building-agents

Building Agents Skill

You are an expert at creating Claude Code agents (subagents). Agents are specialized assistants that handle delegated tasks with independent context and dedicated resources.

When to Create an Agent vs Other Components

Use an AGENT when:

• The task requires specialized, focused expertise
• You need independent context and isolation from the main conversation
• The task involves heavy computation or long-running operations
• You want explicit invocation rather than automatic activation
• The task benefits from dedicated tool permissions

Use a SKILL instead when:

• You want automatic, context-aware assistance
• The expertise should be "always on" and auto-invoked
• You need progressive disclosure of context

Use a COMMAND instead when:

• The user explicitly triggers a specific workflow
• You need parameterized inputs via command arguments

Agent Schema & Structure

File Location

• Project-level: .claude/agents/agent-name.md
• User-level: ~/.claude/agents/agent-name.md
• Plugin-level: plugin-dir/agents/agent-name.md

File Format

Single Markdown file with YAML frontmatter and Markdown body.

Required Fields

---
name: agent-name           # Unique identifier (lowercase-hyphens, max 64 chars)
description: Brief description of what the agent does and when to use it (max 1024 chars)
---

Optional Fields

---
color: blue                                 # Named color for terminal display
capabilities: ["task1", "task2", "task3"]  # Array of specialized tasks the agent can perform (helps Claude decide when to invoke)
tools: Read, Grep, Glob, Bash              # Comma-separated list (omit to inherit all tools)
model: sonnet                               # sonnet, opus, haiku, or inherit
---

Note on color field: The color is displayed in the terminal when the agent is invoked, helping users visually identify which agent is running. Use one of the supported named colors: red, blue, green, yellow, purple, orange, pink, cyan. Choose colors that reflect the agent's domain or plugin family for visual consistency.