Technical Writing
frappe/skills
Write prose in "Simplified Technical English". An agent skill from frappe/skills.
Rules for writing PR descriptions, changelog entries and feature documentation in the Opik repository, including the exact headings that CI requires.
Install Opik Documentation Patterns
$ npx skills add comet-ml/opik --skill documentation -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install comet-ml/opik documentation --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/comet-ml/opik.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/documentation .claude/skills/documentation && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "documentation" agent skill from https://github.com/comet-ml/opik/tree/main/.agents/skills/documentation into .claude/skills/documentation/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/comet-ml/opik/tree/main/.agents/skills/documentationType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add comet-ml/opik --skill documentation -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install comet-ml/opik documentation --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/comet-ml/opik.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/documentation .agents/skills/documentation && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "documentation" agent skill from https://github.com/comet-ml/opik/tree/main/.agents/skills/documentation into .agents/skills/documentation/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add comet-ml/opik --skill documentation -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install comet-ml/opik documentation --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/comet-ml/opik.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/documentation .cursor/skills/documentation && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "documentation" agent skill from https://github.com/comet-ml/opik/tree/main/.agents/skills/documentation into .cursor/skills/documentation/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/comet-ml/opik.git --path .agents/skills/documentation--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add comet-ml/opik --skill documentation -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install comet-ml/opik documentation --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/comet-ml/opik.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/documentation .gemini/skills/documentation && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "documentation" agent skill from https://github.com/comet-ml/opik/tree/main/.agents/skills/documentation into .gemini/skills/documentation/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install comet-ml/opik documentationInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add comet-ml/opik --skill documentation -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/comet-ml/opik.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/documentation .github/skills/documentation && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "documentation" agent skill from https://github.com/comet-ml/opik/tree/main/.agents/skills/documentation into .github/skills/documentation/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add comet-ml/opik --skill documentation -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install comet-ml/opik documentation --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/comet-ml/opik.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/documentation .opencode/skills/documentation && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "documentation" agent skill from https://github.com/comet-ml/opik/tree/main/.agents/skills/documentation into .opencode/skills/documentation/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
documentation- GitHub stars
- 22k
- Token cost
- ~1.3k tokens
- SKILL.md length
- 579 words
- Files
- 1
- Skills in repo
- 19
- Repo updated
- First seen
- Licence
- Apache-2.0
At a glance
Rules for writing PR descriptions, changelog entries and feature documentation in the Opik repository, including the exact headings that CI requires.
- Writing a pull request description that passes the repository's lint check
- SKILL.md covers PR Description, Changelog Entry, Feature Documentation and Key Files, plus 4 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
- Adding a changelog entry for a release
What it does
Every pull request description starts from the repository template at .github/pull_request_template.md, read in full, because CI fails a PR that lacks the required headings: Details, Change checklist, Issues, Testing and Documentation. The AI-WATERMARK section must also be filled in, sections that do not apply get N/A, and headings are never deleted or swapped for another structure.
Details should say what changes for a user, in 3-10 short bullets stated as fact, without motivation or approach summaries. Before and after lists suit a changed behavior, a flat list suits a new capability, and a refactor gets one or two lines. The skill also gives a changelog entry format and a feature documentation outline covering user impact, technical changes such as API, SDK, migration and config changes, and breaking changes with migration steps.
When your agent uses it
- Writing a pull request description that passes the repository's lint check
- Adding a changelog entry for a release
- Documenting a new feature with its API and migration changes
Example prompts
- “Draft the PR description for this branch using the repository template.”
- “Write a changelog entry for the new evaluation metrics feature.”
- “Document the breaking change in the SDK, with migration steps.”
Requirements
- The Opik repository with its pull request template
What it can do on your machine
Read from SKILL.md and the folder at commit f217a86. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Opik Documentation Patterns loads about 1.3k tokens when it runs. Until then it costs about 35 tokens; SKILL.md has 579 words of instructions outside code blocks.
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
Auto-check passed
The automated check found no risky patterns in SKILL.md.
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 at commit f217a86, republished under its Apache-2.0 licence (© comet-ml). 579 words, ~1,331 tokens.
Download SKILL.mdSave it as
.claude/skills/documentation/SKILL.md (or your agent's skills folder).- name
- documentation
- description
- Feature documentation and release notes patterns. Use when documenting changes, writing PR descriptions, or preparing releases.
Documentation
PR Description
Use the repository template at .github/pull_request_template.md — read the FULL file before drafting (the required sections continue past the first screen). CI (.github/workflows/pr-lint.yml) fails any PR whose description is missing one of these exact headings:
## Details## Change checklist## Issues## Testing## Documentation
Also fill in the template's ## AI-WATERMARK section (yes/no; if yes: Tools, Model(s), Scope, Human verification). Never invent a different structure such as ## Summary / ## Test Plan.
A section that does not apply gets N/A — never delete a heading.
## Details — style
Write what changes for a user. A reviewer reads the diff for the code; this section tells them what is different when they use the product.
- Short. Most PRs need 3–10 bullets. If it runs longer, the section is doing the diff's job — cut it.
- Bullets, not prose paragraphs. One behavior per bullet. Nest one level for sub-cases.
- Authoritative. State what happens: "The run is scored once." Not "This should now mean that the run will be scored once."
- No fluff. No motivation paragraph, no "this PR …", no approach summary, no benefits list, no restating the diff.
- Observable behavior first. What the UI shows, what the API returns, what gets scored, stored or logged. Name a class, method or file only when the behavior makes no sense without it.
Pick the shape that fits the change — do not force one:
- Before / After bullet lists when a behavior changed and the contrast is the point.
- A flat bullet list for a new capability, where there is no "before".
- One or two lines when users cannot see the change (refactor, dependency bump) — say what is unchanged and what improved, then stop.
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 stepsFeature 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
apps/opik-documentation/documentation/fern/docs-v2/self-host/changelog.mdx- Self-hosted deployment changelog (breaking/critical changes only; the former repo-rootCHANGELOG.mdwas removed)apps/opik-documentation/documentation/fern/docs-v2/changelog/- Main product docs changelog entries (dated.mdxfiles)apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/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
Show full SKILL.md (224 more words)Show less
Changelog Routing Rules
- Pick the changelog target by scope; do not default everything to one surface.
- Use
apps/opik-documentation/documentation/fern/docs-v2/self-host/changelog.mdxonly for self-hosted deployment breaking/critical/security-impacting notes. - Use
apps/opik-documentation/documentation/fern/docs-v2/changelog/*.mdxfor general Opik product release notes shown in/docs/opik/changelog. - Use
apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/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_ES.md, readme_FR.md, readme_DE.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
© 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
Just SKILL.md in .agents/skills/documentation of comet-ml/opik.
Open the folder on GitHubat commit f217a86
Compare with similar skills
Opik Documentation Patterns next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Opik Documentation Patterns this skillcomet-ml/opik | 22k | — | ~1.3k | Automated safety check: Pass | Apache-2.0 | |
| Technical Writingfrappe/skills | 146 | — | ~1.1k | Automated safety check: Pass | None | |
| Maintain DisCatSharpAiko-IT-Systems/DisCatSharp | 140 | — | ~1.2k | Automated safety check: Pass | MIT | |
| Writingagentic-community/mcp-gateway-registry | 962 | — | ~3.5k | Automated safety check: Pass | Apache-2.0 | |
| Vibe Slop Filterash1794/vibe-engineering | 162 | — | ~2.3k | Automated safety check: Pass | MIT | |
| Outward Prosestylelint-stylistic/stylelint-stylistic | 106 | — | ~2.9k | Automated safety check: Pass | Custom licence |
Similar skills
Maintain DisCatSharp
Aiko-IT-Systems/DisCatSharp
Guides changes to the DisCatSharp C# Discord library: tracing a payload field through parsing, serialization and caches, then validating across target frameworks.
Writing
agentic-community/mcp-gateway-registry
Write prose people will actually read. An agent skill from agentic-community/mcp-gateway-registry.
Vibe Slop Filter
ash1794/vibe-engineering
Strips AI-generation "smell" from prose before it ships (READMEs, docs, release notes, PR descriptions, posts, emails).
Outward Prose
stylelint-stylistic/stylelint-stylistic
Write a commit body, a changelog entry, a PR body, an issue comment or a code comment so that no sentence in it is a claim nobody ran.
Google Devdocs Style
EpicenterHQ/epicenter
Write and review developer documentation in Google Developer Documentation Style.
More from comet-ml/opik
All 19 skills in this repoAdd Opik Code Quality Hook
comet-ml/opik
Checklist for wiring a new linter into Opik's Code Quality pipeline: the four files to edit, the silent-failure gotchas and the pass/fail verification loop.
Opik Analytics Instrumentation
comet-ml/opik
Shows how to add product analytics events to Opik's frontend, Java backend and Python SDK, all reporting through Segment to PostHog with an opik_ name prefix.
Debugging Opik E2E Tests
comet-ml/opik
Investigates a failed Opik end-to-end test from CI, TestOps or a local run, decides regression versus flake, and proposes a fix without editing tests.
Explore Feature E2E Test
comet-ml/opik
Turns a code change into one committed, passing Playwright end-to-end spec by resolving the change scope and handing authoring to a companion skill.
Opik Local Dev Environment
comet-ml/opik
Starts, rebuilds, and troubleshoots the Opik local dev stack, including an optional Comet Platform integration mode for the Opik team.
OpenTelemetry Pipeline Metrics Spec
comet-ml/opik
Specifies how to instrument an opik-backend pipeline with per-stage OpenTelemetry metrics for throughput, latency, errors and queue delay by workspace.
Related
Categories
Questions about Opik Documentation Patterns
What does Opik Documentation Patterns do?
Rules for writing PR descriptions, changelog entries and feature documentation in the Opik repository, including the exact headings that CI requires. md, read in full, because CI fails a PR that lacks the required headings: Details, Change checklist, Issues, Testing and Documentation. The AI-WATERMARK section must also be filled in, sections that do not apply get N/A, and headings are never deleted or swapped for another structure.
When should I use Opik Documentation Patterns?
Opik Documentation Patterns fits situations like: writing a pull request description that passes the repository's lint check; adding a changelog entry for a release; documenting a new feature with its API and migration changes.
How do I install Opik Documentation Patterns in Claude Code?
Run `npx skills add comet-ml/opik --skill documentation -a claude-code`. Or copy the skill folder (.agents/skills/documentation in comet-ml/opik) into .claude/skills/documentation in your project. Claude Code loads it when a task matches its description.
How do I install Opik Documentation Patterns in Codex?
Run `npx skills add comet-ml/opik --skill documentation -a codex`. Or copy the skill folder (.agents/skills/documentation in comet-ml/opik) into .agents/skills/documentation in your project. Codex loads it when a task matches its description.
Can I use Opik Documentation Patterns in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add comet-ml/opik --skill documentation -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/documentation, .gemini/skills/documentation, .github/skills/documentation and .opencode/skills/documentation in your project.
What does Opik Documentation Patterns need to run?
SKILL.md names no scripts, command-line tools or credentials: Opik Documentation Patterns is instructions for the agent only. Our summary lists: The Opik repository with its pull request template.
Does Opik Documentation Patterns access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Opik Documentation Patterns safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Opik Documentation Patterns use?
Opik Documentation Patterns is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Opik Documentation Patterns use?
About 1.3k tokens (SKILL.md is roughly 5.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Opik Documentation Patterns?
Skills that share tags, products or a category with Opik Documentation Patterns: Technical Writing (frappe/skills, 146 stars), Maintain DisCatSharp (Aiko-IT-Systems/DisCatSharp, 140 stars), Writing (agentic-community/mcp-gateway-registry, 962 stars) and Vibe Slop Filter (ash1794/vibe-engineering, 162 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Opik Documentation Patterns?
comet-ml (a GitHub organization) maintains it in comet-ml/opik, which has 22,412 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 7, 2026.
Source: comet-ml/opik on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.