[NA] [DOCS] [FE] Point the Opik skill prompts at /opik-instrument - #8052
Conversation
The published skills are being namespaced under an `opik-` prefix (comet-ml/opik-mcp#171), because `instrument` and `evaluate` claimed unnamespaced names in a global namespace and the installer resolves a collision by overwriting without a prompt or a backup. Every place that tells a user to type `/instrument` therefore stops working. Worse, it stops working silently: a user who has any other `instrument` skill installed gets that one instead, which is the collision this rename exists to prevent — triggered by our own onboarding copy. Ollie's `/instrument` sidebar action is a different command in a different namespace and is deliberately untouched, along with its e2e coverage. One non-docs file is included: the onboarding dialog's copy-button prompt in `InstallWithAITab.tsx`. It is the same defect on the highest-traffic surface, and leaving it would have the product's own copy button contradict the docs. Merge after the pack sync to comet-ml/opik-skills lands, not before — until then `/opik-instrument` does not exist yet. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
documentation
|
🌿 Preview your docs: https://opik-preview-01a04835-fbef-77fb-8ef3-6ad9322f680d.docs.buildwithfern.com/docs/opik No broken links found Unverified links (timeout / rate-limited / server error — not failing the check)• https://aistudio.google.com/apikey (401) 📌 Results for commit 1fb4432 |
⏱️ pre-commit per-hook timing
⏭️ 42 skipped (no matching files changed)
|
alexkuzmik
changed the title
/opik-instrument![baz-reviewer[bot]](https://avatars.githubusercontent.com/in/933528?s=60&v=4){kind=small}
| Once the skill is installed, you can integrate with Opik using the following prompt: | ||
| ``` | ||
| Version my prompts in Opik using the /instrument command. | ||
| Version my prompts in Opik using the /opik-instrument command. |
There was a problem hiding this comment.
Prompt versioning routes to tracing-only skill
The prompt-library onboarding routes Version my prompts in Opik using the /opik-instrument command to /opik-instrument, whose default migrate_prompts is false and whose activation excludes prompt migration, so users get repository instrumentation instead of prompt versioning and lose the former /instrument outcome. The same wording appears across the other documentation and onboarding call sites; should we route it to the prompt-library opik skill, or add and synchronize an explicit prompt-only migration mode?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
`apps/opik-documentation/documentation/fern/docs-v2/prompt_engineering/getting-started.mdx`
around lines 35-35, update the prompt-library onboarding instruction in the integration
example so it invokes the dedicated `opik` prompt-library skill instead of
`/opik-instrument`. Ensure the wording explicitly requests prompt versioning and does
not route users through the repository-instrumentation workflow, which does not migrate
prompts by default.
| Ask your coding agent to instrument your code: | ||
| ``` | ||
| Instrument my agent with Opik using the /instrument command. | ||
| Instrument my agent with Opik using the /opik-instrument command. |
There was a problem hiding this comment.
Onboarding fails before skill release
The new /opik-instrument instruction and prompt-engineering command addition land before the commands exist, so onboarding fails with unknown commands; according to the PR description, should we merge the matching observability/overview.mdx and quickstart.mdx changes atomically with opik-mcp#171 and the subsequent opik-skills pack sync, or retain /instrument until the renamed skill is available?
Want Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents
Before applying, verify this suggestion against the current code. In
`apps/opik-documentation/documentation/fern/docs-v2/observability/getting-started.mdx`
around lines 45-45, update the coding-agent instrumentation instruction so it does not
reference `/opik-instrument` before that skill is available. Restore `/instrument` until
the dependent `opik-mcp#171` and `opik-skills` releases are published, and apply the
same sequencing fix to the identical instructions in `observability/overview.mdx` and
`quickstart.mdx` (including the prompt-engineering command addition), or coordinate all
documentation changes atomically with the skill release.
|
No test needed here. Five of the six files are docs, and the one product file is a single token inside a copy-to-clipboard string on the Install with AI tab ( Advisory, from the QA test radar. Nothing here blocks this PR, and anything it proposes is a draft for review. |
2 participants
Details
The published Opik skills are being namespaced under an
opik-prefix in comet-ml/opik-mcp#171, becauseevaluateandinstrumentclaimed unnamespaced names in a global namespace where the installer resolves a collision by overwriting — no prompt, no diff, no backup. Once that lands, every place telling a user to type/instrumentbreaks, and breaks silently: a user who has any otherinstrumentskill installed gets that one instead, which is the exact collision the rename exists to prevent, triggered by our own onboarding copy.This replaces
using the /instrument commandwithusing the /opik-instrument commandin the five places that refer to the skill, plus the onboarding dialog's copy-button prompt.fern/docs-v2/quickstart.mdx,observability/getting-started.mdx,observability/overview.mdx,prompt_engineering/getting-started.mdx— the four user-facing pages.agents/skills/write-docs/SKILL.md— the canonical snippet docs authors copy; without it the old command regenerates into new pagesapps/opik-frontend/src/v2/pages-shared/onboarding/InstallWithAITab.tsx— the only non-docs file. Same defect on the highest-traffic surface; leaving it would have the product's own copy button contradict the docs beside it. Flagging since it routes to different reviewers — happy to split it out.Ollie's
/instrumentis a different command and is deliberately untouched — it's an action button in the Ollie sidebar on the Agent Runner page, unrelated to the skill pack. Left alone:AgentRunnerEmptyState.tsx,tests_end_to_end/e2e/pom/ollie.page.ts,e2e/tests/ollie/ollie-connect.spec.ts,e2e/agents/README.md. Also untouched: OpenTelemetryinstrumentation/paths across the integrations docs, and the SDK's ownevaluation/evaluate.ts.Related but not resolved here: OPIK_7621.
Change checklist
Issues
[NA]— no ticket; this is follow-on cleanup for the skills rename in feat(skills): namespace published skills under anopik-prefix opik-mcp#171. Happy to file one or retitle with a key if preferred.AI-WATERMARK
AI-WATERMARK: yes
/instrumentoccurrences belong to the skill versus Ollie's separate sidebar command; the reasoning and the full untouched list are spelled out above so that call can be checked directly.Testing
Scoping was verified mechanically rather than by a test run, since the change is six text edits with no logic:
grep -rl "using the /instrument command"before the edit returned exactly the six files changed here, andgrep -con both Ollie sites returned0— so the pattern provably separates the skill's command from Ollie's.grep -rn "/instrument\b"across*.mdx/*.md/*.ts/*.tsxreturns only Ollie sites and OpenTelemetry package paths.grepforInstallWithAITab/Instrument my agentacross*.test.*,*.spec.*,*.snapfound no test or snapshot asserting the prompt string.CI on this branch:
lint (🌐 eslint — frontend)passed;lint (🌐 typecheck — frontend)andTest on Node 20were still running at the time of writing.Not run locally, with reasons:
Unrelated pre-existing CI failure:
Checks with ai-spend plugin(Frontend Private Plugin Checks) fails with prettier errors insrc/plugins/ai-spend/lib/policySettings.test.tsandmanifest.ts, neither of which this PR touches. That workflow has been failing on unrelated branches since ~10:00 today (jacquesverre/OPIK-8105-quick-filter-view-handoff,andreic/OPIK-8102-gemini-thinking-config) and last succeeded at 03:29. Not introduced here.Documentation
This PR is the documentation change. No further docs updates are needed — the install command itself (
npx skills add comet-ml/opik-skills) is unchanged, since only the skill names inside the pack move, not the pack name.One thing left alone deliberately:
prompt_engineering/getting-started.mdxnow reads "Version my prompts in Opik using the /opik-instrument command." Pairing prompt versioning with the instrument skill is pre-existing and not wrong (the skill takes amigrate_promptsoption), but it reads oddly. I did the mechanical rename only rather than rewriting the guidance — worth a separate look.