Opik Explain

What it does

When your agent uses it

• Why did this trace fail
• Explain this trace
• Debug this trace
• Why is my agent slow

Example prompts

• “why did this trace fail”
• “explain this trace”
• “debug this trace”
• “/opik-explain”

Requirements

• Python 3
• A credential in OPIK_API_KEY
• Compatibility (from SKILL.md): Tested with Claude Code; works with any Agent Skills-compatible host (Cursor, VS Code Copilot, Codex). Requires a Python or TypeScript project with Opik configured and at least one trace. Install the `opik` skill alongside this one — it holds the shared SDK and observability references; without it, this skill falls back to the public docs.
• Pre-approved tools (allowed-tools): Read, Grep, Glob, Bash

Workflow steps

4 steps, taken from the step headings in SKILL.md.

1. 1Resolve the target
2. 2Fetch the trace and spans — MCP first, SDK fallback
3. 3Root-cause it
4. 4Report

What it can do on your machine

Read from SKILL.md and the folder at commit e0c2057. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Grep
  • Glob
  • Bash

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships script files (Python), which the agent can run.

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • comet.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • OPIK_API_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Tested with Claude Code; works with any Agent Skills-compatible host (Cursor, VS Code Copilot, Codex). Requires a Python or TypeScript project with Opik configured and at least one trace. Install the `opik` skill alongside this one — it holds the shared SDK and observability references; without it, this skill falls back to the public docs.

  From compatibility in the SKILL.md frontmatter.

Context cost

Opik Explain loads about 2.4k tokens when it runs. Until then it costs about 123 tokens; SKILL.md has 1,012 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~123

When it runs · the whole SKILL.md, loaded when a task matches

~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NotePre-approves every shell command (allowed-tools: Bash)SKILL.md

  allowed-tools: Read, Grep, Glob, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from comet-ml/opik-mcp at commit e0c2057, republished under its Apache-2.0 licence (© comet-ml). 1,012 words, ~2,413 tokens.

name

opik-explain

description

Root-cause a specific Opik trace, or a pattern across traces, and return a grounded explanation. Uses the hosted Opik MCP when it is connected, and falls back to SDK scripting otherwise. Returns the root cause, the evidence spans as clickable Opik UI links, and one suggested next step. Use for "why did this trace fail", "explain this trace", "debug this trace", "why is my agent slow or wrong". Not for adding tracing to an app (use the instrument skill) or for changing code.

allowed-tools

Read, Grep, Glob, Bash

compatibility

Tested with Claude Code; works with any Agent Skills-compatible host (Cursor, VS Code Copilot, Codex). Requires a Python or TypeScript project with Opik configured and at least one trace. Install the `opik` skill alongside this one — it holds the shared SDK and observability references; without it, this skill falls back to the public docs.

metadata.last_updated

2026-09-08

metadata.source_commit

2.0.0

metadata.argument-hint

[trace id, or a description of the behavior to explain]

import opik

client = opik.Opik()

tid = "<trace_id>"
trace = client.get_trace_content(
    tid
)  # TracePublic: exposes project_id, input, output, error info — NOT project_name (accessing .project_name raises)
project = client.rest_client.projects.get_project_by_id(trace.project_id).name
spans = client.search_spans(
    project_name=project, trace_id=tid
)  # spans come from a SEPARATE call, not from the trace object
# ALWAYS pass project_name: without it the SDK searches the configured default project, which
# returns an empty list (or a 404 if that project doesn't exist) even for a valid trace id.
# Reconstruct the tree via each span's parent_span_id (the root span has none).
# Your anchor is the first span that errored, returned wrong output, or dominates the duration.

list(entity_type="trace", project_name="<project>", since="7d",
     filters="error_info is_not_empty", sort="start_time desc")        # error traces
list(entity_type="trace", project_name="<project>", since="7d",
     sort="duration desc")                                             # slow traces (duration in ms)
list(entity_type="trace", project_name="<project>", since="7d",
     filters="feedback_scores.hallucination > 0.5")                    # low-scored traces
list(entity_type="span",  project_name="<project>", since="7d",
     filters='name = "<span name>" AND error_info is_not_empty')       # the shared failing span, across traces

traces = client.search_traces(project_name="<project>", filter_string="error_info is_not_empty")

© comet-ml, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 10 other files in src/opik_mcp/skills/opik-explain of comet-ml/opik-mcp.

• SKILL.md
• evals/.gitignore
• evals/HARNESS.md
• evals/cases.yaml
• evals/fixtures/latency/agent.py
• evals/fixtures/latency/pyproject.toml
• evals/fixtures/toolbug/agent.py
• evals/fixtures/toolbug/pyproject.toml
• evals/grader.py
• evals/metrics.py
• evals/run_evals.py

Open the folder on GitHubat commit e0c2057