dorkos: Skill for Claude Code

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)

# [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

## 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")

## When to Use What

| Scenario | Approach | Why       |
| -------- | -------- | --------- |
| Need X   | Use Y    | Because Z |
| Need A   | Use B    | Because C |

Critical for AI: A good decision matrix eliminates 80% of clarifying questions. Agents can pattern-match their current task to the right approach.

4. Core Patterns (Code Examples)

## Core Patterns

### [Pattern Name]

[1-2 sentence context]

```typescript
// Complete, runnable example
// Comments explain WHY, not WHAT
export function example() {
  // This pattern ensures X because Y
  return result;
}
```

**Requirements:**
- Examples must be complete (copy-paste ready)
- Include imports if non-obvious
- Comments explain reasoning, not mechanics

### 5. Anti-Patterns

```markdown