writing-developer-guideslisted

# Writing Developer Guides ## Overview This skill teaches how to write developer guides that work well for both AI coding agents and human developers. The key insight: AI agents need fast context retrieval, clear decision support, and copy-paste ready patterns. ## When to Apply - Creating a new file in `contributing/` - Updating or refactoring an existing guide - Reviewing guides for completeness - User asks about documentation structure ## Core Principle **Structure for retrieval, not teaching.** Traditional documentation assumes sequential reading. AI agents retrieve specific information based on task context. Every section should be independently useful. ## Required Sections (In Order) Each developer guide must include these sections in this sequence: ### 1. Title + Overview (2-3 sentences) ```markdown # [Topic] Guide ## Overview [What this guide covers] and [why it matters for this project]. ``` **Why this order:** AI agents use the overview to determine relevance before reading further. ### 2. Key Files Table ```markdown ## Key Files | Concept | Location | | ------------- | -------------------- | | Configuration | `src/path/config.ts` | | Types | `src/path/types.ts` | ``` **Why early:** Agents need to know WHERE before HOW. This prevents searching. ### 3. Decision Matrix ("When to Use What") ```markdown ## When to Use What | Scenario | Approach | Why | | -------- | -------- | --------- | | Need X | Use Y | Becaus