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

87%

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

82%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 high-quality, dense instruction body: nearly everything is executable and repo-specific, with concrete templates and an explicit local-verification checklist. Its main costs are length (the component catalog and templates could be split into reference files) and a workflow whose steps are scattered across sections rather than presented as one sequence.

Suggestions

Consolidate the page-creation workflow (create file -> register in docs.yml -> verify with npm run dev -> confirm checklist) into a single numbered sequence near the top, adding a fix-and-retry loop for broken links/components, instead of spreading it across 'Where new pages live', 'Routing', and 'Local verification'.

Move the full Fern MDX component catalog and the changelog/PR entry templates into a references/ file (e.g. references/mdx-components.md), keeping one compact example per component inline in SKILL.md to reduce token load.

Trim low-value meta commentary such as '<Info> — informational, interchangeable with <Note> in practice' and other rationale sentences that add tokens without changing what Claude would do.

Dimension	Reasoning	Score
Conciseness	The body is long (~300 lines) but almost every line carries repo-specific facts Claude cannot know (Fern MDX component syntax, callout selection rules, changelog surfaces, CI-enforced PR headings), so it does not explain concepts Claude already knows. Minor over-explanation could be trimmed (e.g. '<Info>' being 'interchangeable with <Note> in practice', some rationale sentences), placing it below the lean anchor 5 but well above the noticeably-verbose anchor 3.	4 / 5
Actionability	Fully executable throughout: copy-paste-ready frontmatter template, real MDX component examples, the docs.yml page-entry snippet, the changelog entry template, local verification commands ('npm run dev'), and the exact PR headings CI enforces. Specific examples cover the common authoring cases (new page, images, cross-links, changelog, PR description).	5 / 5
Workflow Clarity	The new-page workflow is clearly sequenced — create the file, register it under navigation: in docs.yml, then run the local preview and confirm rendering, links, components, and images — and it warns against inferring routing from folder layout. Checkpoints are present but distributed across sections rather than one numbered sequence, and no explicit fix-and-retry loop is spelled out, so it falls just short of anchor 5.	4 / 5
Progressive Disclosure	No bundle files exist, and the body is organized into clear, navigable sections that push detail to real repo files (fern/docs.yml, .github/pull_request_template.md, anchor pages) — appropriate one-level-deep pointers. However, the full component catalog and the changelog/PR templates are inlined in a ~300-line body that could partly live in a reference file, which keeps it below the ideal-split anchor 5.	4 / 5
	Total	17 / 20 Passed

Description

87%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 description: it names a specific niche, lists multiple concrete capabilities, and includes an explicit 'Use when...' clause with repo-specific trigger phrases. Third-person gerund voice is used correctly and there is no fluff.

Dimension	Reasoning	Score
Specificity	Names the domain (Opik docs site, Fern MDX) and several concrete actions — 'Authoring Fern MDX documentation pages', 'release-note and changelog routing', 'drafting PR descriptions' — with only minor gaps in coverage (e.g. images and cross-link conventions are not named). It lists several specific actions rather than just 1-2, so it sits above anchor 3 but below the fully comprehensive anchor 5.	4 / 5
Completeness	Clearly answers both: the 'what' is stated up front ('Authoring Fern MDX documentation pages for the Opik docs site, plus release-note and changelog routing') and the 'when' is an explicit 'Use when...' clause with concrete trigger phrases ('writing or updating pages under apps/opik-documentation/documentation/fern/, drafting PR descriptions, or picking the right changelog surface'). Nothing is missing or vague.	5 / 5
Trigger Term Quality	Good natural keyword coverage — 'documentation pages', 'docs site', 'changelog', 'release-note', 'PR descriptions', 'fern', 'MDX' — phrased as users would say them. A few natural variations are missing (e.g. '.mdx' extension, 'user guide', 'release notes' as a standalone synonym), keeping it below anchor 5.	4 / 5
Distinctiveness Conflict Risk	A clear niche with distinct triggers: the Opik docs site, the specific path 'apps/opik-documentation/documentation/fern/', and Fern/MDX terminology make it highly unlikely to fire for the wrong skill. Only negligible overlap with generic documentation skills exists.	5 / 5
	Total	18 / 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: 657e319

Reviewed: 3 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.