How to Set Up Claude Code Agents

What is a Claude Code agent?

An agent is a markdown file in .claude/agents/ that gives Claude a specific role, tools, and constraints. Instead of one general-purpose assistant, you get specialized team members: a product manager who plans, a developer who codes, a tester who verifies.

Agent file structure

Every agent file has two parts: YAML frontmatter (configuration) and markdown body (instructions).

---
name: product-manager
description: >-
  Feature planning orchestrator who breaks requests
  into RICE-prioritized tasks and delegates to specialists.
model: opus
tools:
  - Read
  - Grep
  - Glob
  - Task
permissionMode: plan
memory: project
---

# Product Manager

You are the product manager for this project.
You plan features, prioritize work, and delegate
to the right agent.

## Responsibilities
1. Break features into prioritized tasks
2. Delegate to developer for implementation
3. Verify outputs meet acceptance criteria

## Rules
- Never implement code yourself
- Use RICE scoring for prioritization

Frontmatter fields explained

Choosing the right model

Rule of thumb: use opus for agents that orchestrate other agents, sonnet for agents that write code, haiku for agents that gather information.

Permission modes

• default — Standard permission checking with prompts for each action. The safest starting point.
• plan — Read-only exploration mode. Agent can read and search but cannot modify files. Good for PMs and reviewers.
• acceptEdits — Auto-accepts file edits without prompting. Good for developer agents where you trust the changes.
• dontAsk — Auto-denies permission prompts. Explicitly allowed tools still work, but anything requiring approval is silently denied. Use for agents that should only use pre-approved tools.
• bypassPermissions — Skips all permission checks entirely. Use with extreme caution — only for fully trusted agents in controlled environments.

Start with plan and loosen permissions as you build trust in the agent's behavior.

Writing effective agent instructions

The markdown body after frontmatter is your agent's system prompt. Generic instructions produce generic results. Be specific:

• List responsibilities as numbered items
• State exactly what to check, not "review carefully"
• Add anti-patterns with bad/good examples
• End with a Rules section of hard constraints

Common mistakes

• Using permission instead of permissionMode — the correct field name is permissionMode
• Nested memory config — use memory: project, not a nested object
• Full model IDs — use opus not claude-opus-4-6
• Filename mismatch — the name field must match the filename without .md