Agent Development

Quick Start

If you need to create an agent: Create .claude/agents/name/ with agent.md.

If you need to audit an agent: Invoke this skill directly to validate configuration.

If you need to refine an agent: Compare against patterns and apply fixes.

Navigation

Philosophy

Agents are specialized workers with isolated context. Unlike skills (portable knowledge), agents are configured workers with specific tool access and task scope.

Key insight: Agents are "configured workers" - they have specific capabilities defined by their configuration, unlike skills which encode knowledge.

Why this matters:

• Agents have isolated context (Task tool spawns subagent)
• Agents can have tool restrictions (allowed-tools)
• Agents are task-specific workers, not general knowledge
• Agent behavior is defined by frontmatter, not SKILL.md

PATTERN: Directory

Agents use a simple directory structure:

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

Directory Structure

Example Structure

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

PATTERN: Frontmatter

Agents use YAML frontmatter for configuration:

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

Frontmatter Fields

Description Format

Description Examples

Basic:

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

Intermediate:

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."

Gold Standard:

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:

```yaml
---
name: restricted-agent
description: "Agent with limited capabilities."
allowed-tools:
  - Read
  - Write
---

Tool Categories

allowed-tools Best Practices

Example Configurations

Minimal (Read-only analysis):

allowed-tools:
  - Read
  - Glob
  - Grep
  - LSP

Standard (Read-write):

allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
  - LSP

Full access:

allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
  - Task
  - LSP
  - WebFetch
  - WebSearch

PATTERN: Perfect Agent

Simple Agent (Analysis)

---
name: analysis-agent
description: "Analyze code and find patterns. Use when exploring codebase. Includes pattern matching and file discovery. Not for modifications."
allowed-tools:
  - Read
  - Glob
  - Grep
  - LSP
model: sonnet
---

Medium Agent (with Task delegation)

---
name: planning-agent
description: "Create implementation plans with TDD. Use when starting features. Creates test-first plans with verification. Not for bug fixes."
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
  - Task
  - Skill
model: sonnet
---

Complex Agent (Full capabilities)

---
name: full-agent
description: "Complete development workflow agent. Use for autonomous development. Includes planning, implementation, testing. Not for research tasks."
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
  - Task
  - Skill
  - LSP
  - WebFetch
  - WebSearch
  - mcp__vscode-*
model: opus
temperature: 0.7
---

ANTI-PATTERN: Common Failures

Anti-Pattern: Overly Broad allowed-tools

❌ Wrong:
allowed-tools:
  - Read
  - Write
  - Bash
  - Task
  - Skill
  - ALL_TOOLS  # Never do this

Fix: Restrict to minimum needed:

✅ Correct:
allowed-tools:
  - Read
  - Glob
  - Grep

Anti-Pattern: Missing Task Scope

❌ Wrong:
---
name: planning-agent
description: "Plan tasks."
---

Fix: Define clear scope in description:

✅ Correct:
---
name: planning-agent
description: "Create implementation plans with TDD. Use when starting features. Not for modifications."
---

Anti-Pattern: No Model Specification

❌ Wrong:
---
name: analysis-agent
description: "Deep analysis."
---

Fix: Specify model for specialized tasks:

✅ Correct:
---
name: analysis-agent
description: "Deep analysis. Use for complex investigations."
model: opus
---

Anti-Pattern: Wrong Directory Structure

❌ Wrong:
.claude/agents/planning-agent/
├── agent.md
└── references/
    └── patterns.md

✅ Correct:
.claude/agents/planning-agent/
└── agent.md

Or use a Skill if references are needed:
.claude/skills/planning/
├── SKILL.md
└── references/
    └── patterns.md

Anti-Pattern: Agent References Slash Commands

❌ Wrong:
description: "Run /meta:refine:all operations."

Fix: Never reference slash commands:

✅ Correct:
description: "Run refinement operations. Use when improving multiple components. Orchestrates all refine operations."

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

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