docs-review

Review, improve, rewrite, author, or plan Storybook documentation in /docs. Use this when asked to review docs, improve a page, rewrite documentation, draft new docs, or advise on docs strategy.

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

85%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-engineered instruction skill: tight workflow with validation feedback loops, clean progressive disclosure, and concrete decision tables. The main weaknesses are minor duplication of content already in docs-strategy.md and the absence of worked output examples.

Suggestions

In Step 2 and Step 4, replace the inline doc-type list and intervention thresholds with brief pointers to references/docs-strategy.md to remove duplication and tighten the body.

Add a short worked example of the strategy-mode planning artifact (audience, page job, primary doc type, outline, preserve list) so the expected output shape is unambiguous.

Consider adding "edit", "fix formatting", and "update" as trigger synonyms in the description's when-clause to broaden natural-term coverage.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-structured with no concept over-explanation, but the doc-type list (Step 2) and intervention thresholds (Step 4) duplicate content already owned by references/docs-strategy.md and could be trimmed to pointers.	4 / 5
Actionability	Concrete decision tables (request→mode, doc types, intervention thresholds) and copy-paste validation commands give mostly executable guidance, but there are no worked examples of outputs such as a sample strategy artifact or before/after rewrite.	4 / 5
Workflow Clarity	A clear 7-step sequence splits diagnosis (1–4) from action (5–7) and includes an explicit validation step with a fix→re-run feedback loop ("Fix any errors reported by yarn docs:check, then run it again to confirm").	5 / 5
Progressive Disclosure	The SKILL.md is a concise overview pointing to four one-level-deep reference files via a clear File/Owns/When-to-Load table with load-order guidance; all referenced files exist and ownership rules prevent overlap.	5 / 5
	Total	18 / 20 Passed

Description

92%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, well-scoped description that clearly answers both what the skill does and when to use it, with concrete action verbs and natural trigger phrases. The only gap is a few missing everyday synonyms like "edit" or "fix formatting".

Dimension	Reasoning	Score
Specificity	Lists five concrete actions ("Review, improve, rewrite, author, or plan") over a named domain ("Storybook documentation in /docs"), giving comprehensive coverage of the skill's action space.	5 / 5
Completeness	Explicitly states what the skill does and follows with a concrete "Use this when asked to…" clause enumerating trigger phrases, matching the 5-anchor pattern.	5 / 5
Trigger Term Quality	Natural trigger phrases ("review docs", "improve a page", "rewrite documentation", "draft new docs", "advise on docs strategy") cover the main request patterns, but a few common synonyms ("edit", "fix formatting", "update") are missing.	4 / 5
Distinctiveness Conflict Risk	Scoped tightly to Storybook documentation in /docs with distinct action triggers, giving it a clear niche and minimal overlap with other skills.	5 / 5
	Total	19 / 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: storybookjs/storybook
Path: .agents/skills/docs-review/SKILL.md
Commit: 8403f24

Reviewed: about 16 hours 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.