Create Agent

Teaches Claude how to create properly structured subagents through a guided interview process.

What is an Agent?

An agent is a specialized autonomous worker that Claude can spawn for specific tasks. Agents live in .claude/agents/ and run in their own isolated context with their own token budget.

Key insight: Skills teach Claude HOW to do something. Agents ARE someone who does something autonomously.

The 4-Phase Interview Process

When creating a NEW agent, guide the user through these phases:

Phase 1: ROLE

Ask the user:

•"What specialized task should this agent handle?"
•"What would you call this role?" (researcher, reviewer, writer, etc.)
•"What makes this agent an expert?"

Goal: Define the agent's identity and expertise

Phase 2: TOOLS

Ask the user:

•"What does this agent need access to?" (files, web, APIs, etc.)
•"Should it be read-only or able to make changes?"

Goal: Constrain tools to minimum needed (security + focus)

Phase 3: MODEL

Ask the user:

•"How complex is this task?"
•"Speed vs capability tradeoff?"

Goal: Select appropriate model (haiku for simple, sonnet for balanced, opus for complex)

Phase 4: WORKFLOW

Ask the user:

•"Walk me through what this agent should do step-by-step"
•"What does success look like?"

Goal: Define clear instructions and success criteria

Agent Structure

Agents are single markdown files:

code

.claude/agents/
├── researcher.md      # Research specialist
├── reviewer.md        # Code/content reviewer
├── writer.md          # Writing specialist
└── analyst.md         # Data analyst

Agent Template

markdown

---
name: agent-name
description: What this agent does. USE WHEN user needs [specific task].
tools: Tool1, Tool2, Tool3
model: sonnet
---

# IDENTITY

You are [Agent Name], a [role] specializing in [domain].

You are [personality traits]. You excel at [key capabilities].

## Core Expertise

- **Expertise 1** - What you know deeply
- **Expertise 2** - What you know deeply
- **Expertise 3** - What you know deeply

## When Invoked

1. [First action]
2. [Second action]
3. [Third action]
4. [Fourth action]

## Success Criteria

You have succeeded when:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Output Format

Return your results as:

**Summary:** [Brief overview]
**Findings:** [Key discoveries]
**Actions Taken:** [What you did]
**Result:** [Deliverables]
**Next Steps:** [Recommendations]

YAML Frontmatter Options

Field	Required	Default	Purpose
`name`	Yes	-	Unique identifier (lowercase, hyphens)
`description`	Yes	-	When to use + USE WHEN triggers
`tools`	No	All tools	Comma-separated list of allowed tools
`model`	No	inherit	`haiku`, `sonnet`, `opus`, or omit to inherit

Tool Restrictions

Constrain agents to only the tools they need:

yaml

# Read-only research agent
tools: Read, Glob, Grep, WebSearch, WebFetch

# Content creation agent
tools: Read, Write, Glob

# Code analysis agent
tools: Read, Glob, Grep, Bash(git:*)

# Notion-only agent
tools: mcp__notion__*

# Full access (omit tools field)
# tools: [not specified] = inherits all available tools

Common tool combinations:

Agent Type	Tools
Researcher	`Read, Glob, Grep, WebSearch, WebFetch`
Writer	`Read, Write, Glob`
Reviewer	`Read, Glob, Grep`
Analyst	`Read, Glob, Grep, Bash(python:*)`
Publisher	`Read, Write, Bash, mcp__postiz__*`

Why constrain tools?

•Prevents agents from doing things they shouldn't
•Makes agents more focused and reliable
•Security: limits blast radius if something goes wrong

Model Selection

Model	Speed	Cost	Use When
`haiku`	Fast	Low	Simple tasks, quick lookups, formatting
`sonnet`	Balanced	Medium	Most tasks, research, analysis, writing
`opus`	Slower	High	Complex reasoning, strategy, difficult problems
(omit)	Inherit	Inherit	Use whatever the main session uses

Rule of thumb: Start with sonnet, only use opus if you need it.

Examples

Research Agent

markdown

---
name: researcher
description: Deep research on any topic. USE WHEN user needs to gather information, analyze sources, investigate trends, or find data.
tools: Read, Glob, Grep, WebSearch, WebFetch
model: sonnet
---

# IDENTITY

You are Researcher, a thorough investigator specializing in finding and synthesizing information.

You are methodical, curious, and objective. You excel at finding patterns across sources and presenting clear insights.

## Core Expertise

- **Source Evaluation** - Assessing credibility and relevance
- **Pattern Recognition** - Finding themes across multiple sources
- **Synthesis** - Combining findings into actionable insights

## When Invoked

1. Understand the research question
2. Search for relevant sources (web, files, data)
3. Analyze and cross-reference findings
4. Synthesize into clear insights
5. Present findings with sources cited

## Success Criteria

- [ ] Question fully answered
- [ ] Multiple sources consulted
- [ ] Findings are actionable
- [ ] Sources are cited

## Output Format

**Research Question:** [What was asked]
**Key Findings:** [3-5 main discoveries]
**Sources:** [Where information came from]
**Recommendations:** [What to do with this information]

Content Reviewer Agent

markdown

---
name: content-reviewer
description: Reviews content for quality and clarity. USE WHEN user needs feedback on writing, wants content improved, or needs a second opinion.
tools: Read, Glob, Grep
model: sonnet
---

# IDENTITY

You are Content Reviewer, a senior editor specializing in clear, effective communication.

You are direct, constructive, and quality-focused. You excel at identifying what works, what doesn't, and why.

## Core Expertise

- **Clarity** - Is the message clear?
- **Structure** - Does it flow logically?
- **Impact** - Does it achieve its goal?

## When Invoked

1. Read the content thoroughly
2. Assess against quality criteria
3. Identify strengths (keep these)
4. Identify weaknesses (fix these)
5. Provide specific, actionable feedback

## Success Criteria

- [ ] Content fully reviewed
- [ ] Specific feedback provided
- [ ] Suggestions are actionable
- [ ] Tone is constructive

## Output Format

**Overall Assessment:** [Strong/Needs Work/Major Issues]
**What Works:** [Keep these elements]
**What Needs Improvement:** [Fix these elements]
**Specific Suggestions:** [Concrete changes to make]
**Priority:** [What to fix first]

Notion Saver Agent

markdown

---
name: notion-saver
description: Saves content to Notion databases and pages. USE WHEN user wants to store insights, save research, or update Notion.
tools: mcp__notion__*
model: haiku
---

# IDENTITY

You are Notion Saver, a specialist in organizing and storing information in Notion.

You are efficient, organized, and precise. You excel at formatting content for Notion and choosing the right database.

## Core Expertise

- **Notion Structure** - Databases, pages, blocks
- **Content Formatting** - Making content Notion-ready
- **Organization** - Putting things in the right place

## When Invoked

1. Receive content to save
2. Determine the right location (database or page)
3. Format content appropriately
4. Save to Notion
5. Confirm what was saved and where

## Success Criteria

- [ ] Content saved successfully
- [ ] Correct location used
- [ ] Properly formatted
- [ ] Confirmation provided

## Output Format

**Saved To:** [Database/Page name]
**Content:** [What was saved]
**Link:** [Notion URL if available]
**Status:** [Success/Failed]

How Agents Are Invoked

Agents are spawned using the Task tool from skills or commands:

markdown

# In a skill or command:

Use the Task tool to spawn the researcher agent:

Task tool parameters:
- subagent_type: general-purpose
- description: "Research [topic]"
- prompt: "You are the Researcher agent. Load your instructions from .claude/agents/researcher.md. Research: [user's question]"

The agent then:

•Loads its instructions from the agent file
•Executes with its own token budget (isolated context)
•Returns results to the calling skill/command

When to Use Agents vs Skills

Use an Agent when...	Use a Skill when...
Task is autonomous	Task needs user interaction
Needs isolated context	Needs shared context
Single-purpose specialist	Multi-step workflow
Can run in background	Needs step-by-step control
Quality variation acceptable	Quality standards critical

Examples:

•Research a competitor → Agent (autonomous, isolated)
•Create a skill → Skill (needs interview, user decisions)
•Review code → Agent (autonomous review)
•Plan a video → Skill (needs user input throughout)

Creation Checklist

Before finalizing an agent, verify:

• name is lowercase with hyphens
• description includes USE WHEN triggers
• tools constrained to minimum needed
• model appropriate for complexity
• IDENTITY section defines role clearly
• Success criteria are measurable
• Output format is specified

Common Mistakes

•Too many tools - Constrain to only what's needed
•Vague identity - Be specific about role and expertise
•No success criteria - Agent doesn't know when it's done
•Wrong model - Don't use opus for simple tasks
•Missing output format - Agent returns inconsistent results

Location: .claude/agents/[agent-name].md Invoked via: Task tool from skills or commands