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	/project:review
~/.claude/commands/standup.md	Personal, all projects	/user:standup

The file name becomes the command name. Subdirectories create namespaced commands: .claude/commands/test/integration.md becomes /project:test:integration.

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 /project:review and get a consistent, thorough code review.

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: /project: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:

---
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

Field	Required	Description
description	Yes	When the agent should be triggered (Claude reads this to decide)
prompt	No	System prompt (alternatively, write it in the body of the file)
tools	No	Tool restrictions. Defaults to inheriting all tools
model	No	sonnet, opus, haiku, or inherit
maxTurns	No	Maximum agentic turns before the agent stops
disallowedTools	No	Tools to explicitly block

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.”

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

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: Project commands use /project: prefix, personal commands use /user:. If you have both, they are clearly separated. However, if an agent definition exists in both .claude/agents/ and ~/.claude/agents/ with the same name, the project version takes precedence.

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