Agent Fundamentals

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:

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.

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 the sub-agent design notes.

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.

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