gh-crathgeb-claude-code-plugins-plugins-plugin-builder/commands/create-command.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Create a new slash command for a Claude Code plugin	Command name and purpose	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:

## 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:

---
description: Brief description of what this command does
argument-hint: Description of expected arguments
---

With Tool Constraints:

---
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

# [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):

## 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):

## 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):

## 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)

## 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:

---
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

## Testing Your Command

1. **Install the plugin:**
   ```bash
   /plugin install plugin-name
   ```

2. Run the command:

   /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:

   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

allowed-tools: Read, Grep, Glob

File Modification Only

allowed-tools: Edit, Write

Specific Git Commands

allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git status:*)

Package Management

allowed-tools: Bash(npm:*), Bash(yarn:*), Bash(pnpm:*)

No Constraints

# 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