Create and manage custom slash commands in Claude Code. Use when: (1) User wants to create a new slash command, (2) User asks about /commands or custom commands, (3) User wants to automate frequent prompts, (4) User says 'create global command' or 'create local command', (5) User mentions 'command-creator'. Covers creation (global/local), command anatomy, frontmatter, arguments, bash, file references, namespacing, command vs skill comparison.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Create and manage custom slash commands in Claude Code. Use when: (1) User wants to create a new slash command, (2) User asks about /commands or custom commands, (3) User wants to automate frequent prompts, (4) User says 'create global command' or 'create local command', (5) User mentions 'command-creator'. Covers creation (global/local), command anatomy, frontmatter, arguments, bash, file references, namespacing, command vs skill comparison.
Custom Command Creator
Guide for creating effective custom slash commands in Claude Code.
What Are Custom Commands?
Custom slash commands are Markdown files that define reusable prompts. They're simpler than skills - single files for quick, frequently-used prompts.
Use commands when:
Same prompt is used repeatedly
Prompt fits in one file
Explicit control over when to run
Use skills instead when:
Claude should auto-detect the capability
Multiple files or scripts needed
Complex workflows with validation steps
Command Locations
Location
Path
Scope
Project
.claude/commands/<name>.md
This project only (shows as "project")
Personal
$HOME/.claude/commands/<name>.md
All your projects (shows as "user")
Priority: Enterprise > Personal > Project. When commands share a name across levels, personal ($HOME/.claude/commands/) overrides project (.claude/commands/) โ commands follow the same precedence as skills, since custom commands are a skill variant. See Skills for the full precedence rule.
Command Anatomy
Every command is a single Markdown file with optional frontmatter:
---
description: Brief description of what the command does
allowed-tools: Bash(git:*), Read
argument-hint: [filename] [options]
---
# Command Instructions
Your prompt content here with $ARGUMENTS placeholder.
Usage: /review-pr 456 high alice โ $1="456", $2="high", $3="alice"
Bash Execution
Run shell commands before the prompt is sent using !command`` syntax:
---
allowed-tools: Bash(git:*)
---
## Context
- Git status: !`git status`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -5`
## Task
Create a commit based on the above changes.
Important: Must include Bash in allowed-tools for this to work.
File References
Include file contents using @ prefix:
Review the implementation in @src/utils/helpers.js
Compare @src/old.js with @src/new.js
Extended Thinking
Set the effort frontmatter field (lowโmax) to control reasoning depth โ see references/frontmatter.md. The old "thinking keywords" prompting pattern ("think hard", "ultrathink") is superseded; current docs no longer document it.
Same-named commands in different subdirectories are distinguished by their namespace label.
Command Creation Workflow
When the user asks to create a command, follow this workflow.
Step 1: Determine Command Name and Location
If the user provides a name, use it. If they describe what they want, derive an appropriate kebab-case name.
Choose location based on context:
Global command ($HOME/.claude/commands/<name>.md): User says "global", or wants it available across all projects
Local/project command (.claude/commands/<name>.md): User says "local" or "project", or wants it scoped to current repo
If unclear: Ask the user which they prefer
For local commands, find the project root first:
git rev-parse --show-toplevel # Use repo root, or cwd if not a git repo
Ensure the target directory exists before writing.
Step 2: Gather Details
Ask the user if needed:
What should the command do?
Does it need arguments? If so, what arguments?
Should it use bash execution (!command``) for dynamic context?
Should it restrict allowed tools?
Step 3: Write the Command File
Create the command file with proper structure:
Required best practices:
Always include frontmatter with description field
Use argument-hint if the command accepts arguments (e.g., [filename], [pr-number])
Use $ARGUMENTS for all args or $1, $2 for positional args
If using bash execution, include allowed-tools in frontmatter
If manual-only invocation needed, add disable-model-invocation: true
Template:
---
description: Brief description of what the command does
argument-hint: [expected-args]
allowed-tools: Bash(git:*), Read
---
# Command Title
Clear instructions for what Claude should do.
## Context (if using bash execution)
- Dynamic info: !`git status --short`
## Task
What to accomplish with $ARGUMENTS.
Step 4: Format the command file
Format the created command file using the mdx-formatter to ensure consistent markdown formatting:
Show the user the full content of the created file
Tell them they can use it with /<command-name>
For global commands: Remind that a personal (global) command takes priority over a project-level command with the same name โ see the Priority note in "Command Locations" above
For local commands: Suggest committing to git so the team can share it
Key Rules for Creation
Command filename must be kebab-case (lowercase, hyphens): my-command.md
Always include description in frontmatter - commands without it are harder to discover
Keep the command focused on a single task
Use $ARGUMENTS / $1 / $2 for dynamic values, not hardcoded values
Don't overcomplicate - a command is a single Markdown file for a reusable prompt
Local commands are great for project-specific workflows (deploy, test patterns, review checklists)
File paths must use $HOME instead of ~: When command instructions reference home directory paths (e.g., log directories, config files), always write $HOME/cclogs/... or $HOME/.claude/..., never ~/cclogs/... or ~/.claude/.... The ~ character is only expanded by interactive shell login contexts. In Node.js fs operations, non-login shells, and many tool contexts, ~ is treated as a literal character, which creates an actual directory named ~/ inside the working directory instead of resolving to the user's home directory. This applies to paths in the command body text, bash execution snippets, and any instructions that an agent will follow. (Guard note: the ~/... forms above are the deliberate NEVER-case this rule warns against โ a future blanket ~โ$HOME find-and-replace must skip this line, or it destroys the contrast the rule depends on.)
Most commands should omit model and inherit the session's active model. Pin a model only when the command's task clearly calls for it, e.g. a cheap, high-volume task that doesn't need a large model:
---
description: Quick lint-style pass over the diff
model: claude-haiku-4-5-20251001
---
Perform a lint-style pass on $ARGUMENTS.
Preventing Auto-Invocation
To prevent Claude from invoking a command automatically via the Skill tool:
---
description: Deploy to production (manual only)
disable-model-invocation: true
---
Deploy the application to production.
Command-Scoped Hooks
Define hooks that run only during command execution:
