Slash commands and subagents

User-defined /commands and specialized subagent definitions you can ship with your project or install globally.

What it is

A slash command is a reusable prompt invoked with /name. Drop a markdown file in .claude/commands/<name>.md (project) or ~/.claude/commands/<name>.md (personal); Claude Code wires it up automatically. Slash commands have largely converged with Skills — both create /name shortcuts, but a skill folder under .claude/skills/ also supports autonomous activation.

A subagent is a separately-scoped Claude instance with its own context window, tools, and system prompt. Define one in .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (personal). Claude’s orchestrator can spawn defined subagents via the Task tool; by default up to 20 can run concurrently (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), and a subagent can itself spawn subagents up to 3 layers deep by default (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH) — that depth default has moved around release to release, so don’t trust an old number you’ve seen elsewhere. As of v2.1.198 (2026-07-01) subagents run in the background by default: Claude keeps working and is notified when each finishes, and each inherits the session’s extended-thinking configuration. To launch one yourself, run /subtask (v2.1.212, 2026-07-17 — this took over the in-session subagent behavior /fork used to have; /fork now copies the whole conversation into a separate background session instead). There’s no cap on the total number of subagents a session can spawn over its lifetime — a 200-subagent-per-session limit was removed in v2.1.224 (2026-08-07); only the concurrency and depth limits above still apply. As of v2.1.232 (2026-08-13), a fork subagent (subagent_type: "fork") — one that inherits the full parent conversation and reuses its prompt cache, instead of starting with an isolated context — runs by default whenever the orchestrator chooses that type; this is the same mechanism /fork uses, just available to any subagent spawn.

When to use it

  • Slash command: you want a manual, repeatable entry point for a workflow.
  • Subagent: you want Claude to delegate a sub-problem (code review, debugging) into a fresh context.
  • Both: complex pipelines where a /review command spawns a security-reviewer subagent.
  • Skill instead: if you want autonomous activation alongside /name invocation.

How to install / enable

Create the file and start a new session.

mkdir -p .claude/commands
cat > .claude/commands/security-scan.md <<'EOF'
---
allowed-tools: Read, Grep, Glob
description: Run a security review of the codebase
---
Look for SQL injection, XSS, exposed credentials, and insecure configs.
Report findings with severity and remediation.
EOF

For a subagent, write .claude/agents/<name>.md with name, description, tools, and (optionally) model and permissionMode in the frontmatter, then a system prompt body.

Common pitfalls

  • Forgetting YAML frontmatter — slash commands work without it; subagents need at least name and description.
  • Granting too many allowed-tools. Scope tightly. As of v2.1.152 (May 2026) slash commands and skills can also set disallowed-tools: in frontmatter to remove specific tools while the command is active — useful for read-only review commands.
  • Expecting subagents to share context with the parent — they don’t.
  • Putting team-shared commands in ~/.claude/ instead of .claude/ (they won’t be committed).

See also

Sources

  • Slash Commands in the SDK — Anthropic docs; verified 2026-05-19 (this run).
  • Slash Commands (platform docs) — Anthropic docs; verified 2026-05-19.
  • Claude Code customization guide — Alex Op; verified 2026-05-19.
  • Claude Code changelog (v2.1.152–v2.1.224) — disallowed-tools frontmatter on slash commands and skills (v2.1.152); subagents run in background by default and inherit session extended-thinking config (v2.1.198, 2026-07-01); /fork now copies the conversation into a background session while the in-session subagent launcher becomes /subtask (v2.1.212, 2026-07-17); 200-subagent-per-session spawn cap removed (v2.1.224, 2026-08-07); verified 2026-08-08 (this run).
  • Subagents reference — Anthropic docs; verified 2026-08-15 (this run) — current defaults: 20 concurrent subagents (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, exempt when ultracode is active) and 3 layers of nesting depth (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH); depth default was 5 through v2.1.216, dropped to 1 in v2.1.217–218, restored to 3 in v2.1.219; no limit on total subagents spawned over a session’s lifetime; confirms fork subagents inherit the full conversation and reuse the parent’s prompt cache, cheaper than a fresh subagent for same-context tasks.
  • Claude Code changelog (v2.1.232, 2026-08-13) — Anthropic docs; verified 2026-08-15 (this run) — “subagent forking is now on by default: a subagent_type: \"fork\" subagent inherits the full conversation and prompt cache, and non-teammate agent spawns in interactive sessions now run in the background by default.”