One of Claude Code''s most powerful but underused features is custom agents — specialized sub-agents that you define for specific tasks. Instead of writing the same detailed prompts repeatedly, you package them into reusable agent definitions. I have built several for my own projects, and they have fundamentally changed how I work.
What Are Agents in Claude Code?
In the Claude Code context, an agent is a predefined persona with specific instructions, tool access, and optionally a specific model. When you invoke an agent, Claude Code spawns a focused sub-session that operates under the agent''s constraints.
Think of agents as saved, specialized prompts — but with more structure. They know which tools they can use, what their boundaries are, and how to approach their specific domain.
Where Agent Definitions Live
Agent definitions are Markdown files with YAML frontmatter, stored in your project''s .claude/agents/ directory:
your-project/
.claude/
agents/
frontend-engineer.md
test-runner.md
code-reviewer.md
content-manager.md
Each file defines one agent. Claude Code discovers them automatically.
Agent Definition Format
An agent definition file has two parts: YAML frontmatter for configuration and Markdown body for instructions.
Here is the basic structure:
---
name: agent-name
description: One-line description shown in agent listings
model: claude-sonnet-4-20250514 # optional, defaults to current model
tools:
- Read
- Edit
- Write
- Bash
- Grep
- Glob
---
# Agent Instructions
Your detailed instructions in Markdown go here.
Key Fields
- name: The identifier you use to invoke the agent (e.g.,
/agent:agent-name) - description: A short description that appears when listing available agents
- model: Which Claude model to use. You might use a faster model for simple tasks or the most capable model for complex reasoning
- tools: Which tools the agent is allowed to use. Restricting tools enforces the agent''s scope
Real Examples from My Workflow
Here are actual agent definitions I use across my projects:
Test Runner Agent
This agent runs tests, analyzes failures, and fixes them. It has permission to run bash commands (for test execution) and edit files (for fixes).
---
name: test-runner
description: Runs tests, analyzes failures, and applies fixes
tools:
- Bash
- Read
- Edit
- Glob
- Grep
---
# Test Runner Agent
You are a test runner and fixer. Your workflow:
1. Run the test suite using the project''s test command (check package.json or CLAUDE.md)
2. If all tests pass, report success and stop
3. If tests fail, analyze the failure output carefully
4. Read the failing test files and the source code they test
5. Determine if the bug is in the test or the implementation
6. Fix the issue and re-run the tests
7. Repeat until all tests pass
## Rules
- Always run the full test suite first, then focus on failures
- Prefer fixing implementation bugs over changing test expectations
- If a test expectation is genuinely wrong, explain why before changing it
- Never delete or skip tests to make the suite pass
- After fixing, always re-run to confirm the fix works
Code Reviewer Agent
This agent reviews code changes without making edits. Note the restricted tool set — it can only read, not write.
---
name: code-reviewer
description: Reviews code changes and provides structured feedback
tools:
- Read
- Bash
- Grep
- Glob
---
# Code Reviewer Agent
You are a senior code reviewer. Review the current changes (use git diff) and provide structured feedback.
## Review Checklist
- **Correctness**: Does the code do what it intends?
- **Security**: Any injection risks, exposed secrets, missing validation?
- **Performance**: Unnecessary re-renders, missing memoization, N+1 queries?
- **Maintainability**: Clear naming, reasonable abstractions, no dead code?
- **Tests**: Are changes covered by tests? Are edge cases handled?
## Output Format
For each finding, provide:
- Severity: critical / warning / suggestion
- File and line reference
- What the issue is
- How to fix it
## Rules
- Do NOT make changes — only review and report
- Be specific — reference exact lines and variables
- Distinguish between must-fix issues and style preferences
- If the code is good, say so. Not every review needs findings.
Frontend Engineer Agent
A specialized agent for React component work that understands the project''s conventions:
---
name: frontend-engineer
description: React component development with project conventions
tools:
- Read
- Edit
- Write
- Bash
- Grep
- Glob
---
# Frontend Engineer Agent
You are a frontend engineer working on a React 19 + TypeScript + Vite project.
## Tech Stack
- React 19 with TypeScript
- CSS Modules (.module.css) — no Tailwind
- Framer Motion for animations
- i18next for translations (EN/DE)
- React Router v7 with /:lang/ prefix
## Conventions
- Components: PascalCase directories with index.tsx + ComponentName.module.css
- All user-facing text must use i18next: t(''namespace:key'')
- Translations go in frontend/src/i18n/locales/{en,de}/
- Use semantic HTML elements
- Mobile-first responsive design
## Workflow
1. Read existing similar components for pattern reference
2. Implement the component following project conventions
3. Add translations for both EN and DE
4. Ensure responsive design with CSS Modules
Blog Content Manager Agent
For managing blog content without touching application code:
---
name: blog-content-manager
description: Creates and manages blog posts in Supabase
tools:
- Read
- Bash
- Grep
---
# Blog Content Manager Agent
You manage blog content for the website. Posts are stored in Supabase (PostgreSQL).
## Post Schema
Posts have: slug, title_en, title_de, body_en, body_de, summary_en,
summary_de, author, image_url, categories (text[]), tags (text[]),
is_published (boolean), published_at (timestamptz)
## Rules
- All posts must be bilingual (EN + DE)
- German text should be natural, not machine-translated
- Use Markdown for body content
- Slugs: lowercase, hyphenated, descriptive
- Always include summary for both languages
- Categories: use existing categories when possible
- Tags: lowercase, hyphenated
When to Use Agents vs. Direct Prompting
Use agents when:
- You repeat the same type of task — reviewing code, running tests, creating content
- The task requires specific constraints — restricted tool access, particular output format
- You want consistency — the same review checklist, the same coding conventions
- You are delegating to a team — agents document your workflow expectations
Use direct prompting when:
- The task is one-off and unique
- You need flexibility to change approach mid-task
- The task is simple enough that constraints add overhead
Tips for Writing Good Agent Definitions
Be Explicit About What Not to Do
Constraints are as important as instructions. "Never delete tests" is more useful than "handle tests carefully."
Include a Workflow
Numbered steps give the agent a clear execution path. Without them, the agent may skip steps or work in an inefficient order.
Restrict Tools to the Task
A code reviewer that cannot edit files is less likely to start "fixing" things it should only flag. Tool restrictions are guardrails.
Test and Iterate
Agent definitions are code. Treat them that way — version them, refine them when they produce suboptimal results, and share them with your team.
Keep Them Focused
One agent per responsibility. A "do everything" agent is just a regular Claude Code session. The value of agents comes from specialization.
Sharing Agents Across Projects
Since agent definitions are just files in .claude/agents/, you can:
- Check them into version control alongside your project code
- Copy them between projects and adapt them
- Build a personal library of agents in your home directory''s
.claude/agents/for global access
The Bigger Picture
Custom agents in Claude Code are a lightweight way to encode your development workflows into reusable, composable units. They sit at the sweet spot between ad-hoc prompting and heavyweight automation frameworks.
Start with one agent for the task you repeat most. Refine it over a week. Then build the next one. Within a month, you will have a personalized toolkit that makes you significantly faster — not because the AI is doing everything, but because you have taught it exactly how you like things done.
