文档审查

文档 社区

技能解读

当前原文的自动摘译,尚未人工审校。

适用范围

此技能适用于/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)仅拥有工作流程和切换。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
文档
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@storybookjs · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# 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.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。