--- name: create-slash-commands description: Expert guidance for creating Claude Code slash commands. Use when working with slash commands, creating custom commands, understanding command structure, or learning YAML configuration. --- Create effective slash commands for Claude Code that enable users to trigger reusable prompts with `/command-name` syntax. Slash commands expand as prompts in the current conversation, allowing teams to standardize workflows and operations. Commands can be **global** (available everywhere in `~/.claude/commands/`) or **project-specific** (shared with team in `.claude/commands/`). This skill teaches you to structure commands with proper formatting (XML or Markdown), YAML frontmatter, dynamic context loading, and intelligent argument handling. **CRITICAL WORKFLOW**: This skill enforces a mandatory research phase where you MUST: 1. Read all reference documentation 2. Examine existing slash commands for patterns 3. Understand syntax and best practices 4. Only then create the command This prevents poorly-structured commands and ensures consistency with established patterns. 1. Create `.claude/commands/` directory (project) or use `~/.claude/commands/` (personal) 2. Create `command-name.md` file 3. Add YAML frontmatter (at minimum: `description`) 4. Write command prompt 5. Test with `/command-name [args]` **File**: `.claude/commands/optimize.md` ```markdown --- description: Analyze this code for performance issues and suggest optimizations --- Analyze the performance of this code and suggest three specific optimizations: ``` **Usage**: `/optimize` Claude receives the expanded prompt and analyzes the code in context. Slash commands can use either XML tags OR Markdown headings in the body (after YAML frontmatter). **Format choice depends on**: - User preference (ask if not specified) - Command complexity (XML better for complex, Markdown fine for simple) - Existing project patterns (match what's already in use) See [references/prompt-examples.md](references/prompt-examples.md) for real examples of both formats in production. **``** - What the command does and why it matters ```markdown What needs to happen and why this matters. Context about who uses this and what it accomplishes. ``` **`` or ``** - How to execute the command ```markdown Sequential steps to accomplish the objective: 1. First step 2. Second step 3. Final step ``` **``** - How to know the command succeeded ```markdown Clear, measurable criteria for successful completion. ``` **``** - When loading dynamic state or files ```markdown Current state: ! `git status` Relevant files: @ package.json ``` (Note: Remove the space after @ in actual usage) **``** - When producing artifacts that need checking ```markdown Before completing, verify: - Specific test or check to perform - How to confirm it works ``` **``** - When running tests is part of the workflow ```markdown Run tests: ! `npm test` Check linting: ! `bun run lint` ``` **``** - When creating/modifying specific files ```markdown Files created/modified: - `./path/to/file.ext` - Description ``` ```markdown --- name: example-command description: Does something useful argument-hint: [input] --- Process #$ARGUMENTS to accomplish [goal]. This helps [who] achieve [outcome]. Current state: ! `relevant command` Files: @ relevant/files 1. Parse #$ARGUMENTS 2. Execute operation 3. Verify results - Operation completed without errors - Output matches expected format ``` **Simple commands** (single operation, no artifacts): - Required: ``, ``, `` - Example: `/check-todos`, `/first-principles` **Complex commands** (multi-step, produces artifacts): - Required: ``, ``, `` - Add: `` (if loading state), `` (if creating files), `` (what gets created) - Example: `/commit`, `/create-prompt`, `/run-prompt` **Commands with dynamic arguments**: - Use `#$ARGUMENTS` in `` or `` tags - Include `argument-hint` in frontmatter - Make it clear what the arguments are for **Commands that produce files**: - Always include `` tag specifying what gets created - Always include `` tag with checks to perform **Commands that run tests/builds**: - Include `` tag with specific commands - Include pass/fail criteria in `` The skill should intelligently determine whether a slash command needs arguments. **User provides specific input:** - `/fix-issue [issue-number]` - Needs issue number - `/review-pr [pr-number]` - Needs PR number - `/optimize [file-path]` - Needs file to optimize - `/commit [type]` - Needs commit type (optional) **Pattern:** Task operates on user-specified data Include `argument-hint: [description]` in frontmatter and reference `#$ARGUMENTS` in the body. **Self-contained procedures:** - `/check-todos` - Operates on known file (TO-DOS.md) - `/first-principles` - Operates on current conversation - `/whats-next` - Analyzes current context **Pattern:** Task operates on implicit context (current conversation, known files, project state) Omit `argument-hint` and don't reference `#$ARGUMENTS`. **In `` tag:** ```markdown Fix issue #$ARGUMENTS following project conventions. This ensures bugs are resolved systematically with proper testing. ``` **In `` tag:** ```markdown 1. Understand issue #$ARGUMENTS from issue tracker 2. Locate relevant code 3. Implement fix 4. Add tests ``` **In `` tag:** ```markdown Issue details: @ issues/#$ARGUMENTS.md Related files: ! `grep -r "TODO.*#$ARGUMENTS" src/` ``` (Note: Remove the space after the exclamation mark in actual usage) For structured input, use `$1`, `$2`, `$3`: ```markdown --- argument-hint: --- Review PR #$1 with priority $2 and assign to $3. ``` **Usage:** `/review-pr 456 high alice` **Project commands**: `.claude/commands/` (in project root) - Shared with team via version control - Project-specific workflows - Shows `(project)` in `/help` list - Committed to git for team use **Global commands**: `~/.claude/commands/` (user home directory) - Available across all your projects - Personal productivity commands - Shows `(user)` in `/help` list - Not shared with team **File naming**: `command-name.md` → invoked as `/command-name` **Choosing between global and project**: - Use **global** for: Personal workflows, general utilities, commands you use everywhere - Use **project** for: Team workflows, project-specific operations, shared conventions **Required** - Describes what the command does ```yaml description: Analyze this code for performance issues and suggest optimizations ``` Shown in the `/help` command list. **Optional** - Restricts which tools Claude can use ```yaml allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) ``` **Formats**: - Array: `allowed-tools: [Read, Edit, Write]` - Single tool: `allowed-tools: SequentialThinking` - Bash restrictions: `allowed-tools: Bash(git add:*)` If omitted: All tools available **Command file**: `.claude/commands/fix-issue.md` ```markdown --- description: Fix issue following coding standards --- Fix issue #$ARGUMENTS following our coding standards ``` **Usage**: `/fix-issue 123 high-priority` **Claude receives**: "Fix issue #123 high-priority following our coding standards" **Command file**: `.claude/commands/review-pr.md` ```markdown --- description: Review PR with priority and assignee --- Review PR #$1 with priority $2 and assign to $3 ``` **Usage**: `/review-pr 456 high alice` **Claude receives**: "Review PR #456 with priority high and assign to alice" See [references/arguments.md](references/arguments.md) for advanced patterns. Execute bash commands before the prompt using the exclamation mark prefix directly before backticks (no space between). **Note:** Examples below show a space after the exclamation mark to prevent execution during skill loading. In actual slash commands, remove the space. Example: ```markdown --- description: Create a git commit allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) --- ## Context - Current git status: ! `git status` - Current git 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. ``` The bash commands execute and their output is included in the expanded prompt. Use `@` prefix to reference specific files: ```markdown --- description: Review implementation --- Review the implementation in @ src/utils/helpers.js ``` (Note: Remove the space after @ in actual usage) Claude can access the referenced file's contents. **1. Always use XML structure** ```yaml # All slash commands should have XML-structured bodies ``` After frontmatter, use XML tags: - `` - What and why (always) - `` - How to do it (always) - `` - Definition of done (always) - Additional tags as needed (see xml_structure section) **2. Clear descriptions** ```yaml # Good description: Analyze this code for performance issues and suggest optimizations # Bad description: Optimize stuff ``` **3. Use dynamic context for state-dependent tasks** ```markdown Current git status: ! `git status` Files changed: ! `git diff --name-only` ``` **4. Restrict tools when appropriate** ```yaml # For git commands - prevent running arbitrary bash allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) # For analysis - thinking only allowed-tools: SequentialThinking ``` **5. Use #$ARGUMENTS for flexibility** ```markdown Find and fix issue #$ARGUMENTS ``` **6. Reference relevant files** ```markdown Review @ package.json for dependencies Analyze @ src/database/\* for schema ``` (Note: Remove the space after @ in actual usage) **Simple analysis command**: ```markdown --- description: Review this code for security vulnerabilities --- Review code for security vulnerabilities and suggest fixes. 1. Scan code for common vulnerabilities (XSS, SQL injection, etc.) 2. Identify specific issues with line numbers 3. Suggest remediation for each issue - All major vulnerability types checked - Specific issues identified with locations - Actionable fixes provided ``` **Git workflow with context**: ```markdown --- description: Create a git commit allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) --- Create a git commit for current changes following repository conventions. - Current status: ! `git status` - Changes: ! `git diff HEAD` - Recent commits: ! `git log --oneline -5` 1. Review staged and unstaged changes 2. Stage relevant files 3. Write commit message following recent commit style 4. Create commit - All relevant changes staged - Commit message follows repository conventions - Commit created successfully ``` **Parameterized command**: ```markdown --- description: Fix issue following coding standards argument-hint: [issue-number] --- Fix issue #$ARGUMENTS following project coding standards. This ensures bugs are resolved systematically with proper testing. 1. Understand the issue described in ticket #$ARGUMENTS 2. Locate the relevant code in codebase 3. Implement a solution that addresses root cause 4. Add appropriate tests 5. Verify fix resolves the issue - Issue fully understood and addressed - Solution follows coding standards - Tests added and passing - No regressions introduced ``` **File-specific command**: ```markdown --- description: Optimize code performance argument-hint: [file-path] --- Analyze performance of @ #$ARGUMENTS and suggest specific optimizations. This helps improve application performance through targeted improvements. 1. Review code in @ #$ARGUMENTS for performance issues 2. Identify bottlenecks and inefficiencies 3. Suggest three specific optimizations with rationale 4. Estimate performance impact of each - Performance issues clearly identified - Three concrete optimizations suggested - Implementation guidance provided - Performance impact estimated ``` **Usage**: `/optimize src/utils/helpers.js` See [references/patterns.md](references/patterns.md) for more examples. **Slash command specific references:** - [arguments.md](references/arguments.md) - #$ARGUMENTS, positional args, parsing strategies - [patterns.md](references/patterns.md) - Git workflows, code analysis, file operations, **subagent patterns** - [tool-restrictions.md](references/tool-restrictions.md) - Bash patterns, security best practices - [prompt-examples.md](references/prompt-examples.md) - Real-world command examples by pattern **Prompt engineering references from create-prompt skill:** - [clarity-principles.md](../../create-prompt/references/clarity-principles.md) - Being clear and direct - [xml-structure.md](../../create-prompt/references/xml-structure.md) - XML tag usage - [few-shot-patterns.md](../../create-prompt/references/few-shot-patterns.md) - Example-based prompting - [reasoning-techniques.md](../../create-prompt/references/reasoning-techniques.md) - Chain of thought, step-by-step - [system-prompt-patterns.md](../../create-prompt/references/system-prompt-patterns.md) - System prompt templates - [anthropic-best-practices.md](../../create-prompt/references/anthropic-best-practices.md) - Claude-specific techniques - [context-management.md](../../create-prompt/references/context-management.md) - Context windows, long-horizon reasoning - [anti-patterns.md](../../create-prompt/references/anti-patterns.md) - Common mistakes to avoid **CRITICAL: Complete this research phase BEFORE proceeding to any other steps.** You MUST read and understand these materials before creating any slash command: **1. Read ALL reference files in order:** Use the Read tool to read these files: - `references/prompt-examples.md` - Real-world patterns and examples - `references/patterns.md` - Verified command patterns - `references/arguments.md` - Argument handling examples - `references/tool-restrictions.md` - Tool restriction patterns **2. Examine existing slash commands:** Use Bash to find and Read existing commands: ```bash find ~/.claude/commands -name "*.md" -type f | head -10 ``` Then Read 2-3 relevant existing commands to understand: - How they structure their YAML frontmatter - What format they use (XML vs Markdown) - How they handle arguments (#$ARGUMENTS vs positional) - What tool restrictions they apply - How they structure their workflow sections **3. Identify the right pattern:** Based on the user's request, match it to one of these patterns from prompt-examples.md: - **Pattern 1**: Numbered workflow (git ops, CI, EPCT) - for multi-step processes - **Pattern 2**: Reference/docs (CLI wrappers) - for command documentation - **Pattern 3**: Section-based analysis (research, investigation) - for analysis tasks - **Subagent patterns**: For commands that launch Task tool agents - **Hybrid patterns**: Combining multiple approaches **4. Check for similar existing commands:** Before creating a new command, check if a similar command already exists: ```bash grep -l "description.*" ~/.claude/commands/*.md ``` If a similar command exists, read it to: - Avoid duplication - Learn from its structure - Understand how to differentiate the new command **VERIFICATION CHECKLIST:** Before proceeding to step 1, confirm you have: - ✅ Read all 4 reference files - ✅ Examined at least 2 existing slash commands - ✅ Identified which pattern to use - ✅ Checked for similar existing commands - ✅ Understand the correct syntax (#$ARGUMENTS, tool restrictions, etc.) **DO NOT PROCEED** until all items are checked. This research phase is non-negotiable and prevents creating poorly structured commands. **Analyze the user's request** to understand what they want: - What is the command's purpose? - Does it need user input (#$ARGUMENTS)? - Does it produce files or artifacts? - Does it require verification or testing? - Is it simple (single-step) or complex (multi-step)? - What pattern does it match? (see [references/prompt-examples.md](references/prompt-examples.md)) **Intelligence rule**: Only proceed to questions if critical information is missing. If the request is clear, skip directly to format choice. **INTELLIGENCE RULE**: Only ask questions if critical information is truly missing. If the request is clear, skip directly to scope and format questions. Most requests like "create a command to X" contain enough information to proceed. **Ask clarifying questions** ONLY if essential information is missing: Use AskUserQuestion to gather ONLY what's needed: 1. **Command purpose** (if completely unclear): - header: "Purpose" - question: "What should this command do?" - Let user provide via "Other" option 2. **Arguments** (if truly ambiguous - rare): - header: "Arguments" - question: "Does this command need user input?" - options: "Yes - takes arguments", "No - uses context only" **SKIP questions for**: - Clear purposes: "create a command to commit and push" → obvious purpose - Obvious complexity: "simple command to..." vs "command that monitors and fixes..." - Clear arguments: "for [file-path]" → needs args, "to analyze current code" → no args - Standard tools: Git commands → Bash(git :\*), file operations → Read/Edit/Write **Default assumptions** (use unless contradicted): - Git operations → `Bash(git :*)` - Analysis tasks → No tool restrictions - File modifications → `Read, Edit, Write` - Complex multi-step → Add verification and testing sections **ALWAYS ask about scope** unless explicitly specified in the request: Use AskUserQuestion: - header: "Scope" - question: "Where should this command be available?" - options: - "Global (all projects)" - description: "Saved to ~/.claude/commands/ - available everywhere" - "Project only" - description: "Saved to .claude/commands/ - shared with team via git" **Detection rules**: - If request says "global command" → Skip, use global scope - If request says "project command" or "team command" → Skip, use project scope - Otherwise → ALWAYS ask **Important**: This determines the save location: - Global: `~/.claude/commands/command-name.md` - Project: `.claude/commands/command-name.md` (in current working directory) **Determine format based on existing patterns:** Before asking the user, check what format existing commands in the target directory use: - If creating global command: Check `~/.claude/commands/*.md` - If creating project command: Check `.claude/commands/*.md` Read 2-3 existing commands to see if they use XML or Markdown format. **Then ask for format preference**: Use AskUserQuestion: - header: "Format" - question: "What format do you prefer for this slash command?" - options: - First option based on what you found: If most commands use Markdown, make "Markdown (matches existing)" the first option - Second option: The alternative format - Include note about what existing commands use **Recommendation**: - Match existing commands format for consistency - XML for complex multi-step commands - Markdown for simple straightforward commands See [references/prompt-examples.md](references/prompt-examples.md) for format examples. **Create YAML frontmatter** based on gathered information: ```yaml --- name: command-name description: Clear description of what it does argument-hint: [input] # Only if arguments needed allowed-tools: [...] # Only if tool restrictions needed --- ``` **Frontmatter rules**: - `description`: Always required, clear and concise - `argument-hint`: Include if command takes user input - `allowed-tools`: Include if restricting tools for security - `model`: Include only if need specific model (haiku for speed, opus for complexity) **Create command body** in chosen format (XML or Markdown): **Always include:** - `` - What and why - `` - How to do it (numbered steps) - `` - Definition of done **Include when relevant:** - `` - Dynamic state (! `commands`) or file references (@ files) - `` - Checks to perform if creating artifacts - `` - Test commands if tests are part of workflow - `` - Files created/modified **Reference**: Apply prompt engineering best practices from create-prompt skill: - [clarity-principles.md](../../create-prompt/references/clarity-principles.md) - Being clear and direct - [xml-structure.md](../../create-prompt/references/xml-structure.md) - XML tag usage - [anthropic-best-practices.md](../../create-prompt/references/anthropic-best-practices.md) - Claude-specific techniques **Always include:** - `## Objective` - What and why - `## Process` or `## Workflow` - How to do it (numbered list) - `## Success Criteria` - Definition of done **Include when relevant:** - `## Context` - Dynamic state or file references - `## Verification` - Checks to perform if creating artifacts - `## Testing` - Test commands if tests are part of workflow - `## Output` - Files created/modified **Integrate #$ARGUMENTS** if command takes input: - If user input needed: Add `argument-hint` and use `#$ARGUMENTS` in body - If self-contained: Omit `argument-hint` and `#$ARGUMENTS` - For structured input: Use positional args `$1`, `$2`, `$3` **Examples**: See [references/arguments.md](references/arguments.md) **Apply appropriate complexity level**: - **Simple commands**: Keep concise (objective + process + success criteria) - **Complex commands**: Add context, verification, testing as needed - **Don't over-engineer**: Simple tasks stay simple - **Don't under-specify**: Complex tasks get full structure **Pattern matching**: Choose pattern from [references/prompt-examples.md](references/prompt-examples.md): - Pattern 1: Numbered workflow (git ops, CI, EPCT) - Pattern 2: Reference/docs (CLI wrappers) - Pattern 3: Section-based analysis (research, investigation) **Save the command file** based on chosen scope: **Global scope** (user selected "Global (all projects)"): - Path: `~/.claude/commands/command-name.md` - Available across all projects - Personal commands, not shared with team **Project scope** (user selected "Project only"): - Path: `.claude/commands/command-name.md` (in current working directory) - Shared with team via version control - Project-specific commands **Verification**: - File created at correct location based on scope - YAML frontmatter valid - Body follows chosen format consistently - All required sections present **After saving**: - Confirm location to user - Remind them to commit if project scope - Provide usage example: `/command-name [args]` A well-structured slash command meets these criteria: **YAML Frontmatter**: - `description` field is clear and concise - `argument-hint` present if command accepts arguments - `allowed-tools` specified if tool restrictions needed **XML Structure**: - All three required tags present: ``, ``, `` - Conditional tags used appropriately based on complexity - No raw markdown headings in body - All XML tags properly closed **Arguments Handling**: - `#$ARGUMENTS` used when command operates on user-specified data - Positional arguments (`$1`, `$2`, etc.) used when structured input needed - No `#$ARGUMENTS` reference for self-contained commands **Functionality**: - Command expands correctly when invoked - Dynamic context loads properly (bash commands, file references) - Tool restrictions prevent unauthorized operations - Command accomplishes intended purpose reliably **Quality**: - Clear, actionable instructions in `` tag or `## Workflow` section - Measurable completion criteria in `` tag or `## Success Criteria` section - Appropriate level of detail (not over-engineered for simple tasks) - Examples provided when beneficial ## Critical Anti-Patterns to Avoid These are common mistakes that result from skipping the mandatory research phase: ### ❌ MISTAKE 1: Skipping the Research Phase **Wrong**: ``` User asks to create /quick-search command → Immediately ask scope/format questions → Create command without reading references or existing commands → Use wrong syntax, wrong format, miss best practices ``` **Correct**: ``` User asks to create /quick-search command → Read all 4 reference files first → Find and examine existing commands (especially /search if it exists) → Understand patterns and syntax → Then ask questions and create command ``` ### ❌ MISTAKE 2: Using Wrong Argument Syntax **Wrong**: ```markdown --- description: Quick search --- Answer the question: #args ``` **Correct**: ```markdown --- description: Quick search argument-hint: --- User: #$ARGUMENTS ``` The correct syntax is `#$ARGUMENTS` (not `#args`). This is documented in references/arguments.md. ### ❌ MISTAKE 3: Not Checking for Similar Commands **Wrong**: - Create `/quick-search` without checking if `/search` already exists - Result: Duplicate functionality, confusion **Correct**: - Check existing commands first: `find ~/.claude/commands -name "*.md"` - If similar command exists, read it to understand how to differentiate - Consider if the new command is really needed ### ❌ MISTAKE 4: Wrong Format Choice **Wrong**: - User asks for command - Randomly choose XML or Markdown without checking existing commands - Result: Inconsistent codebase **Correct**: - Check what format existing commands use - Match that format for consistency - Only deviate if user explicitly requests different format ### ❌ MISTAKE 5: Missing Tool Restrictions **Wrong**: ```yaml --- description: Quick search with Haiku model model: haiku --- ``` **Correct**: ```yaml --- description: Quick search with Haiku model model: haiku allowed-tools: [Grep, Glob, Read] --- ``` For speed-optimized commands, restrict tools to prevent using slow agents like Task. ### ❌ MISTAKE 6: Not Matching Existing Patterns **Wrong**: - Create unique structure that doesn't match any existing pattern - Result: Hard to maintain, unfamiliar to users **Correct**: - Read prompt-examples.md to see verified patterns - Match your command to Pattern 1, 2, 3, or hybrid - Follow the established structure ### ❌ MISTAKE 7: Not Including "User: #$ARGUMENTS" at the End **Wrong**: ```markdown --- description: Search command argument-hint: --- You are a search specialist. ## Workflow 1. Search for the answer 2. Provide results ``` **Correct**: ```markdown --- description: Search command argument-hint: --- You are a search specialist. ## Workflow 1. Search for the answer 2. Provide results --- User: #$ARGUMENTS ``` Many commands end with `User: #$ARGUMENTS` to properly pass the user's input to the command. ### ❌ MISTAKE 8: Over-Engineering Simple Commands **Wrong**: ```markdown Create comprehensive search system Load all git state Run extensive checks Test all edge cases ``` For a simple search command, this is too much. **Correct**: ```markdown You are a rapid search specialist. ## Workflow 1. Search 2. Answer User: #$ARGUMENTS ``` Match complexity to the task. ## How to Avoid These Mistakes **Follow the Step 0 checklist religiously**: 1. ✅ Read all 4 reference files 2. ✅ Examine 2-3 existing commands 3. ✅ Identify the pattern to use 4. ✅ Check for similar commands 5. ✅ Understand correct syntax **If you skip Step 0, you WILL make these mistakes.**