Defame1297
e869912374
The bin skills were the only plugin without per-skill READMEs, so a reader had to open SKILL.md — an agent-facing contract, not an explainer — to learn what a skill does and when it fires. Each README states purpose, triggers and boundaries for a human audience, leaving SKILL.md free to stay terse.
31 lines
2.1 KiB
Markdown
31 lines
2.1 KiB
Markdown
# write-docs
|
||
|
||
Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
|
||
|
||
## What it does
|
||
|
||
Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
|
||
|
||
The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
|
||
|
||
- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
|
||
- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
|
||
- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
|
||
- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
|
||
|
||
Summary and overview sections are written last, once the detail sections are stable.
|
||
|
||
## Usage
|
||
|
||
```text
|
||
/write-docs
|
||
```
|
||
|
||
Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling.
|
||
|
||
## Files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |
|