feat(skills): add writing-docs skill for public-facing documentation

[sourcehawk]

Description

Adds a writing-docs skill that makes the agent reliably write and update public-facing documentation — README, usage guides, tutorials, public API/reference — to a consistent, OSS-grade bar, and wires it into the existing feature-development flow so docs aren't forgotten. It fills a real gap: the plugin already covers docstrings (testing-a-feature), release notes (drafting-a-release), and specs/ADRs (planning-a-feature), but the durable prose a consumer actually reads had no home and no quality discipline.

The skill teaches one principle — a doc is a set of answers to a reader's questions, proven by a fresh-reader test rather than by re-reading your own draft — and was itself built with the writing-skills RED→GREEN→REFACTOR loop against real subagent baselines.

Changes

• New skills/writing-docs/SKILL.md: locate-the-doc-surfaces-first step, a fresh-reader RED→GREEN→REFACTOR loop, device/depth selection (Mermaid for diagrams, never hand-drawn ASCII), an OSS-grade quality bar, scope handoffs, and Anti-patterns + Red-flags tables.
• Wires **REQUIRED SUB-SKILL:** feature-dev-workflow:writing-docs in beside testing-end-to-end at structural completion in both paths: developing-a-feature (single-PR) and reviewing-feature-progress (multi-PR).
• Lists the skill in the README skills table and the templates/project-CLAUDE.md flow map.

Challenges

The first RED baseline was contaminated: subagents run inside this repo inherited its skill ecosystem and behaved well, hiding the natural failures. Re-running isolated baselines surfaced the real ones — agents default to ASCII diagrams ("avoids a Mermaid dependency") and assert a reader could follow the docs instead of testing it. The skill targets exactly those, and is deliberately leaner than the original design where the evidence didn't justify counters (forgetting and fluff weren't natural failures, so forgetting is handled by the wiring, not prose). A late addition — a step requiring the agent to establish where docs live before writing — came from review feedback and was verified to make the agent infer a docs-site tier from a bare file listing and route depth there.

Testing

Built and verified entirely through subagent scenarios, per writing-skills. RED: documented baseline failures across two scenarios (a feature wrap-up and a from-scratch README), run both contaminated and isolated. GREEN: re-ran the same scenarios with the skill present and confirmed both failures fixed — agents now name reader personas, run an explicit reader test, and decline ASCII in favor of Mermaid. A diagram-warranting scenario confirmed the agent produces a real mermaid block; a multi-surface scenario confirmed the new surface-location step routes depth to a docs site with only a README pointer. A fresh reviewer agent checked the diff against the contributor rules and the design; its one valid finding (a dropped section) was fixed. Mechanical checks: no stack/product leakage (only the justified Mermaid/GitHub mention), description: is trigger-only, control-flow markers consistent across every flow-listing file.

[Copilot]

Pull request overview

Adds a new writing-docs skill that ensures public-facing documentation (README, guides, tutorials, API reference) is written to an OSS-grade bar via a fresh-reader RED→GREEN→REFACTOR loop, and wires it into the structural-completeness checkpoints of both single-PR and multi-PR feature flows.

Changes:

• Adds skills/writing-docs/SKILL.md defining the doc-surface discovery step, reader-persona test loop, Mermaid-only diagram rule, quality bar, and out-of-scope handoffs.
• Wires **REQUIRED SUB-SKILL:** feature-dev-workflow:writing-docs next to testing-end-to-end in developing-a-feature (Step 5) and reviewing-feature-progress (Step 6).
• Lists the skill in the README skills table and the templates/project-CLAUDE.md flow map.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skills/writing-docs/SKILL.md	New skill content with frontmatter, loop, device/depth selection, quality bar, anti-patterns, and red flags.
skills/developing-a-feature/SKILL.md	Adds docs handoff in Step 5 single-PR checkpoint between e2e and verification.
skills/reviewing-feature-progress/SKILL.md	Adds docs handoff in the multi-PR checkpoint between e2e and verification.
README.md	Adds writing-docs row to skills table.
templates/project-CLAUDE.md	Adds writing-docs row to the flow map table.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.