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.
2.1 KiB
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
/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 |