Expert guidance for creating Claude Code slash commands with correct frontmatter, structure, and best practices
Expert guidance for creating Claude Code slash commands - quick actions triggered by /command-name.
Activate this skill when:
| Field | Required | Type | Description |
|---|---|---|---|
description |
No | string | Brief description shown in autocomplete |
allowed-tools |
No | string | Comma-separated list of tools (inherits if not specified) |
argument-hint |
No | string | Expected arguments (e.g., add [tagId] | remove [tagId] | list) |
model |
No | string | Specific model (sonnet, opus, haiku, inherit) |
disable-model-invocation |
No | boolean | Prevent SlashCommand tool from calling this |
commandType |
No | string | Set to "slash-command" for round-trip conversion |
@Reference files directly in command prompts using @ prefix:
Review the implementation in @src/utils/helpers.js
Compare @src/old-version.js with @src/new-version.js
!Execute bash commands inline using ! prefix (requires Bash in allowed-tools):
---
allowed-tools: Bash(git *)
---
Current git status: !`git status`
Last 5 commits: !`git log --oneline -5`
$ARGUMENTS - All arguments passed to command$1, $2, $3... $9 - Individual positional arguments.claude/commands/ to organize commands/subdirectory.command-name.claude/commands/git/quick-commit.md → /git.quick-commitSlash commands must be saved as Markdown files:
Project commands (shared with team):
.claude/commands/command-name.md
Personal commands (individual use):
~/.claude/commands/command-name.md
---
description: Generate documentation for code
allowed-tools: Read, Edit
model: sonnet
---
# 📝 Documentation Generator
Generate comprehensive documentation for the selected code.
## Instructions
- Analyze code structure and purpose
- Generate clear, concise documentation
- Include parameter descriptions
- Add usage examples
- Follow JSDoc/TSDoc format for TypeScript
---
description: Manage tags for files
argument-hint: add [tagId] | remove [tagId] | list
allowed-tools: Read, Write
---
# Tag Manager
Manage tags for project files.
## Usage
- `/tags add <tagId>` - Add a tag (use $1 for tagId)
- `/tags remove <tagId>` - Remove a tag (use $1 for tagId)
- `/tags list` - List all tags
## Implementation
Action: $1
Tag ID: $2
All arguments: $ARGUMENTS
---
description: Compare two files and suggest improvements
allowed-tools: Read, Edit
argument-hint: <file1> <file2>
---
# File Comparator
Compare @$1 with @$2 and identify:
- Differences in approach
- Which implementation is better
- Suggested improvements
---
description: Create commit with git status context
argument-hint: <commit-message>
allowed-tools: Bash(git *)
---
# Smart Git Commit
## Current Status
!`git status --short`
## Recent Changes
!`git diff --stat`
Create a commit with message: $ARGUMENTS
Ensure the commit message follows conventional commit format.
---
description: Quick code review
---
Review the current file for:
- Code quality issues
- Security vulnerabilities
- Performance bottlenecks
- Best practice violations
Brief description of what the command does. Shown in autocomplete. Defaults to first line from prompt if not specified.
---
description: Generate comprehensive documentation for selected code
---
Comma-separated string of tools the command can use. Inherits from conversation if not specified.
Valid tools: Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Task, Skill, SlashCommand, TodoWrite, AskUserQuestion
---
allowed-tools: Read, Edit, Grep
---
With Bash restrictions:
---
allowed-tools: Bash(git status:*), Bash(git diff:*), Read
---
Expected arguments for the command. Shown when auto-completing.
---
argument-hint: [file-path]
---
---
argument-hint: add [tagId] | remove [tagId] | list
---
Specific model to use for this command. Inherits from conversation if not specified.
Valid values:
sonnet - General purpose (Claude Sonnet 3.5)haiku - Fast, simple tasks (Claude Haiku 3.5)opus - Complex reasoning (Claude Opus 4)inherit - Use conversation model (default)---
model: sonnet
---
Set to true to prevent Claude from automatically invoking this command via the SlashCommand tool.
---
disable-model-invocation: true
---
Set to "slash-command" for explicit type preservation in round-trip conversion (PRPM extension).
---
commandType: slash-command
---
The content after frontmatter contains the command prompt and instructions.
Can include emoji icon for visual identification:
# 📝 Documentation Generator
# 🔍 Code Reviewer
Clear, actionable guidance for what the command should do:
## Instructions
- Analyze code structure and purpose
- Generate clear, concise documentation
- Include parameter descriptions
- Add usage examples
Specify expected output format:
## Output Format
Return formatted documentation ready to paste above the code:
/**
* Function description
* @param {string} name - Parameter description
* @returns {Promise<User>} Return value description
*/
Show Claude what good output looks like:
## Example Output
```typescript
/**
* Creates a new user with the provided data
* @param {UserData} userData - User information (email, name)
* @returns {Promise<User>} Created user with ID
* @throws {ValidationError} If email format is invalid
*/
async function createUser(userData: UserData): Promise<User> {
// ...
}
## Schema Validation
Commands are validated against the JSON Schema:
**Schema Location:** https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-slash-command.schema.json
**Required structure:**
```json
{
"frontmatter": {
"description": "string (optional)",
"allowed-tools": "string (optional)",
"argument-hint": "string (optional)",
"model": "string (optional)",
"disable-model-invocation": "boolean (optional)",
"commandType": "slash-command (optional)"
},
"content": "string (markdown content)"
}
| Mistake | Problem | Solution |
|---|---|---|
| Using array for tools | allowed-tools: [Read, Write] |
Use string: allowed-tools: Read, Write |
| Wrong field names | tools:, arguments: |
Use allowed-tools, argument-hint |
| Missing frontmatter delimiters | Frontmatter not parsed | Use --- before and after YAML |
| Invalid tool names | bash, grep (lowercase) |
Use capitalized: Bash, Grep |
| Invalid model values | 3.5-sonnet, claude-opus |
Use: sonnet, opus, haiku, inherit |
| Icons in frontmatter | icon: 📝 |
Put icon in H1: # 📝 Title |
| No description | Autocomplete shows filename | Add description field |
Each command should do ONE thing well:
Good:
---
description: Generate JSDoc comments for functions
---
Bad:
---
description: Generate docs, fix linting, add tests, refactor code
---
Make descriptions specific and actionable:
Good:
description: Generate comprehensive JSDoc documentation for selected code
Bad:
description: Make docs
Only request tools actually needed:
Good:
allowed-tools: Read, Edit
Bad:
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, WebSearch
Use argument-hint to show expected arguments:
argument-hint: [file-path]
argument-hint: <feature-name>
argument-hint: add [item] | remove [item] | list
Show users how to invoke the command:
## Usage
- `/generate-docs path/to/file.ts` - Generate docs for specific file
- `/generate-docs` - Generate docs for current selection
Tell Claude what format you want:
## Output Format
Generate TypeScript interfaces with JSDoc comments:
```typescript
/**
* User account information
*/
interface User {
/** Unique identifier */
id: string;
/** User email address */
email: string;
}
### 7. Add Examples to Prompt
Show Claude examples of good output:
```markdown
## Example
Good documentation:
```typescript
/**
* Calculates total price with tax
* @param price - Base price before tax
* @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
* @returns Total price including tax
*/
function calculateTotal(price: number, taxRate: number): number {
return price * (1 + taxRate);
}
### 8. Use Icons for Visual Identification
Add emoji to H1 heading for quick recognition:
```markdown
# 📝 Documentation Generator
# 🔍 Code Reviewer
# 🧪 Test Generator
# 🔧 Refactoring Assistant
# 🐛 Bug Finder
Organize related commands using subdirectories:
File: .claude/commands/git/status.md
---
description: Show enhanced git status
allowed-tools: Bash(git *)
---
# Git Status
!`git status`
Branch: !`git branch --show-current`
Recent commits: !`git log --oneline -3`
Invoke with: /git.status
File: .claude/commands/git/quick-commit.md
---
description: Quick commit with conventional format
argument-hint: <type> <message>
allowed-tools: Bash(git *)
---
# Quick Commit
Create conventional commit: $1($2): $ARGUMENTS
!`git add -A && git commit -m "$1: $ARGUMENTS"`
Invoke with: /git.quick-commit feat "add user auth"
---
description: Review code for quality, security, and performance issues
allowed-tools: Read, Grep
---
# 🔍 Code Reviewer
Review the selected code or current file for:
## Code Quality
- Clean, readable code
- Proper naming conventions
- DRY principle adherence
- SOLID principles
## Security
- Input validation
- SQL injection risks
- XSS vulnerabilities
- Authentication/authorization
## Performance
- Inefficient algorithms
- Unnecessary computations
- Memory leaks
- Database query optimization
## Output Format
Provide specific file:line references for all issues:
**[Issue Type]** (file.ts:42) - Issue description and suggested fix
---
description: Generate comprehensive documentation for selected code
allowed-tools: Read, Edit
model: sonnet
---
# 📝 Documentation Generator
Generate comprehensive documentation for the selected code.
## Instructions
- Analyze code structure and purpose
- Generate clear, concise documentation
- Include parameter descriptions with types
- Add usage examples
- Follow JSDoc/TSDoc format for TypeScript
- Document error conditions and edge cases
## Output Format
Return formatted documentation ready to paste above the code.
For TypeScript/JavaScript:
```typescript
/**
* Function description
* @param {Type} paramName - Parameter description
* @returns {ReturnType} Return value description
* @throws {ErrorType} Error conditions
*/
### Test Generator
```markdown
---
description: Generate test cases for selected code
allowed-tools: Read, Write
---
# 🧪 Test Generator
Generate comprehensive test cases for the selected code.
## Test Coverage
Create tests covering:
- Happy path scenarios
- Edge cases
- Error conditions
- Boundary values
- Invalid input handling
## Structure
Follow the project's testing conventions:
- Use existing test framework (Jest, Mocha, etc.)
- Match naming patterns
- Follow setup/teardown patterns
- Use appropriate matchers
## Example
```typescript
describe('calculateTotal', () => {
it('should calculate total with valid inputs', () => {
const result = calculateTotal(100, 0.08);
expect(result).toBe(108);
});
it('should handle zero tax rate', () => {
const result = calculateTotal(100, 0);
expect(result).toBe(100);
});
it('should throw for negative price', () => {
expect(() => calculateTotal(-100, 0.08)).toThrow();
});
});
### Git Workflow Command
```markdown
---
description: Create and push feature branch
argument-hint: <feature-name>
allowed-tools: Bash(git *)
---
# 🌿 Feature Branch Creator
Create and push a new feature branch.
## Process
1. Create branch: `feature/$1`
2. Switch to new branch
3. Push to origin with upstream tracking
## Usage
```bash
/feature user-authentication
/feature api-optimization
git checkout -b feature/$1
git push -u origin feature/$1
### Refactoring Command
```markdown
---
description: Refactor code while preserving behavior
allowed-tools: Read, Edit, Bash
---
# 🔧 Refactoring Assistant
Refactor the selected code while maintaining functionality.
## Guidelines
- Preserve existing behavior exactly
- Improve code structure and readability
- Extract reusable functions
- Reduce complexity
- Follow project conventions
- Update related tests
## Process
1. Read and understand current implementation
2. Identify refactoring opportunities
3. Propose changes with explanations
4. Update code with improvements
5. Verify tests still pass
6. Update documentation if needed
## Safety
- Run tests after refactoring
- Commit changes incrementally
- Keep changes focused and atomic
Before finalizing a slash command:
allowed-tools is comma-separated string, not array.claude/commands/*.md