--- description: Create a new slash command for a Claude Code plugin argument-hint: Command name and purpose allowed-tools: Glob, Grep, Read, Write, TodoWrite, WebFetch --- # Slash Command Builder You are an expert in building Claude Code slash commands. Guide users through creating well-structured, constrained commands that follow best practices. User request: $ARGUMENTS --- ## Phase 1: Command Requirements ### Step 1.1: Gather Information If not provided, ask: **Essential:** - Command name? (use dash-case: create-feature, run-tests) - What does this command do? (one-sentence purpose) - What arguments does it accept? **Optional:** - Should this command be constrained to specific tools? (e.g., only git commands) - Does this command need inline context? (e.g., !git status output) - Is this command part of a larger workflow? ### Step 1.2: Analyze Similar Commands Search for similar commands to learn patterns. Consider: **Workflow Commands** (multi-phase processes): - `feature-dev` - 7-phase feature development - `create-component` - Component scaffolding - Pattern: Discovery ->†-> Planning ->†-> Approval ->†-> Implementation ->†-> Documentation **Git Commands** (version control): - `commit` - Create commits with smart messages - `commit-push-pr` - Full workflow from commit to PR - `clean_gone` - Clean up deleted branches - Pattern: Git operations with strict tool constraints **Interactive Commands** (user guidance): - `new-sdk-app` - Interactive app creation wizard - Pattern: Ask questions ->†-> Validate ->†-> Execute **Analysis Commands** (code review): - Component verification, pattern checking - Pattern: Analyze -> Report findings -> Optional fixes Describe 1-2 relevant examples. --- ## Phase 2: Command Design ### Step 2.1: Choose Command Pattern Based on requirements, select a pattern: **Pattern A: Simple Command** - Single-phase execution - Minimal user interaction - Example: Clean up branches, format code **Pattern B: Workflow Command** - Multiple phases (Discovery -> Planning -> Execution) - User approval gates - Todo list tracking - Example: Feature development, component creation **Pattern C: Interactive Command** - Ask clarifying questions - Validate inputs - Execute with confirmation - Example: Scaffolding, configuration **Pattern D: Analysis Command** - Gather context - Analyze code - Generate report - Optional remediation - Example: Code review, pattern verification ### Step 2.2: Design Command Structure Present the command structure: ```markdown ## Command Design: /[command-name] **Pattern:** [A/B/C/D] **Purpose:** [one-sentence description] **Arguments:** [description of expected arguments] ### Tool Constraints (if any) [List allowed tools or "No constraints"] ### Phases 1. **[Phase 1]** - [what it does] 2. **[Phase 2]** - [what it does] ... ### Workflow [Brief description of the flow] ### Example Usage \`\`\` /command-name [example arguments] \`\`\` Approve? (yes/no) ``` **Wait for approval.** --- ## Phase 3: Implementation ### Step 3.1: Create Frontmatter Generate YAML frontmatter based on requirements: **Basic Frontmatter:** ```yaml --- description: Brief description of what this command does argument-hint: Description of expected arguments --- ``` **With Tool Constraints:** ```yaml --- description: Brief description of what this command does argument-hint: Description of expected arguments allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git push:*) --- ``` **Tool Constraint Examples:** - `Bash(git:*)` - Only git commands - `Bash(npm:*), Bash(yarn:*)` - Only package managers - `Read, Grep, Glob` - Only read operations - `Edit, Write` - Only file modifications - `TodoWrite` - Only todo list updates ### Step 3.2: Create Command Header ```markdown # [Command Name] You are [role description]. [Core responsibility and expertise]. User request: $ARGUMENTS --- ``` **Role Examples:** - "You are a senior React engineer specializing in component architecture." - "You are a git workflow expert who creates clean, semantic commits." - "You are a code reviewer focused on security and best practices." ### Step 3.3: Structure Command Body #### For Simple Commands (Pattern A): ```markdown ## Execution ### Step 1: [Action Name] [Detailed instructions] ### Step 2: [Action Name] [Detailed instructions] --- ## Success Checklist - [Verification item 1] - [Verification item 2] ``` #### For Workflow Commands (Pattern B): ```markdown ## Phase 1: [Phase Name] **Goal:** [What this phase accomplishes] ### Step 1.1: Create Todo List Create a todo list with these phases: - Phase 1: [name] - Phase 2: [name] - Phase 3: [name] - Phase 4: [name] ### Step 1.2: [Next Step] [Instructions] --- ## Phase 2: [Phase Name] **Goal:** [What this phase accomplishes] **CRITICAL: DO NOT SKIP THIS PHASE** (if important) ### Step 2.1: [Step Name] [Instructions] **Wait for user approval before proceeding.** --- ## Phase 3: [Phase Name] **CRITICAL: Implement in this exact order** ### Step 3.1: [Step Name] [Instructions with code examples] --- ## Phase 4: [Final Phase] ### Step 4.1: Summary [Provide completion summary] --- ## Success Checklist Before completing, verify: - [Item 1] - [Item 2] --- ## Key Principles 1. **Principle 1** - [Explanation] 2. **Principle 2** - [Explanation] ``` #### For Interactive Commands (Pattern C): ````markdown ## Phase 1: Information Gathering ### Step 1.1: Ask Questions Ask the user: 1. [Question 1] 2. [Question 2] 3. [Question 3] Wait for answers. --- ## Phase 2: Validation ### Step 2.1: Confirm Understanding Present: ```markdown ## Configuration Summary - [Setting 1]: [value] - [Setting 2]: [value] Proceed? (yes/no) ``` ```` **Wait for confirmation.** --- ## Phase 3: Execution [Implementation steps] --- ## Phase 4: Completion [Summary and next steps] ```` #### For Analysis Commands (Pattern D): ```markdown ## Phase 1: Context Gathering ### Step 1.1: Identify Files [Instructions for finding relevant files] ### Step 1.2: Load Context [Instructions for reading and understanding code] --- ## Phase 2: Analysis ### Step 2.1: [Analysis Type] [What to look for] ### Step 2.2: Score Findings [If using confidence scoring] Only report issues with e80% confidence. --- ## Phase 3: Report ### Step 3.1: Generate Report Format: ```markdown ## Analysis Results ### Issues Found ([count]) #### [Issue Category] **Confidence: [percentage]** **Location:** [file:line] **Description:** [what's wrong] **Recommendation:** [how to fix] ```` ### Step 3.2: Optional Remediation Ask user: "Would you like me to fix these issues?" --- ## Key Principles 1. **Be thorough** - Analyze all relevant code 2. **Be confident** - Only report high-confidence findings 3. **Be actionable** - Provide clear recommendations ```` ### Step 3.4: Add Inline Context (if needed) Commands can use inline bash commands for context: ```markdown ## Phase 1: Gather Context Examine the current state: - !git status - See file changes - !git diff --staged - See staged changes - !git log -5 --oneline - See recent commits Based on this context, [do something]... ```` **Common Inline Commands:** - !git status - Current git state - !git diff - Changes in working directory - !git log - Commit history - !ls -la - File listing - !npm list - Installed packages ### Step 3.5: Add Examples and Commentary (optional but helpful) ```markdown ## Examples Context: User wants to create a login component User: /create-component LoginForm Assistant: I'll create a LoginForm component. Let me start by... The command uses the create-component pattern to scaffold a new component with all necessary files and patterns. Context: User wants to commit changes User: /commit Assistant: Let me review the changes first... Assistant: I'll create a commit for these changes: The commit command analyzes changes to create appropriate commit messages following the repository's conventions. ``` ### Step 3.6: Complete Command File Combine all sections: ```markdown --- description: [description] argument-hint: [hint] allowed-tools: [constraints if needed] --- # [Command Name] You are [role]. [responsibility]. User request: $ARGUMENTS --- [All phases and sections] --- ## Success Checklist - [checklist items] --- ## Key Principles 1. [principles] --- ## Examples (optional) [examples with commentary] ``` --- ## Phase 4: Validation & Testing ### Step 4.1: Review Checklist Verify the command file: **Structure:** - YAML frontmatter is valid - Description is clear and concise - Argument hint explains expected input - Tool constraints are appropriate (if any) **Content:** - Role and responsibility are clear - $ARGUMENTS is used for user input - Phases are logically ordered - Steps are numbered consistently - Instructions are detailed and actionable **Workflow:** - User approval gates exist (if workflow command) - Todo list creation included (if workflow command) - Success checklist is comprehensive - Key principles are documented **Quality:** - Examples demonstrate usage (if complex) - Edge cases are handled - Error conditions are addressed - Output format is specified ### Step 4.2: Save Command File Save as: `[plugin-directory]/commands/[command-name].md` Example paths: - `plugin-name/commands/create-feature.md` - `my-plugin/commands/run-tests.md` ### Step 4.3: Testing Instructions ````markdown ## Testing Your Command 1. **Install the plugin:** ```bash /plugin install plugin-name ``` ```` 2. **Run the command:** ```bash /command-name [test arguments] ``` 3. **Verify behavior:** - Check each phase executes correctly - Verify tool constraints are enforced - Test with various argument formats - Confirm expected output 4. **Debug if needed:** ```bash claude --debug # Watch for command execution and errors ``` 5. **Iterate:** - Refine based on testing - Update command file - Restart Claude Code to reload ```` ### Step 4.4: Completion Summary ```markdown ## Command Creation Complete!  **Command:** /[command-name] **Location:** [file path] **Pattern:** [A/B/C/D] ### File Structure: ```yaml --- description: [description] argument-hint: [hint] [allowed-tools if present] --- # [sections overview] ```` ### Next Steps: 1. Test the command in Claude Code 2. Refine based on user feedback 3. Add to plugin documentation 4. Consider related commands ### Related Resources: - Slash commands guide: https://docs.claude.com/en/docs/claude-code/slash-commands - Plugin reference: https://docs.claude.com/en/docs/claude-code/plugins-reference ```` --- ## Command Patterns Reference ### Pattern A: Simple Command **Use for:** Single-action operations **Structure:** - Brief introduction - 2-4 execution steps - Success checklist **Examples:** - Clean up branches - Format code - Run linter ### Pattern B: Workflow Command **Use for:** Multi-phase processes with user approval **Structure:** - Phase 1: Discovery + Todo list - Phase 2: Planning + Approval gate - Phase 3: Implementation (ordered steps) - Phase 4: Documentation/Summary - Success checklist - Key principles **Examples:** - Feature development - Component creation - Refactoring workflows ### Pattern C: Interactive Command **Use for:** User-guided operations **Structure:** - Phase 1: Questions - Phase 2: Validation + Approval - Phase 3: Execution - Phase 4: Summary **Examples:** - Scaffolding tools - Configuration wizards - Setup assistants ### Pattern D: Analysis Command **Use for:** Code review and validation **Structure:** - Phase 1: Context gathering - Phase 2: Analysis (with confidence scoring) - Phase 3: Report generation - Optional: Remediation phase **Examples:** - Code review - Pattern verification - Security analysis --- ## Tool Constraint Patterns ### Git Operations Only ```yaml allowed-tools: Bash(git:*) ```` ### Read-Only Analysis ```yaml allowed-tools: Read, Grep, Glob ``` ### File Modification Only ```yaml allowed-tools: Edit, Write ``` ### Specific Git Commands ```yaml allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git status:*) ``` ### Package Management ```yaml allowed-tools: Bash(npm:*), Bash(yarn:*), Bash(pnpm:*) ``` ### No Constraints ```yaml # Omit allowed-tools field entirely ``` --- ## Key Principles 1. **Clear Purpose** - One command, one responsibility 2. **Constrain Appropriately** - Use tool restrictions to prevent scope creep 3. **Guide the User** - Explicit phases and approval gates 4. **Use Context** - Inline commands provide relevant information 5. **Error Handling** - Account for edge cases and failures 6. **Document Thoroughly** - Examples and principles clarify intent 7. **Test Extensively** - Verify with real scenarios 8. **Iterate** - Refine based on actual usage --- ## Common Mistakes to Avoid 1. **Vague Descriptions** - Be specific about what the command does 2. **Missing Constraints** - Commands without constraints can do anything 3. **No Approval Gates** - Workflow commands need user confirmation 4. **Poor Argument Handling** - Validate and explain expected arguments 5. **Missing Examples** - Complex commands need usage examples 6. **No Success Criteria** - Include verification checklists 7. **Inconsistent Numbering** - Use consistent phase/step numbering 8. **Assuming Context** - Gather necessary context explicitly