Claude Code Slash Commands Custom: A Practical Guide

Custom slash commands are one of the most underused levers in Claude Code. If you have already read the Claude Code Configuration & Workflows concept library, you know that the three-level configuration hierarchy gives you project-level, user-level, and global settings. Slash commands sit inside that hierarchy as reusable, invocable prompt templates, and getting them right separates teams that feel in control of their agentic workflows from teams that keep rewriting the same instructions in every session.

This guide covers how claude code slash commands custom work mechanically, how to organise a commands directory that scales, when to reach for a command versus a CLAUDE.md rule or an MCP tool, and how exam candidates should think about this domain for the CCAR-F.

How do custom slash commands work in Claude Code?

Custom slash commands are Markdown files stored in a .claude/commands/ directory. When you type / in the Claude Code interface, Claude reads that directory and surfaces each file as an invocable command. The file name becomes the command name; the file content becomes the prompt that Claude executes.

A minimal example:

.claude/
  commands/
    review.md
    test-plan.md
    security-audit.md

Invoking /review sends the contents of review.md to Claude as the user turn for that session. You can include $ARGUMENTS as a placeholder; anything you type after the command name is interpolated there.

# review.md
Review the following file for correctness, style, and test coverage.
Focus on edge cases and error handling. File: $ARGUMENTS

Calling /review src/payments/processor.py then expands to a fully formed prompt without you retyping the criteria each time.

Project-level commands live in .claude/commands/ and are version-controlled alongside the code. User-level commands live in ~/.claude/commands/ and apply across all projects. The three-level configuration hierarchy determines precedence when names collide: user-level commands override global defaults, and project-level commands override user-level ones.

What belongs in a custom slash command versus CLAUDE.md?

This is the question teams get wrong most often. The short answer: CLAUDE.md is for standing rules that apply to every interaction; slash commands are for repeatable tasks you invoke deliberately.

The practical rule: if you would want Claude to follow the instruction even when you have not mentioned it, put it in CLAUDE.md. If you only want it when you explicitly ask, make it a command. Keeping CLAUDE.md short and high-signal matters because every token in it consumes context on every turn. Bloated CLAUDE.md files are a common source of the attention dilution problem, where critical guardrails get buried under lower-priority prose.

How should you structure a commands directory for a real team?

A flat directory works for small projects. For teams with more than a handful of commands, grouping by workflow stage pays off quickly.

.claude/
  commands/
    plan/
      feature-plan.md
      refactor-plan.md
      migration-plan.md
    review/
      security-audit.md
      performance-review.md
      api-contract-check.md
    implement/
      tdd-loop.md
      one-file-fix.md
    release/
      changelog-draft.md
      migration-checklist.md

Claude Code surfaces nested commands with a / separator, so /plan/feature-plan is a valid invocation. This mirrors the way teams already think about their workflow stages and makes onboarding faster because the command list is self-documenting.

For version control implications, commit the .claude/commands/ directory. New engineers get the full command set on git clone. Treat command files like code: review them in PRs, keep them focused, and delete stale ones.

What makes a well-written custom command?

Four properties distinguish commands that get used from commands that get ignored.

1. A single, specific goal. A command that tries to review security, performance, and style simultaneously will produce diluted output. Split concerns into separate commands.

2. Explicit output format. Tell Claude exactly what to return. If you want a numbered list of findings with severity labels, say so. Vague commands produce vague output.

3. Scoped context instructions. Tell Claude which files or directories are relevant. A command that says "review the codebase" forces Claude to guess; a command that says "review $ARGUMENTS and its direct imports" is actionable.

4. Termination criteria. Agentic commands that loop (TDD loops, iterative refactors) need an explicit stopping condition. Without one, you risk the agentic loop anti-patterns that cause runaway sessions.

A well-formed TDD loop command looks like this:

# tdd-loop.md
You are implementing a failing test suite. Work through the following steps:

1. Run the test suite: `npm test -- $ARGUMENTS`
2. Identify the first failing test.
3. Write the minimum code to make it pass.
4. Re-run the suite.
5. Repeat until all tests in $ARGUMENTS pass or you have made 10 attempts.
6. If 10 attempts are exhausted without full passage, stop and summarise
   which tests remain failing and why.

Do not modify test files. Do not skip tests.

The explicit attempt limit in step 6 is the termination criterion. Without it, Claude may loop indefinitely on a genuinely broken test.

When should you use plan mode commands versus direct implementation commands?

The right choice depends on task size and reversibility. A useful heuristic:

The exam-relevant principle here is that model-driven vs pre-configured decision making applies directly to command design. High-stakes, hard-to-reverse operations (database migrations, multi-repo refactors) warrant a pre-configured plan-then-confirm pattern. Low-stakes, easily reversible operations (drafting a changelog, generating a test plan) can go straight to execution.

How do custom commands interact with MCP tools?

Custom slash commands and MCP tools solve different problems. A slash command is a prompt template: it shapes what Claude is asked to do. An MCP tool is a capability: it gives Claude access to an external system.

They compose naturally. A command can instruct Claude to use a specific MCP tool as part of its workflow:

# api-contract-check.md
Use the `openapi-validator` MCP tool to validate the contract at $ARGUMENTS.
Report any breaking changes against the previous version stored in
`docs/api/previous-contract.json`.
Format findings as a table: endpoint | change type | severity.

This pattern keeps the prompt logic in version control (the command file) while the capability lives in the MCP server. For teams building production workflows, this separation is cleaner than embedding tool-specific logic in CLAUDE.md. See the MCP scoping hierarchy concept for how tool availability interacts with project and user scope.

How do you handle context limits in long command-driven workflows?

Long agentic workflows driven by slash commands face the same stale context problem as any extended session. A few patterns help.

Checkpoint commands. Create a /checkpoint command that instructs Claude to write a structured summary of current state to a scratch file before the session compacts. When you resume, a /resume command reads that file and re-establishes context.

# checkpoint.md
Write a structured summary of the current task state to `.claude/scratch/checkpoint.md`.
Include: task goal, steps completed, steps remaining, open questions, and any
decisions made. Be concise; this file will be read at the start of the next session.

# resume.md
Read `.claude/scratch/checkpoint.md` and confirm your understanding of the
current task state before proceeding. Ask one clarifying question if anything
is ambiguous.

This is a practical application of summary injection for fresh sessions: rather than relying on Claude to compact gracefully, you control the summary explicitly.

Scope-limiting commands. For large codebases, commands that explicitly bound the working set prevent context bloat. Instead of "review the whole repo", write commands that take a path argument and stay within it.

What do CCAR-F candidates need to know about custom commands?

The CCAR-F exam (60 items, 120-minute limit, passing score 720 on a 1000-point scale) covers Claude Code Configuration & Workflows as Domain 3, weighted at 20%. Custom slash commands appear in scenario-based items that test practical judgment, not recall.

Expect scenarios that ask you to choose between:

• Putting a rule in CLAUDE.md versus making it a slash command
• Writing a command with an explicit termination condition versus leaving it open-ended
• Using a plan-mode command versus direct execution for a given task type
• Composing a command with an MCP tool versus handling everything in the prompt

The exam consistently rewards deterministic, proportionate solutions. A command with a hard attempt limit beats one that "tries until it succeeds". A command scoped to a specific directory beats one that operates on the whole repo. These are not stylistic preferences; they reflect the exam's bias toward solutions that are auditable and recoverable.

Our concept library maps 174 atomic concepts to the five CCAR-F domains and 30 task statements. The Claude Code configuration concepts are a direct study resource for Domain 3.

A reference command library to start from

Below is a minimal starter set covering the most common workflow stages. Copy these into .claude/commands/ and adapt them to your stack.

# plan/feature-plan.md
Produce a step-by-step implementation plan for the following feature: $ARGUMENTS

Structure the plan as:
1. Files to create (with purpose)
2. Files to modify (with specific changes)
3. Tests to write
4. Open questions requiring human input

Do not write any code. Output the plan only.

# review/security-audit.md
Perform a security-focused review of $ARGUMENTS.

Check for:
- Injection vulnerabilities (SQL, command, path traversal)
- Insecure deserialization
- Missing input validation
- Hardcoded credentials or secrets
- Overly permissive error messages

For each finding: file | line | severity (critical/high/medium/low) | description | suggested fix.
Stop after 20 findings and note that the list may be incomplete.

# release/changelog-draft.md
Draft a changelog entry for the changes in $ARGUMENTS (a git range or branch name).

Format: Keep a Changelog (https://keepachangelog.com).
Sections: Added, Changed, Deprecated, Removed, Fixed, Security.
Omit empty sections. Write for a technical audience. Do not invent changes
not present in the diff.

These three commands cover planning, auditing, and release documentation without overlapping with standing CLAUDE.md rules. They are narrow, have explicit output formats, and include stopping conditions or scope limits.

Summary

Custom slash commands in Claude Code are prompt templates stored as Markdown files, versioned with your project, and invoked deliberately. They complement CLAUDE.md (which holds standing rules) and MCP tools (which provide capabilities). Well-written commands have a single goal, an explicit output format, scoped context, and a termination criterion. For CCAR-F candidates, Domain 3 scenarios reward the same properties: deterministic, proportionate, auditable solutions over open-ended ones.