docs-write

docs:write — Documentation Generation & Update

Philosophy: Template-driven documentation with progressive disclosure. Load only the reference template needed for the current request. Respect existing project conventions. Preserve custom content when updating.

Core Principles

1. Template-driven - Consistency through templates, customization through content
2. One reference per invocation - Load only the selected template, not all 14
3. Idempotent updates - Preserve custom sections, update only managed sections
4. Convention-aware - Detect and follow existing project documentation structure
5. Progressive disclosure - SKILL.md routes, reference files provide detail

---

Trigger Conditions

Run this skill when:

• Creating new documentation of any type
• Updating existing documentation with template guidance
• Generating AI-focused files (CLAUDE.md, AGENTS.md, llms.txt)
• Writing architecture documentation (C4, system overview)
• User says "write docs for", "create a tutorial", "document the API", "generate README"

Do NOT use this skill for:

• Assessing documentation health → Use docs:audit
• Recording architectural decisions → Use docs:adr
• "Review my docs" or "what's missing" → Use docs:audit
• "Record this decision" or "create an ADR" → Use docs:adr

---

Critical Sequence

Phase 0: Prerequisites Check

Step 0.1 - Resolve Project Root:

PROJECT_ROOT=$(git rev-parse --show-toplevel)
echo "Project root: ${PROJECT_ROOT}"

# Ensure docs folder exists
mkdir -p "${PROJECT_ROOT}/docs"

Step 0.2 - Check Existing Documentation:

# Check if target doc already exists
ls "${PROJECT_ROOT}/docs/"

# Check existing folder conventions (tutorials/ vs guides/ etc.)
find "${PROJECT_ROOT}/docs" -type d -maxdepth 2

Verify:

[ ] PROJECT_ROOT resolved correctly
[ ] docs/ folder exists (created if needed)
[ ] Checked for existing doc with same name/topic
[ ] Noted existing folder conventions