docs(bin): give every bin skill a README

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.

plugins/bin/.apm/skills/write-docs/README.md

@@ -0,0 +1,30 @@
+# 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 |