Five ways to build specialist agents in Claude Code: Task sub-agents, .claude/agents YAML, custom slash commands, CLAUDE.md personas, and perspective prompts.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
Problem: A real project usually wants more than one head on the work. A security pair of eyes. A performance pair. Someone keeping the docs honest. Holding all those roles in one chat burns focus and time.
Quick Win: Hand a parallel job to a sub-agent. It runs on its own, then drops what it found back into your main session.
Understanding: Claude Code gives you several ways to get agent-style behavior, from built-in sub-agents to your own slash commands. Each earns its keep on different jobs. Get the basics down before reaching for the fancier patterns.
Here are the five paths Claude Code offers, side by side:
| Approach | Best For | Persistence |
|---|---|---|
| Task Tool (Sub-agents) | Parallel execution, isolated work | Session only |
.claude/agents/ Definitions | Persistent specialist sub-agents | Permanent |
| Custom Slash Commands | Reusable workflows, team sharing | Permanent |
| CLAUDE.md Personas | Project-wide behavior rules | Permanent |
| Perspective Prompting | Quick context switches | Single request |
Every path has a trade-off. Sub-agents win on parallel work. .claude/agents/ definitions hand sub-agents a name that sticks. Slash commands shine on reusability.
Use this page to decide which primitive you are actually reaching for. If you already know you want multiple agents and the open question is coordination shape, read Agent Patterns. If you need several Claude sessions collaborating as peers instead of subagents reporting to one lead, jump to Claude Code Agent Teams.
If you are unsure which path to reach for, do not start with the fanciest one. Move down this ladder:
Is this just a one-off perspective shift? Use perspective prompting.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
Is this a repeatable workflow you want to trigger on demand? Use a slash command.
Is this a persistent specialist Claude should be able to route to automatically?
Use .claude/agents/.
Do you need parallel work or isolated context right now? Use a sub-agent through the Task tool.
Should the rule apply to every session in the repo?
Put it in CLAUDE.md.
That order matters because it keeps you from overbuilding. Most teams should earn their way from prompts to commands to persistent agents, not jump straight to a giant specialist fleet.
Inside your session, the Task tool spins up small Claude Code instances. Every sub-agent gets a fresh context window, runs independently, and ships results back to the orchestrator.
Why sub-agents matter:
Ctrl+B)New: Sub-agents Claude spawns can now sit in the background. Hit Ctrl+B, and the main agent stays free for other chat. Results pop back up the moment they finish. Full walkthrough in the async workflows guide.
For deeper orchestration patterns, see Agent Patterns.
Sub-agents can also live on disk. Drop a Markdown file into a dedicated agents/ directory, YAML frontmatter at the top, and you have a custom sub-agent definition. These are not slash commands. Slash commands are prompts you call by hand. An agent definition sets up a persistent sub-agent that Claude's orchestrator picks up on its own when the task fits.
Two scopes for agent definitions:
.claude/agents/) - Specific to your repository, shareable with your team via git~/.claude/agents/) - Available across all your projects, personal to your machineA sub-agent declared in .claude/agents/ reads your project's CLAUDE.md just like the main session does. Coding standards, conventions, project rules all carry over without extra wiring.
Controlling the sub-agent model: Set CLAUDE_CODE_SUBAGENT_MODEL in your environment to point sub-agents at a specific model. Useful for cost trims (a lighter model for sub-agents), or for tasks that benefit from heavier reasoning.
Claude can be told which sub-agents it is allowed to call, using Task(AgentName) permission rules. Drop them into the deny array of your settings.json, or pass them at the command line through --disallowedTools.
That keeps the Explore sub-agent from being spawned. Built-in agent names cover Explore, Plan, and Verify. Agents can also be turned off at launch.
Reach for this in sensitive environments where you want a tighter leash on agent behavior, or when autonomous exploration is eating too many tokens.
Reusable slash commands live as Markdown files in .claude/commands/. Run /project:security-review src/auth/ and your specialist gets to work.
Command locations:
.claude/commands/ - Project-specific, shareable via git~/.claude/commands/ - Personal, available everywhereEvery interaction in your project runs through whatever sits in CLAUDE.md. The file ends up shaping how Claude shows up by default. Agent-style consistency, without ever calling the agent by name.
For a one-off look, ask Claude to put on a specific perspective. Zero setup. Specialized analysis right away.
Use sub-agents when: You want parallel runs, or you need isolated context across several tasks.
Use .claude/agents/ when: You want named specialist agents that stick around, and Claude's orchestrator picks them up by task type on its own.
Use slash commands when: The same workflow keeps coming back across sessions, or you want to share it with the team.
Use CLAUDE.md when: The behavior should apply everywhere, on every interaction, automatically.
Use perspective prompting when: You want a quick, one-time take from a different angle.
If you occasionally want a second pair of eyes on auth, permission checks, or secrets handling:
This is better than a permanent agent definition if the need is occasional.
If you keep writing docs, changelogs, or blog posts with the same quality gates:
That is the clean reusable middle ground.
If your repo has recurring frontend, backend, database, or security work:
.claude/agents/That is where persistent agents start paying off.
In practice, well-developed Claude Code setups run all five at once. Persistent definitions for specialist roles. Slash commands for repeat workflows. CLAUDE.md for project-wide standards. Sub-agents for parallel jobs. The ClaudeFast Code Kit ships 18 pre-configured agents (security auditor through frontend specialist), plus the slash commands and routing rules already in place, so the patterns are visible before you build your own.
Next Action: Pick a workflow you run often, and turn it into a slash command under .claude/commands/. From there, dig into the distribution strategies the harder orchestration work needs.
Explore More Agent Concepts: