agent-design-best-practices

Agent Design Best Practices

Overview

This skill defines best practices for designing Claude Code agent files (.claude/agents/*.md). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that agent files define capabilities, not lifecycle -- the team lead's spawn prompt controls when and how the agent runs.

Principles

1. Define Capabilities, Not Lifecycle

Agent files describe what an agent can do. The spawn prompt from the team lead controls when it runs and what to focus on.

<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
# Security Planner Agent

You are a security specialist in a plan-create Agent Team.
Given a Research Brief from the team lead, identify security
considerations for the planned changes.

## Output Format

Send your sub-plan to the team lead via `SendMessage` with this structure:
...

<!-- Correct: Defines domain expertise, team lead controls usage -->
# Security Specialist Agent

You are a security specialist who identifies vulnerabilities,
evaluates threats, and recommends mitigations for code changes.

## Analysis Process
1. Read affected files
2. STRIDE analysis
3. Check input validation
...

The wrong version is coupled to one workflow ("plan-create Agent Team", "Given a Research Brief", "Send via SendMessage"). The correct version works in any context -- planning, review, ad-hoc analysis -- because the team lead's spawn prompt provides the specific instructions.

2. One Agent Per Domain, Not Per Phase

Prefer a single agent that covers a domain over multiple agents split by workflow phase. The team lead specializes the agent per phase via the spawn prompt.

The same agent type can be spawned multiple times with different prompts for different phases. A security-specialist spawned during planning gets "evaluate this plan for security risks" while the same type spawned during review gets "review these code changes for vulnerabilities."