From 2fe3eef35a04d7f00adebb03bb0a4f029d2ef597 Mon Sep 17 00:00:00 2001
From: Hugo Nijhuis <hugo@flowmade.one>
Date: Mon, 29 Dec 2025 00:48:03 +0100
Subject: [PATCH] Add model selection guidance to writing-agents.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a new "Model Selection" section that explains when and why to
choose different Claude models (haiku, sonnet, opus, inherit) for agents.

Includes:
- Model characteristics comparison table
- Decision matrix for agent task types
- Concrete examples with reasoning
- Best practices for model selection
- Guidance on when to use `inherit`

Closes #17

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/writing-agents.md | 78 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/docs/writing-agents.md b/docs/writing-agents.md
index c62c47b..602d584 100644
--- a/docs/writing-agents.md
+++ b/docs/writing-agents.md
@@ -334,6 +334,84 @@ The H1 title in `AGENT.md` should be the role name in Title Case:
 | `code-reviewer` | Code Reviewer Agent |
 | `security-auditor` | Security Auditor Agent |
 
+## Model Selection
+
+Agents can specify which Claude model to use via the `model` field in YAML frontmatter. Choosing the right model balances capability, speed, and cost.
+
+### Available Models
+
+| Model | Characteristics | Best For |
+|-------|-----------------|----------|
+| `haiku` | Fastest, most cost-effective | Simple structured tasks, formatting, basic transformations |
+| `sonnet` | Balanced speed and capability | Most agent tasks, code review, issue management |
+| `opus` | Most capable, best reasoning | Complex analysis, architectural decisions, nuanced judgment |
+| `inherit` | Uses parent context's model | When agent should match caller's capability level |
+
+### Decision Matrix
+
+| Agent Task Type | Recommended Model | Reasoning |
+|-----------------|-------------------|-----------|
+| Structured output formatting | `haiku` | Pattern-following, no complex reasoning |
+| Code review (style/conventions) | `sonnet` | Needs code understanding, not deep analysis |
+| Security vulnerability analysis | `opus` | Requires nuanced judgment, high stakes |
+| Issue triage and labeling | `haiku` or `sonnet` | Mostly classification tasks |
+| Feature planning and breakdown | `sonnet` or `opus` | Needs strategic thinking |
+| Batch processing (many items) | `haiku` or `sonnet` | Speed and cost matter at scale |
+| Architectural exploration | `opus` | Complex reasoning about tradeoffs |
+
+### Examples
+
+These examples show recommended model configurations for different agent types:
+
+**Code Reviewer Agent** - Use `sonnet`:
+```yaml
+---
+name: code-reviewer
+model: sonnet
+skills: forgejo, code-review
+---
+```
+Code review requires understanding code patterns and conventions but rarely needs the deepest reasoning. Sonnet provides good balance.
+
+**Security Auditor Agent** (hypothetical) - Use `opus`:
+```yaml
+---
+name: security-auditor
+model: opus
+skills: code-review  # would add security-specific skills
+---
+```
+Security analysis requires careful, nuanced judgment where missing issues have real consequences. Worth the extra capability.
+
+**Formatting Agent** (hypothetical) - Use `haiku`:
+```yaml
+---
+name: markdown-formatter
+model: haiku
+skills: documentation
+---
+```
+Pure formatting tasks follow patterns and don't require complex reasoning. Haiku is fast and sufficient.
+
+### Best Practices for Model Selection
+
+1. **Start with `sonnet`** - It handles most agent tasks well
+2. **Use `haiku` for volume** - When processing many items, speed and cost add up
+3. **Reserve `opus` for judgment** - Use when errors are costly or reasoning is complex
+4. **Avoid `inherit` by default** - Make a deliberate choice; `inherit` obscures the decision
+5. **Consider the stakes** - Higher consequence tasks warrant more capable models
+6. **Test with real tasks** - Verify the chosen model performs adequately
+
+### When to Use `inherit`
+
+The `inherit` option has legitimate uses:
+
+- **Utility agents**: Small helpers that should match their caller's capability
+- **Delegation chains**: When an agent spawns sub-agents that should stay consistent
+- **Testing/development**: When you want to control model from the top level
+
+However, most production agents should specify an explicit model.
+
 ## Best Practices
 
 ### 1. Choose Skills Deliberately