文档审查
- 作者仓库星标 90,172
- 作者仓库 storybook
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @storybookjs · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Documentation Review
## Scope
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`).
## Use This Skill When
- Asked to review, improve, rewrite, or author documentation in `/docs`.
- Asked for advice on page structure, doc type, audience, or content strategy for `/docs`.
- Asked to fix formatting, style, or compliance issues in `/docs`.
## Use a Light Touch When
- The request is a trivial grammar or typo fix that does not need full diagnosis.
- The page is already structurally sound and only needs minor editorial cleanup.
## Reference Files
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 |
### Ownership Rules
- Strategy references do not own formatting or component rules.
- `storybook-style.md` does not own doc-type or intervention logic.
- This file (`SKILL.md`) owns workflow and handoffs only.
## Workflow
Follow this sequence for every request. Steps 1–4 are diagnosis; steps 5–7 are action.
### 1. Determine the Requested Outcome
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":
- If the draft is obviously weak or the ask implies planning → critique-first (lead with diagnosis).
- If the page is decent and the ask implies cleanup → improve-first (lead with edits).
**Default:** When ambiguous, default to `improve`, not `maintenance`.
### 2. Determine the Primary Doc Type
Read the page and classify it using the doc types in `references/docs-strategy.md`:
- `concept` — explains what something is and why it matters
- `task` — walks the reader through accomplishing a goal
- `reference` — lookup for options, API, or config
- `troubleshooting` — diagnose and fix a problem
- `migration` — move from one version or approach to another
- `decision guide` — choose between options
Always 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.
### 3. Diagnose the Draft
Evaluate the page against the quality dimensions in `references/docs-principles.md`, in order:
1. Intent clarity
2. Audience fit
3. Information shape
4. Conceptual clarity
5. Task usability
6. Example quality
7. Economy
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.
### 4. Choose the Intervention Level
Use the thresholds in `references/docs-strategy.md`:
- No structural issues, minor style problems → `maintenance`
- Structure is okay but framing, order, or examples are weak → `improve`
- Structure is wrong for the page's job → `rewrite`
- Page does not exist → `author`
- User wants advice, not edits → `strategy`
**Hard 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.
### 5. Improve or Plan
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:
- Audience
- Page job
- Primary doc type
- Recommended outline
- Split/merge recommendation (if applicable)
- Preserve list (content worth keeping)
- Do **not** edit files or run validation.
When editing, you may also improve docs-owned snippet files in `docs/_snippets/` if example quality depends on them.
### 6. Apply Storybook Style
For edit modes (`maintenance`, `improve`, `rewrite`, `author`):
- Load `references/storybook-style.md` if not already loaded.
- Apply voice, tone, heading, link, component, and frontmatter rules.
- This step is always downstream of structural and editorial work — never the first pass.
### 7. Validate
For edit modes only:
```bash
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.
## Handoffs
- **PR creation:** Do not create a PR automatically. If the user asks for end-to-end execution including a PR, hand off to the `pr` skill.
- **Snippet files:** This skill may edit files in `docs/_snippets/` when example quality requires it, but does not own snippet creation for non-docs purposes.
章节与文件索引
按说明文件中的顺序排列。
适用范围
使用此技能时
使用轻触时
参考文件
所有权规则
文件/命令 -> /docs · docs/_snippets/ · references/ · references/docs-principles.md · references/docs-strategy.md · references/docs-antipatterns.md · references/storybook-style.md · maintenance
内容校验值 -> 6a6ddbd3b3cc
当前原文的自动摘译,尚未人工审校。
适用范围
此技能适用于
/docs中的文档文件和docs/_snippets/中文档拥有的片段文件。不要将此技能用于非文档文件(代码、配置、/docs之外的自述文件)。使用此技能时
要求在
/docs中审查、改进、重写或编写文档。询问有关/docs的页面结构、文档类型、受众或内容策略的建议。要求修复/docs中的格式、样式或合规性问题。使用轻触时
该请求是一个简单的语法或拼写错误修复,不需要完整的诊断。该页面结构已经健全,只需要进行少量的编辑清理。
参考文件
该技能使用
references/下的四个参考文件。仅根据需要按顺序加载它们: 文件 · 拥有 · 何时加载references/docs-principles.md· 北极星、质量维度、双阅读器要求 · 始终 — 首先阅读references/docs-strategy.md· 模式、文档类型、干预阈值、页面形状指导 · 始终 — 第二阅读references/docs-antipatterns.md· 诊断模式和纠正措施 · 诊断薄弱或混乱的草稿时所有权规则
策略引用不拥有格式或组件规则。
storybook-style.md不拥有文档类型或干预逻辑。该文件(SKILL.md)仅拥有工作流程和切换。