Creating Custom Commands

Every team has that one senior developer who always asks the right questions during code review. They check for error handling edge cases, verify that database queries use indexes, and catch the N+1 query before it hits production. Custom commands let you encode that developer’s judgment into a reusable /review command that any team member can run.

What You Will Walk Away With

• How to create custom slash commands from simple prompt templates to full agent workflows
• Subagent configuration patterns for code review, security auditing, and testing
• Techniques for sharing commands across your team via version control
• Strategies for building a library of domain-specific commands

Creating Custom Slash Commands

Custom commands in Claude Code are markdown files that live in specific directories. When you type / in the REPL, these appear alongside built-in commands.

File Structure

Commands are .md files in these locations:

Location	Scope	Available As
.claude/commands/review.md	Project, shared with team	/review
~/.claude/commands/standup.md	Personal, all projects	/standup

The file name becomes the command name — no project: or user: prefix. Subdirectories are namespaced into the command name with a colon: .claude/commands/test/integration.md is invoked as /test:integration, not a bare /integration.

Note

Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Your existing .claude/commands/ files keep working, so everything below still applies. Skills are the recommended form going forward because they add a directory for supporting files and frontmatter that lets Claude load them automatically when relevant.

A Simple Review Command

Create .claude/commands/review.md:

Review the changes in the current git diff. For each file:

1. Check error handling: Are all async operations wrapped in try/catch? Do error responses include meaningful messages?
2. Check performance: Are there N+1 queries? Unnecessary re-renders? Missing indexes for new queries?
3. Check security: Is user input validated? Are SQL queries parameterized? Are secrets handled correctly?
4. Check tests: Do the changes have corresponding test coverage? Are edge cases tested?

Output format:
- Start with a one-line summary: PASS, NEEDS CHANGES, or BLOCKING
- List findings grouped by file
- For each finding, explain WHY it matters and suggest a specific fix

Now any team member can run /review and get a consistent, thorough code review.

Tip

Copy-paste prompt to invoke the command after staging your work:

/review

Stage the changes you want reviewed first (git add -p), then run /review in the REPL. The command reads the staged diff and returns a PASS / NEEDS CHANGES / BLOCKING verdict grouped by file.

Tip

Copy-paste command for a security-focused review:

Create .claude/commands/security-audit.md:

Perform a security audit of the current codebase changes (git diff HEAD).

Check for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication/authorization bypasses
- Sensitive data exposure (API keys, tokens, PII in logs)
- Insecure dependencies (check package.json changes)
- Missing input validation on API endpoints
- Hardcoded credentials or secrets

For each finding, rate severity as CRITICAL, HIGH, MEDIUM, or LOW.
Provide the exact file and line number, the vulnerability, and a specific fix.

Dynamic Commands with Variables

Commands can include $ARGUMENTS to accept input when invoked:

.claude/commands/explain.md

Explain the following code or concept in the context of this project: $ARGUMENTS

Focus on:
- What it does and why it exists
- How it connects to surrounding code
- Any non-obvious design decisions
- Potential gotchas for future maintainers

Usage: /explain the WebSocket reconnection logic in src/realtime/

Building Subagents

Subagents are specialized Claude Code instances with their own context window, tools, and instructions. They are ideal for tasks that require focused analysis without polluting your main session’s context.

Subagent File Format

Create .claude/agents/reviewer.md:

---
name: reviewer
description: "Expert code reviewer. Triggers automatically after code changes or when review is requested."
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
---

You are a senior code reviewer with expertise in TypeScript and Node.js.

When reviewing code:
1. Read the git diff first to understand the scope of changes
2. Check each modified file for:
   - Type safety issues (any types, missing null checks)
   - Error handling gaps
   - Performance concerns (unnecessary iterations, missing memoization)
   - Test coverage
3. Be specific: reference exact file paths and line ranges
4. Suggest concrete fixes, not vague improvements
5. Acknowledge good patterns when you see them

Output a structured review with APPROVE, REQUEST_CHANGES, or COMMENT verdict.

Subagent Configuration Options

These are the fields you set in the YAML frontmatter of a subagent file. Only name and description are required; the system prompt is the markdown body of the file.

Field	Required	Description
name	Yes	Unique identifier using lowercase letters and hyphens
description	Yes	When the agent should be triggered (Claude reads this to decide)
tools	No	Allowlist of tools the agent can use. Defaults to inheriting all tools
disallowedTools	No	Tools to explicitly deny, removed from the inherited or allowed list
model	No	sonnet, opus, haiku, fable, or inherit (defaults to inherit)
permissionMode	No	default, acceptEdits, dontAsk, bypassPermissions, or plan
skills	No	Skills to preload into the agent’s context at startup
hooks	No	Lifecycle hooks scoped to this subagent
memory	No	Persistent memory scope: user, project, or local

The prompt and maxTurns fields are not file-frontmatter keys — they only exist in the inline --agents JSON form shown below, where prompt carries the system prompt (since there is no markdown body).

Tip

Copy-paste subagent for automated test generation:

Create .claude/agents/test-writer.md:

---
description: "Generates comprehensive test suites. Use when new code needs tests or existing tests need expansion."
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
  - Bash
model: sonnet
---

You are a testing specialist. When asked to write tests:

1. Read the source file and understand its public API
2. Check existing tests for patterns (test framework, assertion style, mocking approach)
3. Generate tests covering:
   - Happy path for each public function/method
   - Edge cases (empty inputs, null values, boundary conditions)
   - Error cases (invalid inputs, network failures, timeouts)
   - Integration points (database calls, API calls)
4. Follow the existing test conventions in this project
5. Run the tests after writing them to verify they pass

Never mock what you can test directly. Prefer integration tests over unit tests for database operations.

Triggering Subagents

Subagents trigger in two ways:

1. Automatically: Claude reads the description field and decides when a subagent would be helpful. Good descriptions improve automatic triggering.
2. Explicitly: Ask Claude to “run the reviewer agent” or “use the test-writer to add tests for auth.ts.”

Tip

Copy-paste prompt to dispatch a subagent explicitly:

Use the test-writer agent to add edge-case tests for src/auth/session.ts. Mirror the existing Vitest patterns in tests/auth/, cover token expiry and refresh-race conditions, and run the suite when you're done.

Naming the agent and the exact file removes ambiguity, so Claude delegates instead of attempting the work in the main session.

CLI-Defined Subagents

For temporary or experimental agents, define them on the command line:

claude --agents '{
  "performance": {
    "description": "Analyzes code for performance bottlenecks",
    "prompt": "You are a performance engineer. Profile and analyze code for bottlenecks. Focus on algorithmic complexity, memory allocation, and I/O patterns.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Building a Team Command Library

Organizing Commands by Workflow

.claude/
  commands/
    review.md            # /review        -- General code review
    security-audit.md    # /security-audit -- Security-focused review
    explain.md           # /explain        -- Code explanation with context
    refactor.md          # /refactor       -- Guided refactoring workflow
    test/
      unit.md            # /test:unit        -- Generate unit tests
      integration.md     # /test:integration -- Generate integration tests
      e2e.md             # /test:e2e         -- Generate end-to-end tests
    deploy/
      checklist.md       # /deploy:checklist -- Pre-deployment verification
      rollback.md        # /deploy:rollback  -- Rollback assistance
  agents/
    reviewer.md          # Code review subagent
    test-writer.md       # Test generation subagent
    debugger.md          # Debugging specialist

A subdirectory becomes a colon-namespaced prefix, so commands/test/unit.md is invoked as /test:unit. The equivalent skills layout puts each workflow in its own directory — .claude/skills/test-unit/SKILL.md — which buys you supporting files and automatic invocation.

Sharing Commands via Git

Since .claude/commands/ and .claude/agents/ are regular files in your repository, they are automatically shared when committed:

git add .claude/commands/ .claude/agents/
git commit -m "Add team review and test-writing commands"

New team members get your entire command library when they clone the repo.

Note

Personal commands in ~/.claude/commands/ are not shared. Use this for personal productivity shortcuts that reflect your individual workflow preferences rather than team standards.

When This Breaks

Subagent does not trigger automatically: Improve the description field. Claude needs clear guidance about when to use each agent. Add phrases like “Use proactively after code changes” or “Triggers when testing is discussed.”

Command is too long and gets truncated: Claude Code loads the full command file into context. Very long commands (more than 500 lines) may crowd out other important context. Keep commands focused and delegate complex logic to subagents.

Agent inherits too many tools: By default, subagents inherit all tools from the parent session. If your agent should not modify files, explicitly restrict its tools to ["Read", "Grep", "Glob", "Bash"].

Team commands conflict with personal commands: Commands are invoked by bare name (/review), so a project command and a personal command with the same name collide. The higher-priority scope wins: a project command in .claude/commands/ overrides a personal one in ~/.claude/commands/. Note that skills and commands share the same namespace — if a skill and a command have the same name, the skill takes precedence, so avoid reusing a skill’s name for a command. The same project-over-user precedence applies to subagents defined in both .claude/agents/ and ~/.claude/agents/.

What is Next

• Hooks and Automation — Combine hooks with commands for fully automated workflows
• Memory System — Make your commands context-aware with project memory
• Prompt Engineering — Write better prompts inside your custom commands