К основному содержанию
скилл CX Codex

opik-instrument — скилл для Claude Code: трассировка Opik

Скилл opik-instrument для Claude Code добавляет трассировку Opik в существующее приложение и проверяет, что след попал в Opik. Запускается по просьбе инструментировать код или трассировать агента.

Apache-2.0 123 установок ★ 8 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add comet-ml/opik-skills --skill opik-instrument -a claude-code
Открыть на GitHub

Что делает opik-instrument

Скилл добавляет в приложение минимальную трассировку Opik, запускает безопасный пример работы и проверяет, что след появился в Opik. В конце он возвращает ссылку на трассу. Для проекта на Python или TypeScript он определяет язык и LLM-фреймворк, затем выбирает интеграцию фреймворка или добавляет ручные спаны для непокрытых операций.

Перед изменениями скилл проверяет конфигурацию командой opik healthcheck. Если конфигурации нет, запускает opik configure для Python или npx opik-ts configure для TypeScript. Пакет Opik устанавливается через менеджер проекта; lockfile сохраняется. Для поиска интеграций используется соседний скилл opik с файлом references/integrations.md, а если файла нет — документация Opik. Нужен проект на Python или TypeScript; если безопасный запуск требует ключа провайдера LLM, например OPENAI_API_KEY, без него проверка останавливается.

Какие задачи решает

  • добавить трассировку Opik в существующее приложение
  • подключить нативную интеграцию для LLM-фреймворка
  • проверить, что тестовый запуск создал трассу в Opik
  • найти операцию, которую нужно покрыть ручным спаном

Примеры запросов агенту

  • Добавь трассировку Opik в это приложение и проверь тестовый запуск.
  • Инструментируй агента в src/agent.py и верни ссылку на трассу.
  • Подключи наблюдаемость к приложению на TypeScript через Opik.

Как установить opik-instrument

1Через Skills CLI (Vercel)

npx skills add comet-ml/opik-skills --skill opik-instrument -a claude-code

2Вручную: положить файлы

~/.claude/skills/opik-instrument/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/opik-instrument/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об opik-instrument

Как установить opik-instrument в Claude Code?

Выполни npx skills add comet-ml/opik-skills --skill opik-instrument -a claude-code. Файл скилла появится по пути ~/.claude/skills/opik-instrument/SKILL.md.

Что делает opik-instrument?

Скилл добавляет трассировку Opik в существующий проект, запускает безопасный рабочий путь и проверяет поступление трассы. После проверки он возвращает ссылку на неё.

Что нужно для работы opik-instrument?

Нужен проект на Python или TypeScript и настроенная конфигурация Opik; её можно создать через opik configure или npx opik-ts configure. Для интеграций используется соседний скилл opik либо документация Opik. Если безопасный запуск обращается к LLM-провайдеру, потребуется его ключ, например OPENAI_API_KEY.

Исходный текст

SKILL.md · Apache-2.0
---
name: opik-instrument
description: Add Opik tracing to an existing app and verify a real trace lands. Installs the Opik package, detects the language and LLM framework, adds the minimum tracing, runs a safe representative path, confirms a trace in Opik, and returns the trace link. Use for "instrument my code", "add opik tracing", "add observability", "trace my agent". Not for building a new app from scratch, or a review-only pass with no code changes.
compatibility: Tested with Claude Code; works with any Agent Skills-compatible host (Cursor, VS Code Copilot, Codex). Requires a Python or TypeScript project. Install the `opik` skill alongside this one — it holds the shared SDK and integration references; without it, this skill falls back to the public docs.
allowed-tools:
  - Read
  - Edit
  - Write
  - Grep
  - Glob
  - Bash
metadata:
  last_updated: "2026-08-05"
  source_commit: "2.0.0"
  argument-hint: "[optional: file or directory path]"
---

# Instrument — Add Opik Tracing and Verify a Real Trace

**Definition of done:** a representative, safely-executed path produces a trace that is confirmed in Opik and a direct trace link is returned. If verification can't be completed safely or autonomously, stop at the **first** genuine blocker and return **exactly one** concrete next step. Code edits alone are not success.

Operate: **opinionated in execution, conservative in code changes, automatic in routine decisions, uncompromising about verifying value — but never by running something unsafe.**

## Inputs

The entry point is just `/opik-instrument` (optionally `/opik-instrument <path>`). Infer everything else; treat these only as **optional overrides** the user may pass, never as required setup:

- target path (default: project root) · project name (default: inferred from the repo) · run command (default: an inferred safe path) · `migrate_prompts` (default: **false**).

Never turn inference into a questionnaire. Ask only when you hit a genuine, non-inferable blocker (see **Blockers**).

## Activation — the only in-scope work

### 1. Configure Opik (one source of truth)
- If `~/.opik.config` exists or `OPIK_API_KEY` is set, use it as-is.
- Otherwise run the official flow: `opik configure` (Python) / `npx opik-ts configure` (TypeScript).
- **Verify the config before instrumenting:** run `opik healthcheck` — it validates the config, the install, and backend/workspace reachability. If it fails, stop at that Blocker and fix config or connectivity before adding any tracing.
- Only add project-local `.env` vars if the project **already** uses that pattern. Never introduce a second config mechanism; never copy secret values between mechanisms.

### 2. Detect language & framework
Python (`*.py`, `pyproject.toml`) or TypeScript (`*.ts`, `package.json`). Identify the LLM framework from imports and pick its integration:

| Import | Integration |
|---|---|
| `openai` / `anthropic` | `track_openai` / `track_anthropic` |
| `langchain` / `langgraph` | `OpikTracer` callback |
| `crewai` / `dspy` / google-genai / bedrock / `llama_index` / `litellm` | `track_crewai` / `OpikCallback` / `track_genai` / `track_bedrock` / `LlamaIndexCallbackHandler` / `OpikLogger` |
| TS: `opik-openai` / `opik-vercel` / `opik-langchain` | `trackOpenAI` / `OpikExporter` / `OpikCallbackHandler` |

Full list: read `../opik/references/integrations.md` (the `opik` skill, installed beside this one). If that file isn't there, read <https://www.comet.com/docs/opik/integrations/overview> — never settle for manual spans on a framework that has a native integration just because the reference was unreachable. If the project is **already instrumented**, audit and add only what's missing — do not re-instrument.

### 3. Add the minimum tracing
Decision policy, in order:
1. Prefer the **framework-native integration** for provider LLM spans.
2. Add manual `@opik.track` spans only for orchestration/tools the integration doesn't cover (`type="tool"` / `"llm"` / `"guardrail"`). A bare `@opik.track` produces the default span type, **`general`** — the right choice for an entrypoint/orchestrator.
3. Never instrument the same operation twice (no `@opik.track(type="llm")` on top of `track_openai`).
4. Mark **one entrypoint per independently-runnable agent/service** — not necessarily one per repo.
5. Decorator order relative to framework decorators (e.g. `@app.route`) is **framework-dependent** — verify per framework; do not assume a universal order.
6. Scripts: flush at the end (`opik.flush_tracker()` / `await client.flush()`). LiteLLM inside `@opik.track`: pass `metadata={"opik": {"current_span_data": get_current_span_data()}}` or traces orphan.

Make the **smallest change** that lets one representative path emit a trace.

### 4. Install the Opik package (by default)
Add **only** the required Opik package(s) via the repo's detected package manager (pip / uv / poetry / npm / pnpm / yarn), through normal project conventions. **Preserve the lockfile**; do not run generic upgrades; do not install globally; treat unusual lifecycle scripts cautiously. Surface it as a change (e.g. "added `opik` to `pyproject.toml`"). If the environment blocks installation → **Blocker** with the one exact command.

### 5. Run a safe representative path
Infer a safe command — prefer an existing **test, example, or dev script**, then a bounded single-request entrypoint. **Never** run anything that looks like production or does irreversible/expensive work (writes, emails, purchases, mass API calls). If no safe path is inferable → **Blocker** ("which dev command safely exercises this agent?"). Print the command, then run it.

If the run needs an **LLM provider credential** (e.g. `OPENAI_API_KEY`) and it's absent, that's a Blocker — the app can't produce a trace. Note some SDK clients raise at **construction** (module load), before any span runs, so there is **no partial trace** to wait on: return blocked with the one next step, don't wait on a flush that never happened.

### 6. Verify ingestion
Confirm a trace actually arrived — don't assume. **Prefer the SDK for verification**: it's already installed as part of instrumenting (zero extra moving parts), whereas the Opik MCP is optional and may not be connected.

```python
import opik
client = opik.Opik()

tid = "<trace_id>"                          # the tracer logs a trace URL/id when the run flushes — use that
detail = client.get_trace_content(tid)      # TracePublic: exposes project_id, NOT project_name (accessing .project_name raises)
project = client.rest_client.projects.get_project_by_id(detail.project_id).name
spans = client.search_spans(project_name=project, trace_id=tid)   # SEPARATE call; without project_name it searches the default project and returns nothing
# Reconstruct the tree via each span's parent_span_id (the root span has none); check the expected types (general -> tool/llm).
```

To find the newest trace instead of using a known id, use the client's trace search (e.g. `search_traces`) scoped to the project. Optionally, if the Opik MCP is connected, `list` recent traces then `read` the newest.

Traces are asynchronous — allow a few seconds after the run and make sure the flush ran.

### 7. Report
Return a short human result + the trace link (see **Output**), then make the single expansion offer.

## Blockers

When you genuinely can't proceed, stop at the **earliest** blocker and return **exactly one** next step — never a checklist — and still report the changes already made. Examples:
- "Run `opik configure`, then rerun `/opik-instrument`."
- "Install dependencies with `uv sync`, then rerun `/opik-instrument`."
- "Which dev command safely exercises this agent?"
- "Instrumented and installed, but the run needs a provider credential — set `OPENAI_API_KEY` (or the relevant provider key) and rerun."
- "Instrumented and ran, but this environment can't query Opik — open the project and confirm trace `<id>` arrived."

## Expansion — after the trace lands (one offer, not a funnel)

Do **not** migrate prompts, add threading, or broaden spans during activation. After verification, make a **single consolidated offer** of what you found, e.g.:

> Tracing is verified. I also found ways to deepen it: 3 Prompt Library candidates, missing conversation threading, and 2 untraced tools. Expand?

## Output

**User-facing:** a short human message — what was instrumented, the trace link, and the one expansion offer (or, if blocked, the single next step plus what changed). Not raw JSON.

**Underneath** (for composition / evals), a small state model:
- `status`: `verified` | `blocked` | `already_verified` | `unsupported`
- `changes`: `files_changed`, `dependency_added`, `config_source`, `entrypoints_instrumented`, `integrations_added`
- `verification`: `command_run`, `trace_id`, `trace_url`
- `blocker`: `reason`, `next_step`
- `expansion_opportunities`: `prompts`, `threads`, `spans`

Invariants: `verified` must carry a `trace_id`/`trace_url`; `blocked` must carry exactly one `next_step` **and** still report `changes`; `already_verified` = existing instrumentation exercised and confirmed; `unsupported` explains the unsupported language/shape and **modifies nothing**.

## Examples

**Normal — no LLM framework.** A Python script with a `retrieve()` tool and a local `generate()`. No provider to wrap → add `@opik.track(type="tool")` on `retrieve`, bare `@opik.track` (→ `general`) on the entrypoint, flush in `__main__`; `uv add opik`; run it; confirm the `general → tool → llm` trace via the SDK; return the link. → **`verified`**.

**Framework — OpenAI.** `from openai import OpenAI`. Use the native integration: `client = track_openai(OpenAI())`; **leave the LLM-calling function undecorated** (the integration traces it); mark the entrypoint; install `opik`; run. If `OPENAI_API_KEY` is missing, `OpenAI()` raises at construction → **`blocked`**: "set `OPENAI_API_KEY`, then rerun" (report the edits already made).

**Already instrumented.** `@opik.track` / `track_openai` already present. Audit only — add a missing entrypoint or flush, do **not** re-instrument; run + verify. → **`already_verified`**.

## Anti-patterns
Double-wrapping (integration + manual span on the same call); orphaned LiteLLM traces (missing `current_span_data`); missing flush in scripts; overwriting or duplicating config; **running an unsafe/production path just to force a trace**; broad dependency upgrades when only `opik` is needed; migrating prompts during activation.

## References

SDK detail lives in the `opik` skill, installed beside this one. Read the files directly — paths are relative to this file: `../opik/references/tracing-python.md`, `../opik/references/tracing-typescript.md`, `../opik/references/integrations.md`, `../opik/references/observability.md`. If your host lays skills out differently, locate the `opik` skill's `references/` directory.

If the `opik` skill isn't installed, say so in the report and use <https://www.comet.com/docs/opik/> rather than working from memory.

© comet-ml · Apache-2.0 · comet-ml/opik-skills

Похожие скиллы

Каталог скиллов SKILL.md →
opik akillness Помогает настроить Opik для трассировки вызовов LLM, оценки ответов и мониторинга. С его помощью проверяют качество промптов и экспериментов. CX Codex +1 146установок instrument-events amplitude Скилл instrument-events превращает YAML с кандидатами в события в план инструментирования: где именно в коде поставить вызовы трекинга и какие свойства передавать. CX Codex +1 65 900установок launchdarkly-metric-instrument launchdarkly Скилл launchdarkly-metric-instrument для Claude Code добавляет вызов track() в кодовую базу, чтобы отправлять событие метрики в LaunchDarkly. Он также помогает проверить поток событий. CX Codex +1 3 300установок instrument-data-to-allotrope официальный anthropics Скилл instrument-data-to-allotrope для Claude Code преобразует файлы лабораторных приборов в Allotrope Simple Model (ASM) для LIMS и хранилищ данных. Определяет тип прибора и выдаёт ASM JSON, CSV и код парсера. CX Codex +1 2 500установок sentry-instrument getsentry Скилл sentry-instrument проводит агента по шагам: определяет платформу, ставит SDK Sentry и подключает нужный сигнал — от ошибок до AI-мониторинга. CX Codex +1 2 000установок Comet Opik официальный github Субагент Comet Opik для GitHub Copilot, который подключает Opik через MCP: версионирует промпты, разбирает трейсы и метрики LLM-приложений. CX Codex +1 ★ 41 430звёзд репо

Из того же набора5

Спонсоры проекта

Компании, которые помогают держать аналитику открытой