In short
Claude Code agents, also called subagents, are specialist assistants Claude Code can hand a task to. Each one has its own instructions, its own context window and its own set of tools, so it can review or research without cluttering your main session. They are perfect for reviews: a UI reviewer, an accessibility auditor, a copy editor. Below: how an agent file is built, a short example, and three ready-made review agents.
Updated
Where the file goes
Project agents go in .claude/agents/<agent-name>.md. Personal agents go in ~/.claude/agents/. You can also create and edit them with the /agents command in Claude Code.
Claude Code agents templates: structure
name
The agent's identifier, lowercase and hyphenated.
description
When Claude Code should use the agent. Specific triggers make it delegate at the right moments.
tools
Optional. Limit a review agent to reading tools so it reports instead of editing.
Instructions
The agent's role, what to check, in what order, and the exact format of its report.
A short example
--- name: ui-reviewer description: Reviews UI changes against design/template.html. Use after building a page, before saying it is done. tools: Read, Grep, Glob --- You are a senior product designer. Check spacing, type, colour tokens, states and mobile layout. Return a fix list grouped by severity, with file and line for each item.
Creating a Claude Code subagent, step by step
Choose a job that benefits from a fresh pair of eyes: reviewing a change, auditing accessibility, checking copy or researching across many files. Subagents shine when the work would clutter your main conversation.
Run /agents in Claude Code or create .claude/agents/<name>.md. Give it a name, a description that says when to use it, and, for review agents, only read tools so it reports instead of editing.
Write the instructions as a role, a checklist and an output format. The output format matters most: a list grouped by severity with file and line for each item is easy for the main session to act on.
Use it after building something: ask Claude Code to run the UI reviewer, read the report, then let the main session fix the must-fix items.
Ready-made Claude Code agents templates files
Complete files you can copy into your project and fill in. Each one works with the BrowserMoon design templates, so what the tool builds also looks professional.
UI review agent
A Claude Code subagent that reviews a page against your design template and returns a fix list: spacing, type, colour, states and mobile layout.
.claude/agents/ui-reviewer.md--- name: ui-reviewer description: Reviews UI changes against design/template.html and the design rules. Use after building or changing a page or component, before saying the work is done. tools: Read, Grep, Glob, Bash --- You are a senior product designer reviewing a pull request for visual quality. You do not write features; you find design problems and say exactly how to fix them.
Accessibility auditor agent
A Claude Code subagent that audits changed UI for accessibility: contrast, labels, keyboard use, focus and screen reader text.
.claude/agents/accessibility-auditor.md--- name: accessibility-auditor description: Audits UI changes for accessibility problems. Use after building forms, navigation, modals or any interactive component, and before release. tools: Read, Grep, Glob, Bash --- You are an accessibility specialist. Review the changed UI files against WCAG 2.2 AA and report problems with exact fixes. Do not change features.
Copy editor agent
A Claude Code subagent that rewrites interface and landing page copy to be short, clear and specific, without touching the code around it.
.claude/agents/copy-editor.md--- name: copy-editor description: Edits user-facing copy in pages and components for clarity and brevity. Use when the user asks to improve copy, or before shipping a landing page. tools: Read, Edit, Grep, Glob --- You are a product copy editor. You change only user-facing strings: headings, body text, buttons, labels, errors, empty states. Never change logic, layout or class names.
Using Claude Code agents with a design template
A UI review agent is only as good as what it compares against. Point it at design/template.html, and it can check spacing, type, colours and components against a real design instead of general taste.
Pair it with the CLAUDE.md design section: the main session builds to the rules, and the agent checks it did.
SaaS landing page · Analytics dashboard · Pricing section · Dark gradient hero · Account settings · AI chat interface
Best practices
- ·Give review agents read-only tools. They should report; the main session decides what to change.
- ·Define the output format precisely, such as a list grouped by severity with file and line.
- ·Say "use after..." in the description so Claude Code calls the agent at the right time.
- ·Use agents for work that needs a fresh context: reviews, audits and research across many files.
Common mistakes and how to fix them
Giving a reviewer write access
Limit review agents to Read, Grep and Glob so they report and you decide.
No output format
Specify exactly how findings are listed, or every report looks different.
Vague descriptions
Say "use after building a page" so Claude Code delegates at the right moment.
Too many agents
Start with two or three that you actually use; add more when a job keeps repeating.
Subagents vs skills
These files tell Claude Code how to work. A design template tells it what to build. Use both.
Claude Code templatesFrequently asked questions
What are Claude Code agents?
Subagents: specialist assistants with their own instructions, context and tools. Claude Code hands them a task and gets back a result, keeping the main session focused.
Where do Claude Code agent files go?
In .claude/agents/ in your project, or ~/.claude/agents/ for personal agents. Each agent is one markdown file.
How do I create a Claude Code agent?
Write a markdown file with name, description and optional tools in the frontmatter, and the instructions below. Or run /agents in Claude Code.
When should I use an agent instead of a skill?
Use an agent when the task benefits from a separate context, like a review or audit across many files. Use a skill when you want extra instructions in the current session.
Can agents run in parallel?
Yes. Claude Code can start several subagents for independent work, such as reviewing different parts of a change.
Can an agent use a different model?
Yes, an agent file can set its own model, so a quick check can run on a faster model.
Where should a review agent look for the design?
At your design template file and the design rules in CLAUDE.md, both named in the agent's instructions.
Are agents shared with my team?
Project agents in .claude/agents are, through git. Personal ones in ~/.claude/agents are just yours.
Claude Code templates by category
Related