// 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.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | docs-review |
| description | 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. |
This skill applies to documentation files in /docs and docs-owned snippet files in docs/_snippets/. Do not use this skill for non-docs files (code, configuration, READMEs outside /docs).
/docs./docs./docs.This skill uses four reference files under references/. Load them in order and only as needed:
| File | Owns | When to Load |
|---|---|---|
references/docs-principles.md | North star, quality dimensions, dual-reader requirement | Always — read first |
references/docs-strategy.md | Modes, doc types, intervention thresholds, page-shape guidance | Always — read second |
references/docs-antipatterns.md | Diagnosis patterns and corrective moves | When diagnosing a weak or confusing draft |
references/storybook-style.md | Editorial, MDX components, frontmatter, formatting, validation rules | In maintenance mode, or as the final pass of edit modes |
storybook-style.md does not own doc-type or intervention logic.SKILL.md) owns workflow and handoffs only.Follow this sequence for every request. Steps 1–4 are diagnosis; steps 5–7 are action.
Read the user's request and map it to a mode:
| Request Pattern | Mode |
|---|---|
| "Fix links, callouts, formatting" | maintenance |
| "Make this clearer", "improve this page" | improve |
| "This doc is a mess; rewrite it" | rewrite |
| "Draft docs for feature X" | author |
| "What kind of page should this be?" | strategy |
| "Review this doc" (unspecified) | hybrid — see below |
Hybrid behavior: For vague asks like "review this doc":
Default: When ambiguous, default to improve, not maintenance.
Read the page and classify it using the doc types in references/docs-strategy.md:
concept — explains what something is and why it matterstask — walks the reader through accomplishing a goalreference — lookup for options, API, or configtroubleshooting — diagnose and fix a problemmigration — move from one version or approach to anotherdecision guide — choose between optionsAlways select one primary type, even if the page contains secondary elements.
After selecting the primary type, identify any secondary sections — sections with their own heading whose content follows a different doc type's shape. Note these for Step 3. See "Common Secondary Sections" in references/docs-strategy.md for expected combinations.
Evaluate the page against the quality dimensions in references/docs-principles.md, in order:
For secondary sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability) against the secondary section's own doc type, not the page's primary type. All other dimensions apply page-wide.
If the page shows signs of structural weakness, load references/docs-antipatterns.md and check for common patterns.
Use the thresholds in references/docs-strategy.md:
maintenanceimproverewriteauthorstrategyHard rule: When the draft is structurally weak, do not stop at sentence-level edits. Reorder, split, replace examples, or rewrite the page shape.
Split/escalation rule: If the dominant job is unclear or the page serves multiple unrelated jobs, switch to strategy mode or recommend a page split before polishing. Well-structured secondary sections (see references/docs-strategy.md) are not a reason to split.
Execute based on the chosen mode:
maintenance: Apply editorial and compliance fixes. Load references/storybook-style.md as primary guide.improve: Strengthen framing, order, explanation, and examples. Keep the page's identity. Use references/storybook-style.md for the final pass.rewrite: Materially replace the page. Preserve sound content; discard or restructure the rest. Use references/storybook-style.md for the final pass.author: Write the page from scratch using the primary doc type's shape as a guide. Use references/storybook-style.md for the final pass.strategy: Return a planning artifact containing:
When editing, you may also improve docs-owned snippet files in docs/_snippets/ if example quality depends on them.
For edit modes (maintenance, improve, rewrite, author):
references/storybook-style.md if not already loaded.For edit modes only:
yarn fmt:write
yarn docs:check
Fix any errors reported by yarn docs:check, then run it again to confirm.
Do not run validation in strategy mode or when no files were edited.
pr skill.docs/_snippets/ when example quality requires it, but does not own snippet creation for non-docs purposes.