715 lines
13 KiB
Markdown
715 lines
13 KiB
Markdown
---
|
||
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
|
||
|
||
<example>
|
||
Context: User wants to create a login component
|
||
User: /create-component LoginForm
|
||
Assistant: I'll create a LoginForm component. Let me start by...
|
||
<commentary>
|
||
The command uses the create-component pattern to scaffold
|
||
a new component with all necessary files and patterns.
|
||
</commentary>
|
||
</example>
|
||
|
||
<example>
|
||
Context: User wants to commit changes
|
||
User: /commit
|
||
Assistant: Let me review the changes first...
|
||
<runs git status and git diff>
|
||
Assistant: I'll create a commit for these changes:
|
||
<creates commit with semantic message>
|
||
<commentary>
|
||
The commit command analyzes changes to create appropriate
|
||
commit messages following the repository's conventions.
|
||
</commentary>
|
||
</example>
|
||
```
|
||
|
||
### 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
|