Specialized agents

Four tools everyone calls "agents"

In Claude Code, the word "agent" covers four different mechanisms. Mixing them up wastes time and tokens (a token is the unit of text the model reads and writes, and what you're billed on).

This chapter covers the first two in detail, the ones you'll use every day. Workflows and agent teams get a quick intro at the end of the chapter, with the details in chapter 18.

Specialized commands

Out of the box, Claude Code is a generalist. It can do everything, but without guidelines it makes inconsistent choices: the wrong color palette, a file put in the wrong place, a forgotten business rule.

A specialized command fixes that. It's briefed on its domain: which files it touches, which rules it follows, how it checks its work.

Same logic as in a restaurant: the chef knows the kitchen rules, and nobody asks them to do the bookkeeping.

1. Create the folder

Create a .claude/commands/ folder at the root of your project. Every .md file in it becomes a slash command. Since January 2026, commands and skills have been merged: .claude/commands/front.md and .claude/skills/front/SKILL.md both create /front. The skill format (a folder) is for when you want to ship extra files alongside the prompt.

your-project/
  .claude/
    commands/
      front.md       → /front (interface)
      back.md        → /back (business logic)
      database.md    → /database (database)
      qa.md          → /qa (quality)
      orchestrate.md → /orchestrate (project lead)

2. Structure of a command file

Each file answers 4 questions:

1. Who are you? The role and specialty
2. What do you work on? The files and folders involved
3. What rules do you follow? The domain's conventions
4. How do you check your work? The validation commands

Add a description in the frontmatter (the block between --- at the top of the file). That's what Claude reads to know when to suggest the command. Without it, it takes the first line of the file, which is rarely written for that. Chapter 8 shows the exact format.

The 6 typical commands for a SaaS

Frontend, /front

Handles everything visible: pages, components, layouts, design.

# /front - Frontend

You handle UI components, pages, layouts and the design system.

## Scope
- src/app/ (all pages and layouts)
- src/components/ (reusable components)
- src/app/globals.css (global styles)

## Palette
- Primary: #E8634A - buttons, active links
- Background: #FFFBF7 - page background
- Never use a color outside the palette

## Rules
- Server Components by default
- shadcn/ui for all base components
- UI copy in the app's language, spelled correctly
- One component per file, kebab-case

## Verification
After each change: npm run typecheck && npm run lint

Backend, /back

Handles business logic, APIs, authentication.

# /back - Backend

You handle Server Actions, business logic and integrations.

## Scope
- src/lib/actions/ (Server Actions)
- src/lib/validators/ (Zod schemas)
- src/app/api/ (API routes)
- src/middleware.ts

## Rules
- Every mutation goes through a Server Action, not an API route
- Zod validation required on every input
- Check authentication in every action
- Never expose an API key on the client side

## Verification
After each change: npm run typecheck && npm run lint

Database, /database

Handles the SQL schema, migrations, security (RLS, Postgres's row-by-row access rules).

# /database - Database

You handle the PostgreSQL schema, migrations and RLS policies.

## Scope
- supabase/migrations/ (numbered SQL files)
- src/lib/types/database.types.ts (auto-generated types)

## Rules
- Any change → new numbered SQL migration
- RLS enabled on every table, filtered by organisation_id
- Never run supabase db reset

## Verification
npx supabase migration up --local
npx supabase gen types typescript --local > src/lib/types/database.types.ts
npm run typecheck

AI, /ia

Handles AI API integration, prompts, streaming.

# /ia - AI integration

You handle the Claude API integration, prompts and streaming.

## Scope
- src/lib/ai/ (client, prompts, rate-limit)
- src/app/api/ai/ (AI endpoints)

## Rules
- Always server-side, never an exposed API key
- Streaming via the Anthropic SDK
- Usage tracking in ai_usage after every call
- Rate limiting per user plan

QA, /qa

Handles tests, lint, typecheck.

# /qa - Quality

You handle tests and code quality.

## Quality Gates
| Gate | Command | When |
|------|---------|------|
| TypeScript | npm run typecheck | After each change |
| Lint | npm run lint | After each change |
| Unit Tests | npm run test | Before commit |
| Build | npm run build | Before deploy |

## Rules
- Unit tests for all business logic
- No tests for trivial boilerplate
- Minimum coverage: 80% on critical modules

Orchestrator, /orchestrate

Coordinates the rest. It's the project lead, and the only one on the list that has a reason to launch subagents.

# /orchestrate - Project lead

You supervise the execution of a plan.

## Workflow
1. Read the plan in docs/plans/
2. Independent tasks → one subagent per task, in parallel
3. Dependent tasks → sequential, in the main conversation
4. Check typecheck + lint after each group

## Quality Gates
- TypeScript: 0 errors
- Lint: 0 errors
- Build: success
- Tests: all pass

Using a command

You type the slash command, followed by your request:

/front Create a notification banner component that shows a temporary message at the top of the page, with a close button and a slide-in animation.

/front already knows it has to work in src/components/, stick to the palette, go through shadcn/ui and check with typecheck + lint. Without the command, you'd have had to write all that in your prompt.

You're not limited to these 6. An /email, a /deploy: create a command for any recurring need. The rule: if you repeat the same instructions more than 3 times, it deserves a file.

Subagents

A subagent works the opposite way from a command. You describe a goal, Claude delegates.

Since Claude Code version 2.1.198 (July 1, 2026), subagents run in the background by default. You keep talking to Claude while they work, and they notify you when they're done. Claude can launch up to 20 in parallel.

Creating a subagent

The interactive /agents wizard was removed in v2.1.198. There are two ways to do it today.

The simplest: ask Claude.

"Create an explorer subagent in .claude/agents/ that maps an area of the code and returns the list of key files with a one-line explanation each. Haiku model."

By hand: a markdown file in .claude/agents/ (for the project) or ~/.claude/agents/ (for all your projects).

---
name: explorer
description: Maps an area of the code and returns the key files. Use before changing a part of the project you don't know.
model: haiku
---

You explore the code in read-only mode.
Return the list of relevant files, one line per file,
then the 3 things to watch out for before changing this area.
Don't modify any file.

The description matters as much as the prompt: it's what Claude reads to decide when to delegate. The model: field picks the subagent's model. Haiku is enough to explore, read logs or find a file, and costs much less than Opus.

The Agent tool and worktree isolation

To launch a subagent, Claude uses the Agent tool (it was called Task in older versions and old tutorials). The option to know is isolation: "worktree": the subagent gets its own git worktree, a separate copy of the repo on a dedicated branch. Since v2.1.222 (early August 2026), that isolation also covers its edits and its Bash commands.

Without a worktree, two subagents writing to app/page.tsx at the same time step on each other. With one, each has its own sandbox and you merge at the end.

Example: translating 3 articles from FR to EN

Three MDX articles, independent of each other. Three subagents in parallel, each on its own worktree.

What Claude sends (pseudo-code):

Agent({
  description: "Translate article 1",
  prompt:
    "Translate content/fr/article-1.mdx to content/en/article-1.mdx. Keep the MDX structure and the frontmatter. Casual tone.",
  isolation: "worktree",
});

Agent({
  description: "Translate article 2",
  prompt:
    "Translate content/fr/article-2.mdx to content/en/article-2.mdx. Same rules: MDX structure, frontmatter, casual tone.",
  isolation: "worktree",
});

Agent({
  description: "Translate article 3",
  prompt:
    "Translate content/fr/article-3.mdx to content/en/article-3.mdx. Same rules: MDX structure, frontmatter, casual tone.",
  isolation: "worktree",
});

All 3 run in the background. Each writes its file in its own worktree, Claude collects the results and merges. You only typed one sentence: "Translate these 3 articles in parallel, one subagent per article."

The fork: a subagent that inherits your conversation

• Claude launches it with subagent_type: "fork" in the Agent tool.
• /subtask <task>: you launch a forked subagent yourself on a specific task.
• /fork [prompt]: copies your conversation into a background session, with its own worktree. You keep going here, the copy moves forward on its own.

Workflows and agent teams, briefly

Workflows (since late May 2026): you add the ultracode keyword to your request ("ultracode: audit every API endpoint"). Claude then writes a script that Claude Code runs in the background across dozens, sometimes hundreds of subagents. /workflows lists the ones running and lets you save them in .claude/workflows/ to run them again. On Pro, you turn it on in /config, at a reduced size by default.

Agent teams: several Claude sessions coordinating with each other. Still experimental (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), and Anthropic's docs mention roughly 7 times more tokens than a standard session when teammates run in plan mode. Keep them for big projects.

Both, along with /goal, /loop and routines, are covered in detail in chapter 18.

When to use what

The rule: subagents when tasks are independent. If they depend on each other, stay sequential in your conversation.

What it costs

A subagent doesn't read your conversation's cache. It starts from zero, and its cache only lasts 5 minutes, even on a subscription (your main conversation gets 1 hour). Only the fork reuses the parent's cache.

In practice:

• To read 50 files or logs, a haiku subagent costs less than loading everything into your Opus session, and your main context stays light.
• For a small task that needs all your context, a fork is cheaper than a subagent you'd have to re-explain everything to.
• Launching 20 subagents means 20 contexts filling up. You save time, your consumption doesn't go down.

The details of caching and billing mechanics are in chapter 19.

Sources

• Official Claude Code changelog
• Workflows, Claude Code documentation
• Manage costs, Claude Code documentation
• Prompt caching in Claude Code