Subagents

A subagent is a second Claude session your main agent can call. It gets its own context, its own tool allowlist, and usually its own system prompt. When it finishes, it summarises its work back to the caller and disappears.

Use subagents when you want a narrow job done well without polluting your main thread.

Where subagents live

Subagents are plain markdown files with YAML frontmatter.

~/.claude/agents/         # available to you in every project
.claude/agents/           # shared with the team via git

A minimal definition looks like this.

---
name: apex-reviewer
description: Reviews Apex classes for bulkification, governor limits, and test gaps.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior Salesforce engineer reviewing Apex for production readiness.

Focus on:
- Bulkification and SOQL inside loops
- CPU, heap, and callout governor limits
- Sharing model and CRUD/FLS where relevant
- Test coverage gaps and assertion strength

Return a scored markdown report grouped by file. No code edits.

The tools line restricts what the subagent can do. For a reviewer, read-only tools are safer. For a scaffolder, give it Write and Edit.

Invoking a subagent

Three ways, in order of how often you'll use them.

1. Mention by name. In your main prompt, say "use the apex-reviewer subagent to check ContactService.cls." The lead agent spawns it.
2. /agents. Lists every subagent Claude Code can see and lets you run one directly.
3. From another subagent or skill. A skill body can say "delegate to the apex-reviewer subagent for any .cls files."

Subagent vs agent team

Both run multiple Claude sessions at once. The difference is coordination.

If no one needs to debate, use a subagent.

Five SF subagent patterns

1. Apex reviewer

Shown above. Hand it a class, get back a scored report with file-by-file findings. Pair it with the sf-apex skill if you have one installed.

2. Permission set auditor

---
name: permset-auditor
description: Audits permission sets and groups for stale references, missing FLS, and access drift.
tools: Read, Grep, Glob, Bash(sf org:list:metadata*)
model: sonnet
---

You audit permission set metadata in force-app/main/default/permissionsets/
and permissionsetgroups/.

For each permset:
- List every object, field, Apex class, tab, and page reference
- Flag references that no longer exist in force-app
- Flag missing FLS on custom fields used by LWCs or flows
- Output a table with severity (high, medium, info)

Useful before packaging or before hand-off to a customer's release team.

3. Deploy validator

---
name: deploy-validator
description: Runs validation-only deploys against a target org and summarises failures.
tools: Read, Bash(sf project deploy validate*), Bash(sf project deploy report*)
model: sonnet
---

Given a target org alias, run a validation-only deploy of the current
force-app source. Do not run destructive operations.

Return a summary with: test coverage, test failures, component errors.
Group errors by file. Do not attempt fixes.

Safe to run against customer sandboxes because the tool allowlist blocks anything destructive.

4. Flow test runner

---
name: flow-test-runner
description: Runs Flow tests across the project and reports coverage by flow.
tools: Read, Bash(sf flow test run*), Bash(sf flow test report*)
model: haiku
---

Run every Flow test in the project against the default org. Return a table
of flow name, tests run, pass rate, and coverage percentage.

Flag any flow below 75% coverage.

Haiku is fine here because the job is rote. Save Sonnet tokens for the harder work.

5. SOQL consultant

---
name: soql-consultant
description: Helps write and optimise SOQL. Does not execute queries without confirmation.
tools: Read, Grep, Bash(sf data query*)
model: sonnet
---

You help draft SOQL and explain query plans.

Rules:
- Never execute a query that returns more than 2000 rows without explicit approval
- Always prefer indexed fields (Id, Name, CreatedDate, custom indexed fields)
- For selective filtering, explain which field is driving selectivity
- For non-selective queries, suggest an index or a redesign

The explicit "never execute above N rows" line is the guardrail. Subagents follow system prompts carefully.

Or install a pre-built pod: Jag's FDE agents

If you ran the Jag's SF Skills full installer, you already have 7 production-grade subagents in ~/.claude/agents/. You don't need to write yours from scratch. Read theirs first; they're the clearest reference for production subagent frontmatter.

The pod is modeled after a real Forward Deployed Engineering team:

fde-strategist                     Plans, delegates up to 4 concurrent workers, no edits
├── FDE team (agent-specific)
│   ├── fde-engineer               Bot metadata, topics, actions, Apex, Agent Scripts
│   └── fde-experience-specialist  Persona, conversation design, utterances, LWC
├── Cross-cutting (both teams)
│   ├── fde-qa-engineer            Apex + agent testing, debug logs, session tracing
│   └── fde-release-engineer       Deploys, Connected Apps, Agent Script CLI, CI/CD
└── PS team (platform infrastructure)
    ├── ps-technical-architect     Service Apex, integrations, data, LWC, performance
    └── ps-solution-architect      Metadata, Flows, permissions, Mermaid diagrams

Every agent is a single .md file with YAML frontmatter declaring its model, permissionMode, tools, disallowedTools, and bound skills. The strategist runs in plan mode with Edit and Write disabled; the six implementers run in acceptEdits with a constrained tool allowlist.

The full roster

Invoking the pod

You don't address the specialists. You ask the strategist and it plans, delegates, and consolidates:

Use the fde-strategist agent. Goal: stand up a Customer Service Triage
Agentforce agent for ACME in the acme-uat org. Topics for warranty,
billing, and shipping. Include a companion LWC, a Connected App for the
mobile channel, and an agent test suite covering all three topics plus
an ambiguous utterance. Target org alias: acme-uat. Never deploy to
anything containing "prod".

A plausible plan:

1. ps-solution-architect drafts objects, permset group, and a Mermaid architecture diagram.
2. fde-engineer scaffolds bot metadata, topics, and invocable Apex.
3. fde-experience-specialist writes the persona doc and LWC in parallel with step 2.
4. ps-technical-architect builds service Apex for the actions.
5. fde-qa-engineer creates the agent test suite and Apex tests.
6. fde-release-engineer runs a dry-run deploy against acme-uat and reports.

Up to four of those run concurrently. The strategist consolidates and asks before anything gets deployed.

See Jag's SF Skills for the install path.

Writing a good subagent

Four things make the difference between a useful subagent and a wasted turn.

1. One job. "Reviewer" beats "reviewer and refactorer and doc writer." If it's two jobs, make two subagents.
2. Narrow tool allowlist. Don't give a reviewer Write. Don't give a query helper Bash(*).
3. Return format. Say explicitly what comes back: markdown table, PR diff, JSON, a short summary. Vague output means a vague result.
4. Hard constraints. Write them as rules in the body. "Never X. Always Y." The agent follows them.

When to skip a subagent

• The task is a single step your main agent can do in one turn.
• The work needs live back-and-forth and you aren't ready to write a brief.
• The files the subagent needs are already loaded in your main context. Spawning just re-reads them.

Subagents are also not free. Each one burns a fresh context window. Three narrow subagents are usually cheaper than one agent trying to hold the whole world, but one subagent spawned for a 200-token task is just waste.

Next

• Agent Teams for when the workers need to coordinate instead of just reporting back.
• Skills for capability packs a subagent can load.
• Hooks and Custom Commands for automation that kicks off a subagent on its own.