docs-writing
Writes and audits technical docs with Diataxis type gating, runnable examples, and 51 documentation rules. Use when asked to "review my docs", "write an API reference", or improve a documentation page. For a whole README use readme-creator; for agent instructions use agents-md.
mblode · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mblode/agent-skills --skill docs-writing技能说明
name: docs-writing description: Writes and audits technical docs with Diataxis type gating, runnable examples, and 51 documentation rules. Use when asked to "review my docs", "write an API reference", or improve a documentation page. For a whole README use readme-creator; for agent instructions use agents-md.
Documentation Writing
- IS: writing and auditing technical documentation quality (Diataxis doc types, voice, structure, clarity, runnable code, formatting, navigation, content hygiene, agent-readable docs) for docs sites, API references, documentation-site tutorials, how-to docs, and existing READMEs.
- IS NOT: editorial blog tutorials or articles (use the external
ghostwriterskill with platformblog), a README from scratch or a whole-README rewrite (usereadme-creator; a README that needs its prose fixed in place stays here), AGENTS.md or CLAUDE.md instructions (useagents-md), marketing and landing-page copy (usecopywriting), or the product's own error strings and CLI output (usedx-audit; this skill covers the docs that describe them).
Mode dispatch
- Reviewing docs? → Audit workflow.
- Writing or rewriting a page? → Writing workflow.
- "Improve" or "fix" docs? → Audit first, then apply fixes yourself.
Classify before anything else
Doc type gates which rules apply, so classify every file first. Use the Diataxis compass: does the page serve action (doing) or cognition (understanding), and is the reader acquiring a skill or applying one?
| Acquisition (learning) | Application (working) | |
|---|---|---|
| Action | Tutorial | How-to guide |
| Cognition | Explanation | Reference |
A page that answers differently for different sections is mixed; structure-diataxis handles the split. Classify by the reader's task, not the filename. A README can orient or reference; a getting-started page can be a tutorial or a goal-directed how-to.
Audit workflow
Track this checklist:
Docs audit progress:
- [ ] Step 1: Scope to changed files unless a full sweep was requested
- [ ] Step 2: Classify each doc with the compass; name the audience
- [ ] Step 3: Run CRITICAL categories (voice-, structure-), skipping rules the type-gating table excludes
- [ ] Step 4: Run HIGH categories (clarity-, code-)
- [ ] Step 5: Run remaining in-scope categories (format-, nav-, scan-, hygiene-, review-)
- [ ] Step 6: Report per the output contract, by severity
Load rule files by category prefix (rules/voice-*.md, then rules/structure-*.md, ...) only for in-scope categories. After applying fixes, rerun the rules that produced findings before finalizing.
Writing workflow
Track this checklist:
Docs writing progress:
- [ ] Step 1: Pick one Diataxis type per file with the compass; name the audience and what they can do afterwards
- [ ] Step 2: Read the defaults bundles (voice-defaults, clarity-defaults, scan-defaults) plus the structure- and code- rules the type-gating table keeps
- [ ] Step 3: Draft: bottom line up front, quick start for getting-started docs, runnable example per concept, next steps for tutorials and how-tos
- [ ] Step 4: Apply the type-relevant rules to concrete weaknesses in the draft
- [ ] Step 5: Verify: run every example, resolve every link, confirm parameter names and defaults against the implementation; quote the command output
Step 5 is the exit criterion: a doc ships when its examples ran and its links resolved, not when it "reads well". Length follows what the reader has to do, not the template: drop a section the page does not need rather than filling it.
Type-gating table
These rules apply only to the listed types. Flagging them elsewhere tells the author to break Diataxis.
| Rule | Applies to |
|---|---|
structure-quick-start | Getting-started pages, READMEs |
structure-next-steps, structure-procedures | Tutorials, how-to guides |
code-multiple-languages | Reference and how-to pages for a multi-SDK API |
scan-three-column-api | API reference |
hygiene-experimental-label, hygiene-planned-label | Reference and how-to pages for unstable or unshipped features |
nav-agent-readable | Docs sites (not a single README) |
Everything else applies to every type. Tutorials additionally get the we allowance in voice-defaults; reference pages get the signature-block allowance in structure-heading-overview.
Rule categories by priority
| Priority | Category | Impact | Prefix | Rules |
|---|---|---|---|---|
| 1 | Voice & Tone | CRITICAL | voice- | 4 |
| 2 | Structure & Organization | CRITICAL | structure- | 9 |
| 3 | Clarity & Language | HIGH | clarity- | 5 |
| 4 | Code Examples | HIGH | code- | 8 |
| 5 | Formatting & Syntax | MEDIUM-HIGH | format- | 7 |
| 6 | Navigation & Linking | MEDIUM-HIGH | nav- | 7 |
| 7 | Scanability & Readability | MEDIUM | scan- | 2 |
| 8 | Content Hygiene | MEDIUM | hygiene- | 6 |
| 9 | Review & Testing | LOW-MEDIUM | review- | 3 |
For the full rule list per category, read rules/_sections.md. The *-defaults.md files (voice, clarity, scan, review) are multi-check bundles, 2-5 baseline checks each.
Output contract (audit mode)
## Documentation Audit Findings
### path/to/file.md
- [CRITICAL] `voice-defaults`: Passive voice obscures who performs the action.
- Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."
### path/to/clean-file.md
- ✓ pass
- Group by file; order by severity within each file.
- Use
file:linewhen available. - Every finding names the rule, states the issue, proposes a fix. No fix, not reportable.
- List clean files as
✓ passso the author knows they were checked.
Gotchas
- Doc-type misclassification is the top false-positive source. A missing quick start on an explanation page, or a "Next steps" section demanded of a reference page, is a finding against Diataxis, not for i