Agent Fundamentals

Five ways to build specialist agents in Claude Code: Task sub-agents, .claude/agents YAML, custom slash commands, CLAUDE.md personas, and perspective prompts.

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.

The Task Tool

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:

• Isolated context keeps work on one task from leaking into the next
• Parallel runs cut the wall-clock time on multi-file analysis
• A sub-agent that fails does not take your main session down with it
• Background mode lets you keep working while they run (press 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.

Custom Sub-Agent Definitions

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:

• Project agents (.claude/agents/) - Specific to your repository, shareable with your team via git
• User agents (~/.claude/agents/) - Available across all your projects, personal to your machine

A 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.

Restricting Sub-Agent Access with Permission Rules

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.

Custom Slash Commands

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 everywhere

CLAUDE.md Personas

Every 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.

Perspective Prompting: Quick Context Switches

For a one-off look, ask Claude to put on a specific perspective. Zero setup. Specialized analysis right away.

When to Use Each

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.

Three Practical Setups

1. Security review without permanent overhead

If you occasionally want a second pair of eyes on auth, permission checks, or secrets handling:

• keep your normal session
• spawn a security-focused sub-agent
• have it report findings only

This is better than a permanent agent definition if the need is occasional.

2. Content workflow you run every week

If you keep writing docs, changelogs, or blog posts with the same quality gates:

• use a slash command
• load the voice, workflow, and checklist there
• do not force that content context into every coding session

That is the clean reusable middle ground.

3. Domain specialist you want Claude to route to naturally

If your repo has recurring frontend, backend, database, or security work:

• define persistent specialists in .claude/agents/
• keep the domain rules close to the agent
• let the orchestrator pick them up when the task fits

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:

• Sub-Agent Best Practices - When to use parallel, sequential, or background execution
• Sub-Agent Design - Architecture patterns for orchestrating multiple agents
• Custom Agents - Build specialized agents with slash commands
• Agent Patterns - Proven design patterns for agent systems
• Human-Like Agents - Create agents with distinct personalities