Documentation
BusinessdocumentationDocumentation is an Agent Skill for business published in the comet-ml/opik repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Feature documentation and release notes patterns. Use when documenting changes, writing PR descriptions, or preparing releases.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/comet-ml/opik/blob/HEAD/.agents/skills/documentation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/documentation, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Documentation
PR Description
## Summary
- What this PR does (bullet points)
## Test Plan
- How to verify it works
## Related Issues
- Resolves #123
Changelog Entry
### [VERSION] - [DATE]
#### New Features
- **Feature Name**: Brief description
#### Improvements
- **Improvement**: What changed and why
#### Bug Fixes
- **Fix**: What was broken (#issue)
#### Breaking Changes
- **Change**: What breaks, migration steps
Feature Documentation
When documenting a feature, cover:
User Impact
- What capability does this add?
- How do users access it?
Technical Changes
- API changes (endpoints, params)
- SDK changes (new methods)
- Database migrations
- Config changes
Breaking Changes (if any)
- What breaks
- Migration steps
Key Files
CHANGELOG.md- Self-hosted deployment changelog (breaking/critical changes only)apps/opik-documentation/documentation/fern/docs/changelog/- Main product docs changelog entries (dated.mdxfiles)apps/opik-documentation/documentation/fern/docs/agent_optimization/getting_started/changelog.mdx- Agent Optimizer release changelogapps/opik-documentation/documentation/fern/docs.yml- Docs routing/navigation source of truth for changelog surfaces.github/release-drafter.yml- Release template
Changelog Routing Rules
- Pick the changelog target by scope; do not default everything to root
CHANGELOG.md. - Use
CHANGELOG.mdonly for self-hosted deployment breaking/critical/security-impacting notes. - Use
apps/opik-documentation/documentation/fern/docs/changelog/*.mdxfor general Opik product release notes shown in/docs/opik/changelog. - Use
apps/opik-documentation/documentation/fern/docs/agent_optimization/getting_started/changelog.mdxfor Agent Optimizer version updates (for examplesdks/opik_optimizerreleases like3.1.0). - Liquibase
changelog.xmlfiles are migration manifests, not user-facing release-note changelogs. - If unsure where an entry belongs, confirm the surface from
apps/opik-documentation/documentation/fern/docs.ymlbefore editing.
Images in documentation
- Use
fern/imgfor documentation images (e.g.apps/opik-documentation/documentation/fern/img/...). - Do not use
static/imgfor new assets; it is a legacy folder used by external integrations and cannot be deleted. - Reference images in docs as
/img/...(e.g./img/tracing/openai_integration.png). - In repos that define
docs.yaml/docs.yml, treat that file as the routing source of truth; do not assume URLs mirror directory layout.
Internationalized READMEs
Non-English README files (readme_CN.md, readme_JP.md, readme_KO.md, readme_PT_BR.md) are AI machine-translated from the English README.md.
- Each non-English README must have a notice at the top (as a blockquote) warning that the file is AI-translated and welcoming improvements.
- When the English README is updated with significant content changes, re-translate the affected non-English READMEs using AI and update accordingly.
- Do not manually edit translated READMEs for content changes; update the English source and re-translate.
Style
- User perspective, not implementation details
- Specific (version numbers, dates)
- Code examples for API/SDK changes
- Concise - link to docs, don't duplicate