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.