Index of every page on this site: llms.txt
All skills
comet-ml avatar

/documentation

@9b3d88e
by Cometcomet-ml/opik23k stars
1,964
Run it yourself

Feature documentation and release notes patterns. Use when documenting changes, writing PR descriptions, or preparing releases.

Use this Skill: https://skilld.dev/gh/comet-ml/opik/documentation

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈36 tokens for metadata: the name and description. ≈1.3k when used: this file.

Description uses 1.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈143 characters, or 1.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 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

  • apps/opik-documentation/documentation/fern/docs-v2/self-host/changelog.mdx - Self-hosted deployment changelog (breaking/critical changes only; the former repo-root CHANGELOG.md was removed)
  • apps/opik-documentation/documentation/fern/docs-v2/changelog/ - Main product docs changelog entries (dated .mdx files)
  • apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/changelog.mdx - Agent Optimizer release changelog
  • apps/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 one surface.
  • Use apps/opik-documentation/documentation/fern/docs-v2/self-host/changelog.mdx only for self-hosted deployment breaking/critical/security-impacting notes.
  • Use apps/opik-documentation/documentation/fern/docs-v2/changelog/*.mdx for general Opik product release notes shown in /docs/opik/changelog.
  • Use apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/changelog.mdx for Agent Optimizer version updates (for example sdks/opik_optimizer releases like 3.1.0).
  • Liquibase changelog.xml files 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.yml before editing.

Images in documentation

  • Use fern/img for documentation images (e.g. apps/opik-documentation/documentation/fern/img/...).
  • Do not use static/img for 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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8mo4 checks · Risk SAFE
  • Gen Agent Trust Hub8mo

    The skill provides templates and guidelines for writing pull request descriptions, changelogs, and feature documentation. It contains no executable code, script logic, or network operations.

  • Socket8mo

    No alerts

  • Snyk8mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

Signed by skilld at 9b3d88e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 months ago

README badge

README badge for comet-ml/opik/documentation