跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

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 ghostwriter skill with platform blog), a README from scratch or a whole-README rewrite (use readme-creator; a README that needs its prose fixed in place stays here), AGENTS.md or CLAUDE.md instructions (use agents-md), marketing and landing-page copy (use copywriting), or the product's own error strings and CLI output (use dx-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)
ActionTutorialHow-to guide
CognitionExplanationReference

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.

RuleApplies to
structure-quick-startGetting-started pages, READMEs
structure-next-steps, structure-proceduresTutorials, how-to guides
code-multiple-languagesReference and how-to pages for a multi-SDK API
scan-three-column-apiAPI reference
hygiene-experimental-label, hygiene-planned-labelReference and how-to pages for unstable or unshipped features
nav-agent-readableDocs 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

PriorityCategoryImpactPrefixRules
1Voice & ToneCRITICALvoice-4
2Structure & OrganizationCRITICALstructure-9
3Clarity & LanguageHIGHclarity-5
4Code ExamplesHIGHcode-8
5Formatting & SyntaxMEDIUM-HIGHformat-7
6Navigation & LinkingMEDIUM-HIGHnav-7
7Scanability & ReadabilityMEDIUMscan-2
8Content HygieneMEDIUMhygiene-6
9Review & TestingLOW-MEDIUMreview-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:line when available.
  • Every finding names the rule, states the issue, proposes a fix. No fix, not reportable.
  • List clean files as ✓ pass so 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
阅读完整来源 ↗