documentation

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

Quality

72%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/documentation/SKILL.md

Quality

Content

68%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 tight, repo-specific instruction set that gives exact headings, paths, and rules without padding. Its main weaknesses are the absence of a complete worked example and the topic-based organization, which leaves multi-step processes (PR description drafting, changelog routing) without explicit sequence or validation checkpoints.

Suggestions

Add one complete example PR description and one filled-in changelog entry so the formats are copy-paste ready.

Express the PR-description and changelog tasks as short numbered workflows with explicit checkpoints (e.g. verify headings against CI, confirm surface via docs.yml) instead of scattered rules.

Consolidate the 'Key Files' list and 'Changelog Routing Rules' into a single table to remove repeated paths and tighten the token budget.

Dimension	Reasoning	Score
Conciseness	The body is imperative and dense with repo-specific facts (exact headings, file paths) and never explains concepts Claude already knows. Only a 4 because paths are repeated between 'Key Files' and 'Changelog Routing Rules', and the changelog skeleton plus style section could each be trimmed slightly.	4 / 5
Actionability	Guidance is concrete and executable: the exact CI-enforced headings, the real template path '.github/pull_request_template.md', a fillable changelog skeleton, and routing rules keyed to actual repo paths. Below 5 because there is no complete example PR description or changelog entry to copy from.	4 / 5
Workflow Clarity	The content is organized by topic rather than as a sequenced workflow; the routing section does include one checkpoint ('confirm the surface from docs.yml before editing') but there are no stepwise flows or validate-fix-retry loops for the multi-step tasks described (e.g. changelog entry creation, README re-translation). This matches the score-3 anchor: sequence implied but checkpoints implicit.	3 / 5
Progressive Disclosure	The skill has no bundle files, so everything is in one well-sectioned SKILL.md with clear headers and lean sections. Above 3 because placement is sensible for a ~110-line skill, below 5 because some reference material (changelog templates, routing table) could arguably live in a reference file.	4 / 5
	Total	15 / 20 Passed

Description

61%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 serviceable description with an explicit 'Use when' trigger clause and natural trigger terms, held back by a vague 'what' clause and an over-broad 'documentation' label. It would benefit from naming concrete actions like changelog entry creation or README translation handling.

Suggestions

Replace the vague noun phrase 'Feature documentation and release notes patterns' with 2-3 concrete actions, e.g. 'Write PR descriptions, changelog entries, and feature documentation following repo conventions.'

Add trigger synonyms users actually say — 'changelog', 'release notes', 'docs update' — to improve both specificity and trigger coverage.

Narrow the 'documentation' framing to repo/release documentation to reduce overlap with general writing skills.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Feature documentation and release notes patterns') but 'patterns' is generic phrasing rather than a concrete action; only 'writing PR descriptions' reads as a specific action, and major covered areas (changelogs, READMEs) are absent. It sits between the score-2 anchor ('names the domain but actions are minimal or generic') and score 3, which would require clearer named actions.	2 / 5
Completeness	Both parts are explicit: what ('Feature documentation and release notes patterns') and when ('Use when documenting changes, writing PR descriptions, or preparing releases'). Below 5 because the 'what' is a thin noun phrase rather than a list of concrete capabilities.	4 / 5
Trigger Term Quality	Phrases like 'documenting changes', 'writing PR descriptions', 'preparing releases', and 'release notes' are natural terms users would say. Not a 5 because common synonyms such as 'changelog', 'docs', or file extensions are missing.	4 / 5
Distinctiveness Conflict Risk	'Documentation' is a broad term with overlap risk against general writing or docs-editing skills, though the PR-description and release-notes triggers narrow the niche. It is somewhat specific but could still overlap with similar skills, matching the score-3 anchor.	3 / 5
	Total	13 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: comet-ml/opik
Path: .agents/skills/documentation/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.