Custom Slash Commands Skill

Custom Slash Commands

Create reusable prompts and workflows as slash commands that Claude Code can execute on demand.

Quick Reference

| Element | Requirement | |---------|-------------| | Location (project) | .claude/commands/name.md | | Location (user) | ~/.claude/commands/name.md | | Filename | Lowercase with hyphens, .md extension | | Invocation | /command-name [arguments] | | Precedence | Project commands override user commands |

Frontmatter Options

| Field | Purpose | Default | |-------|---------|---------| | allowed-tools | Tools the command can use | Inherits from conversation | | argument-hint | Hint shown in autocomplete | None | | description | Brief description | First line of prompt | | model | Force specific model | Inherits from conversation | | hooks | Lifecycle-scoped hooks (PreToolUse, PostToolUse, Stop) | None | | disable-model-invocation | Prevent Skill tool access | false |

Command vs Skill Decision Guide

| Choose Command When | Choose Skill When | |---------------------|-------------------| | Simple prompt fits one file | Complex workflow needs multiple files | | You want explicit /invoke | Claude should auto-discover | | Quick template or reminder | Scripts and utilities needed | | Single-file instructions | Team needs detailed guidance |

Rule of thumb: If it fits in one file and you want explicit control, use a command. If it needs structure or auto-discovery, use a Skill.

File Structure

Project Commands (Team-Shared)

.claude/
  commands/
    commit.md           # /commit
    review.md           # /review
    frontend/
      component.md      # /component (project:frontend)
      test.md           # /test (project:frontend)
    backend/
      endpoint.md       # /endpoint (project:backend)
      test.md           # /test (project:backend)

User Commands (Personal)

~/.claude/
  commands/
    standup.md          # /standup (user)
    journal.md          # /journal (user)
    tools/
      format.md         # /format (user:tools)

Core Patterns

Pattern 1: Simple Prompt Command

# .claude/commands/review.md
Review this code for:
- Security vulnerabilities
- Performance issues
- Code style violations

Usage: /review

Pattern 2: Command with Arguments

# .claude/commands/fix-issue.md
---
argument-hint: <issue-number>
description: Fix a GitHub issue by number
---

Fix issue #$ARGUMENTS following our coding standards.
Check the issue description and implement the fix.

Usage: /fix-issue 123

Pattern 3: Positional Arguments

# .claude/commands/review-pr.md
---
argument-hint: [pr-number] [priority] [assignee]
description: Review pull request with priority
---

Review PR #$1 with priority $2 and assign to $3.
Focus on security, performance, and code style.

Usage: /review-pr 456 high alice

Pattern 4: Bash Execution

# .claude/commands/commit.md
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit with context
---

## Context

- Current git status: !`git status`
- Staged changes: !`git diff --cached`
- Recent commits: !`git log --oneline -5`

## Task

Create a commit message based on the staged changes.
Follow conventional commit format.

Usage: /commit

Pattern 5: File References

# .claude/commands/compare.md
---
argument-hint: <file1> <file2>
description: Compare two files
---

Compare the following files and highlight differences:

File 1: @$1
File 2: @$2

Focus on:
- API changes
- Breaking changes
- Logic differences

Usage: /compare src/old.ts src/new.ts

Pattern 6: Tool Restrictions

# .claude/commands/analyze.md
---
allowed-tools: Read, Glob, Grep
description: Analyze code without making changes
---

Analyze the codebase for patterns and issues.
Do NOT modify any files - read-only analysis.

Pattern 7: Model Override

# .claude/commands/quick-answer.md
---
model: claude-3-5-haiku-20241022
description: Quick answer using faster model
---

Quickly answer: $ARGUMENTS

Be concise. No code changes.

Pattern 8: Command with Hooks

# .claude/commands/deploy.md
---
description: Deploy with pre-flight validation
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/preflight-check.sh"
          once: true
  Stop:
    - hooks:
        - type: command
          command: "./scripts/notify-deploy.sh"
---

Deploy the current branch to the staging environment.
Ensure all tests pass before deploying.

Hooks in commands are lifecycle-scoped and only active during command execution.

Namespacing

Subdirectories group related commands and appear in descriptions:

| File Path | Command | Description Shows | |-----------|---------|-------------------| | .claude/commands/deploy.md | /deploy | (project) | | .claude/commands/frontend/deploy.md | /deploy | (project:frontend) | | ~/.claude/commands/deploy.md | /deploy | (user) | | ~/.claude/commands/tools/deploy.md | /deploy | (user:tools) |

Conflict Resolution:

Project commands override user commands with same name
Same-name commands in different subdirectories coexist (distinguished by description)

Variables Reference

| Variable | Description | Example | |----------|-------------|---------| | $ARGUMENTS | All arguments as single string | "123 high-priority" | | $1, $2, ... | Individual positional arguments | $1="123", $2="high-priority" | | !command | Bash output (requires allowed-tools) | `!`git status | | @path | File contents reference | @src/main.ts |

Workflow: Creating a Command

Prerequisites

[ ] Identify the repeated prompt or workflow
[ ] Decide: project or user scope
[ ] Plan arguments if dynamic

Steps

Create command file
- [ ] Choose location (.claude/commands/ or ~/.claude/commands/)
- [ ] Name file (lowercase, hyphens, .md)
- [ ] Add frontmatter if needed
Write command content
- [ ] Clear instructions for Claude
- [ ] Add argument placeholders if needed
- [ ] Include bash execution if needed
Test
- [ ] Run /help to verify command appears
- [ ] Execute command with test arguments
- [ ] Verify output is as expected

Validation Checklist

[ ] Filename is lowercase with hyphens
[ ] Command appears in /help
[ ] Arguments work correctly
[ ] Bash execution has allowed-tools
[ ] Description is helpful

Skill Tool Integration

Claude can invoke custom commands and skills programmatically via the Skill tool (replaces the deprecated SlashCommand tool).

Requirements for Skill tool invocation:

Must have description in frontmatter
Cannot be a built-in command
Not blocked by disable-model-invocation: true

Character budget: Default 15,000 characters. Override with SLASH_COMMAND_TOOL_CHAR_BUDGET env var.

To encourage usage:

# In CLAUDE.md
Run /write-test when starting to write tests.

To disable:

---
disable-model-invocation: true
---

Permission Rules

Control which commands Claude can invoke via the Skill tool:

| Pattern | Meaning | |---------|---------| | Skill(/commit) | Exact match (no arguments) | | Skill(/review-pr:*) | Prefix match (any arguments) | | Skill(/deploy:*) | Prefix match |

// settings.json
{
  "permissions": {
    "allow": ["Skill(/commit)", "Skill(/review-pr:*)"],
    "deny": ["Skill(/deploy:*)"]
  }
}

Migration: If you have existing SlashCommand permission rules, update them to use Skill.

Security Considerations

[ ] Be careful with allowed-tools: Bash(*) - prefer specific patterns
[ ] Don't expose secrets in command files
[ ] Review project commands before committing
[ ] Consider disable-model-invocation for sensitive commands

Reference Files

| File | Contents | |------|----------| | EXAMPLES.md | 8+ copy-paste ready examples | | TROUBLESHOOTING.md | Common issues and solutions |

Agent Skills: Custom Slash Commands

Skill Files