Slash Command Creator

Quick Start

Step 1: Create the command

# .claude/commands/my-command.md

---

description: Brief description of what this command does.

---

## Steps

1. First action
2. Second action
3. Final action

Invoke with /my-command in Claude Code (shows "(project)" in /help).

Step 2: Validate (required)

Always run validation after creating or modifying a command:

uv run .claude/skills/meta-command-creator/scripts/validate-command.py .claude/commands/my-command.md

Fix any errors before committing.

Command Locations

Priority

When project and user commands share the same name, project wins and user command is silently ignored.

Tip: Slash command autocomplete works anywhere in your input, not just at the beginning.

YAML Frontmatter (Official Fields Only)

---
description: Create a conventional git commit with proper formatting.
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git status:*)
argument-hint: [commit message]
---

Invalid Fields (Do Not Use)

• •name - Inferred from filename
• •category - Not an official field
• •tags - Not an official field

Special Syntax

Bash Execution (! prefix)

Execute bash commands before the slash command runs. Output is included in context:

---
allowed-tools: Bash(git:*)
description: Create a git commit
---

## Context

- Current status: !`git status`
- Current diff: !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`

## Your task

Based on the above changes, create a single git commit.

Important: You MUST include allowed-tools with Bash when using ! prefix.

File References (@ prefix)

Include file contents in commands:

Review the implementation in @src/utils/helpers.js

Compare @src/old-version.js with @src/new-version.js

Extended Thinking

Include extended thinking keywords to trigger deeper reasoning:

Think carefully about the architecture implications before making changes.

Command Templates

See reference.md for complete templates:

• •Basic Command - Simple steps with reference section
• •Command with Arguments - Using $ARGUMENTS and $1, $2
• •Guardrailed Command - Safety constraints for state-changing operations
• •Multi-Phase Command - Complex workflows with distinct phases
• •Git Commit Command - With bash execution context

$ARGUMENTS Patterns

See reference.md for detailed patterns.

Organizing Commands

Use subdirectories for categorization:

.claude/commands/
├── git/commit.md      # Shows "(project:git)"
├── dev/feature.md     # Shows "(project:dev)"
└── docs/update.md     # Shows "(project:docs)"

SlashCommand Tool

Claude can execute custom slash commands programmatically using the SlashCommand tool.

Enabling Automatic Invocation

Reference commands by name in your prompts or CLAUDE.md:

Run /write-unit-test when you are about to start writing tests.

Requirements

• •Command MUST have description frontmatter (used for context)
• •Built-in commands (/compact, /init, etc.) are NOT supported
• •Only custom user-defined commands work

Disabling

# Disable all SlashCommand tool invocations
/permissions
# Add to deny rules: SlashCommand

# Disable specific command only

Add to command frontmatter:

disable-model-invocation: true

Permission Rules

• •Exact match: SlashCommand:/commit (only /commit, no args)
• •Prefix match: SlashCommand:/review-pr:* (allows any args)

Character Budget

Default: 15,000 characters for command descriptions. Set custom limit:

SLASH_COMMAND_TOOL_CHAR_BUDGET=20000

When exceeded, shows "M of N commands" warning in /context.

Skills vs Commands

When to Use Each

Use slash commands when:

• •You invoke the same prompt repeatedly
• •The prompt fits in a single file
• •You want explicit control over when it runs

Use Skills when:

• •Claude should discover the capability automatically
• •Multiple files or scripts are needed
• •Complex workflows with validation steps
• •Team needs standardized, detailed guidance

Common Mistakes

Validation

Run the validator to check command structure:

uv run .claude/skills/meta-command-creator/scripts/validate-command.py .claude/commands/my-command.md

Checklist

• • File location: .claude/commands/<name>.md
• • YAML frontmatter has description
• • Steps are numbered and actionable
• • $ARGUMENTS handled correctly (if used)
• • allowed-tools included if using ! bash execution
• • All code blocks have language specifiers
• • Guardrails section for state-changing commands
• • Output format specified

Built-in Commands Reference

Key built-in commands (cannot be overridden):

Full list: Run /help in Claude Code.

Delegation

• •After creating/modifying commands: Run uv run .claude/skills/meta-command-creator/scripts/validate-command.py <command.md>
• •Pattern discovery: For existing command patterns, use Explore agent

References

• •Official Docs: code.claude.com/docs/en/slash-commands.md
• •Existing commands: .claude/commands/openspec/
• •Skills comparison: code.claude.com/docs/en/skills.md