Agent Development

.claude/agents/agent-name/
└── agent.md

.claude/agents/
├── planning-agent/
│   └── agent.md
├── code-review-agent/
│   └── agent.md
└── testing-agent/
    └── agent.md

---
name: agent-name
description: "Brief description, non spoiling of the content. Use when {trigger condition + keywords + key sentences user might say that should lead the agent to be invoked}. Not for {exclusions}."
allowed-tools:
  - Read
  - Write
  - Glob
model: sonnet  # Optional: sonnet, opus, haiku
temperature: 0  # Optional: 0-1
---

description: "Plan implementation tasks. Use when starting new work or features that need planning."

description: "Create implementation plans with TDD discipline. Use when starting new features, following test-driven development, or planning complex implementations. Not for bug fixes or quick tasks."

description: "Plan implementation using TDD discipline with parallel execution. Use when building new features, following test-driven development, or planning complex implementations. Creates test-first plans with verification gates. Not for bug fixes, hotfixes, or trivial changes."

## PATTERN: Allowed Tools

The `allowed-tools` field restricts which tools the agent can use:

### Tool Categories

| Category | Tools |
| :-------- | :----- |
| File Operations | Read, Write, Glob, Grep |
| Code Intelligence | LSP operations |
| Execution | Bash, Task |
| VS Code | All mcp__vscode-* tools |
| Web | WebFetch, WebSearch, mcp__exa-* |
| Orchestration | Skill, AskUserQuestion |

### allowed-tools Best Practices

| Do | Don't |
| :-- | :----- |
| Restrict to minimum needed | Use broad tool access |
| Limit destructive tools | Allow rm, rm -rf without hooks |
| Use for behavior guidance | Use as security (personal project) |
| Document why restrictions exist | Add without reason |

### Example Configurations

**Minimal (Read-only analysis):**

**Standard (Read-write):**

**Full access:**

## PATTERN: Perfect Agent

### Simple Agent (Analysis)

### Medium Agent (with Task delegation)

### Complex Agent (Full capabilities)

## ANTI-PATTERN: Common Failures

### Anti-Pattern: Overly Broad allowed-tools

**Fix:** Restrict to minimum needed:

### Anti-Pattern: Missing Task Scope

**Fix:** Define clear scope in description:

### Anti-Pattern: No Model Specification

**Fix:** Specify model for specialized tasks:

### Anti-Pattern: Wrong Directory Structure

### Anti-Pattern: Agent References Slash Commands

**Fix:** Never reference slash commands:

## Validation Checklist

Before claiming agent authoring complete:

**Structure:**
- [ ] Agent in `.claude/agents/name/` directory
- [ ] Single `agent.md` file
- [ ] No `references/` folder

**Frontmatter:**
- [ ] Valid `name` field
- [ ] Description uses "Use when" format
- [ ] Clear task scope defined
- [ ] Exclusions documented if applicable

**Configuration:**
- [ ] `allowed-tools` defined (or omitted for defaults)
- [ ] Model specified for specialized tasks
- [ ] Temperature set for creative tasks

**Best Practices:**
- [ ] Tools restricted to minimum needed
- [ ] No reference to slash commands
- [ ] Task scope clearly defined
- [ ] Behavior guidance via allowed-tools

---

## Recognition Questions

| Question | Answer Should Be... |
| :------- | :------------------ |
| Does agent use directory structure? | Yes, `.claude/agents/name/` |
| Does agent have frontmatter? | Yes, with name and description |
| Does allowed-tools exist? | Yes, restricted to minimum |
| Does agent reference /meta? | No, never references slash commands |
| Is task scope clear? | Yes, description defines scope |
| Is model specified? | Yes, for specialized tasks |

---

<critical_constraint>
**Portability:**

1. Agents MUST reference skills by name only, never by path
2. Agents never know about commands that trigger them
3. Agent logic must be self-documenting
4. Never use relative paths pointing outside the skill itself. When referencing other components, use: "invoke `skill-name`" or "invoke `skill-name` and read its file"

**Self-Contained:**

1. All agent configuration MUST be in frontmatter
2. No external dependencies for validation
3. Fork isolation (works in vacuum)

**Configuration:**

1. allowed-tools guides behavior (removes options from availability)
2. Hooks can enforce (block operations via exit codes)
3. Tools should be restricted to minimum needed
4. Model and temperature affect agent creativity
</critical_constraint>