Custom Commands & Subagents Basics

7 examples to get you started with Custom Commands & Subagents - 5 basic and 2 intermediate.

Prerequisites

• A working Claude Code install, invoked from your project's root directory.
• A project-scoped commands directory at .claude/commands/ (created on demand, no install step required).
• No extra packages. Commands are just markdown files; subagents are spawned through the built-in Agent tool, nothing to configure up front.

Basic Examples

1. Create a Commands Directory

Every custom command lives as a markdown file under .claude/commands/.

mkdir -p .claude/commands

• Claude Code scans this directory automatically; no registration step is needed beyond creating the file.
• Commands here are project-scoped and get checked into version control alongside the rest of the repo.
• A user-level equivalent also exists for commands you want available across every project, but project-scoped is the right default for team-shared commands.

2. Write a One-Line Slash Command

The simplest command is a frontmatter header plus a single prompt sentence.

---
description: Summarize the current git diff in plain language
---
 
Summarize the currently staged git changes in two or three sentences, written for a teammate who has not seen the diff yet.

• Save this as .claude/commands/summarize-diff.md and the command becomes available as /summarize-diff.
• The description frontmatter field is what shows up when a user tab-completes available commands.
• The body below the frontmatter is sent into the conversation exactly as typed, as if the user had pasted it themselves.

3. Invoke the Command

Once the file exists, the command is live immediately, no restart required.

# inside a Claude Code session
/summarize-diff

• Typing /summarize-diff inserts the file's prompt body into the conversation and runs it right away.
• Because the prompt is stored on disk, every teammate who pulls the repo gets the identical command.
• Editing the markdown file changes the command's behavior the next time it is invoked, no rebuild step involved.

Related: Writing Your First Custom Slash Command with Markdown Frontmatter - the full frontmatter schema

4. Accept Arguments in a Command

Commands can reference the text typed after the command name.

---
description: Explain a specific file's purpose
---
 
Read $ARGUMENTS and explain what it does, who calls it, and any non-obvious side effects, in under 150 words.

• $ARGUMENTS is replaced with whatever the user typed after the command name, e.g. /explain-file lib/auth.ts.
• This turns a one-off command into a reusable template instead of a fixed, hardcoded prompt.
• If no arguments are given, $ARGUMENTS is empty, so word the prompt to degrade gracefully or note that a target is required.

5. Spawn a Single Subagent

A subagent is a separate Claude instance with its own context, launched to handle one bounded task.

# a plain-language request in the main session, not a shell command
# "Use a subagent to find every place notification emails are sent
#  in this codebase and summarize the trigger conditions for each."

• The subagent explores the codebase in its own isolated context and returns only a summary to the main session.
• None of the subagent's intermediate file reads or search steps pollute the parent conversation's context window.
• This is the right move when a task is exploratory and would otherwise burn a lot of context on dead ends.

Related: How Subagents Get Their Own Context and Tools - why the isolation exists

Intermediate Examples

6. Combine a Command with a Subagent Request

A command's prompt body can itself ask Claude to delegate to a subagent.

---
description: Audit a feature area and report findings, without derailing the main session
---
 
Use a subagent to research how $ARGUMENTS is implemented across this codebase:
entry points, data flow, and any tests that cover it. Have the subagent report
back a concise summary (file paths and a short description each), not full file contents.

• Saved as .claude/commands/audit-feature.md, this makes /audit-feature payment retries a repeatable one-liner that always delegates the same way.
• The main session only ever sees the subagent's summary, keeping its own context free for the actual fix or feature work that follows.
• Wording the prompt to explicitly ask for "a concise summary, not full file contents" matters, since a subagent will otherwise report back everything it found.

7. Fan Out Several Subagents from One Command

For larger audits, a single command can ask for multiple subagents to run against independent parts of the codebase at once.

---
description: Research three subsystems in parallel and compare their patterns
---
 
Spawn three subagents in parallel, one each for: the authentication code,
the billing code, and the notifications code. Each subagent should report
back the error-handling pattern it finds in its area. Then compare the
three patterns and note any inconsistency worth fixing.

• Because each subagent gets its own isolated context, the three research tasks do not interfere with or contaminate each other's findings.
• Running them in parallel is faster than researching each subsystem sequentially in the main session.
• The main session only has to reason over three short summaries, not the full breadth of files each subagent actually opened.

Related: Spawning Parallel Subagents for Isolated Research Tasks - the fan-out pattern in depth

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.