Software Docs Skill

Guiding Principles

• Max 1 page / ~6 min read — trim ruthlessly, link to details
• Audience-first — tune every doc to its primary reader (see AUDIENCES.md)
• Interview before writing — gather context, write rough draft, iterate
• No filler — every sentence earns its place
• Markdown only — use headers, tables, code blocks; no emojis unless audience is internal-casual

Humanization Flag

Check the user's prompt for --human, --humanise, or --humanize (case-insensitive, any position).

• If flag present: strip the flag from the prompt before processing. After the doc is written to file (Step 6), output exactly Humanizing... on its own line, then use the Skill tool to invoke humanizer with the written file path as context. The humanizer rewrites the file in place at full intensity. The humanized version replaces the draft — do not show the pre-humanized output.
• If flag absent: proceed normally, no humanization step.

Examples: write a PRD for X --humanise · --human write a user guide · create release notes --humanize

Workflow

1. Identify doc type → load template from templates/
2. Interview user (round 1, 3–5 targeted questions)
3. Write rough draft
4. Ask open questions BEFORE finalising
5. Resolve open questions with user
6. Iterate with user until approved
7. If --human/--humanise/--humanize flag present → humanize written file in place

Step 1 — Identify doc type

Ask: "What are you building/shipping/explaining?" then map to one of:

Step 2 — Interview (round 1)

Ask only what's missing. Standard questions per type are in each template. 3–5 questions max per round. Don't ask what you can infer.

Step 3 — Write rough draft

Use the matching template. Fill every section — write TBD rather than omitting. Flag assumptions with > **Assumption:** ...

Step 4 — Ask open questions BEFORE finalising

MANDATORY: Before presenting the doc as complete, surface every open question to the user and get answers.

• Identify all [ ] open questions in the draft
• Present each question with a brief explanation of why it matters and what the tradeoffs are
• Wait for the user to answer all questions
• Only then mark them resolved with [x] and include the rationale in the answer

Do NOT skip this step or leave open questions unresolved. A doc with unresolved [ ] items is not done.

Step 5 — Resolve and finalise

Update each resolved question with [x] + the decision + the reason (1–2 sentences). This gives future readers the context behind the decision, not just the outcome.

Step 6 — Iterate

Present diff of changes. Stop when user says "looks good" or "ship it".

Templates

Audience Tone Guide

See AUDIENCES.md for full guide. Quick reference:

Quality Checklist (run before marking done)

• Under 6 min read (~1200 words)
• Audience is explicit in doc header
• No section is vacuous ("we will monitor the situation")
• Every action item has an owner + date
• No jargon without definition for non-eng audience
• Links to supporting docs rather than inlining