write-docs

Authoring Fern MDX documentation pages for the Opik docs site, plus release-note and changelog routing. Use when writing or updating pages under apps/opik-documentation/documentation/fern/, drafting PR descriptions, or picking the right changelog surface.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

86%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, highly actionable docs-authoring skill with real templates and examples and clear verification steps. The main lever is tightening the callout/changelog prose; an explicit fix-then-revalidate loop for renames/changelog routing would lift workflow_clarity to 5.

Suggestions

Tighten the callout taxonomy and changelog bullet lists — the MDX examples already convey intent, so the prose can drop a sentence or two for token efficiency.

Add an explicit validate-then-revalidate feedback loop for rename/changelog-surface decisions (e.g. 'after editing docs.yml navigation, re-run the link checker; if 404s, fix the slug and re-run') to clear the workflow_clarity cap.

For frontmatter routing, surface the 'consult navigation: in docs.yml, then verify with npm run dev' pairing as one numbered checkpoint rather than two separate sections.

Dimension	Reasoning	Score
Conciseness	Mostly lean and assumes competence (frontmatter template, component one-liners, 'Never' rules), with a few sections that could be trimmed — e.g. the callout taxonomy and changelog bullets restate intent the examples already show.	4 / 5
Actionability	Fully executable throughout: real frontmatter/YAML templates, real MDX component examples taken from the repo, concrete install/verify commands, and explicit path rules — copy-paste ready for the common cases.	5 / 5
Workflow Clarity	Clear sequences with validation checkpoints (Local verification lists frontmatter/component/link/image checks; PR template enforces exact headings), but the destructive/batch-adjacent routing choices (renames, changelog surface selection) lack an explicit validate-then-fix feedback loop, keeping it just below 5.	4 / 5
Progressive Disclosure	A single content surface with well-organized, clearly headed sections; no nested/external reference indirection (Key files are inline pointers, not multi-level hops), and for a no-bundle skill this is appropriately structured and navigable.	5 / 5
	Total	18 / 20 Passed

Description

91%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, third-person description that names the niche, concrete actions, and explicit use-when triggers tied to real paths and surfaces. Minor specificity gaps (images, cross-links) keep it just short of a perfect specificity anchor.

Dimension	Reasoning	Score
Specificity	Names the domain (Fern MDX docs, changelog routing) and several concrete actions — authoring pages, drafting PR descriptions, picking the right changelog surface — with only minor coverage gaps around e.g. image handling.	4 / 5
Completeness	Explicit 'what' (authoring Fern MDX pages, release-note and changelog routing) and an explicit 'Use when...' trigger clause with concrete cases, satisfying both halves concretely.	5 / 5
Trigger Term Quality	Comprehensive natural triggers ('writing or updating pages under apps/opik-documentation/documentation/fern/', 'drafting PR descriptions', 'changelog'), covering the phrases a user would actually say plus the concrete path/file signal.	5 / 5
Distinctiveness Conflict Risk	A clear niche (the Opik Fern docs site, fern/docs-v2, changelog surfaces) with highly specific triggers, making overlap with unrelated skills minimal.	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 4 suspicious	Warning

	Total	15 / 16 Passed

Repository: comet-ml/opik
Path: .agents/skills/write-docs/SKILL.md
Commit: 50de943

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.