plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
Complete reference for YAML frontmatter fields in slash commands.
YAML frontmatter is optional metadata at the start of command files:
---
description: Brief description
allowed-tools: Read, Write
model: sonnet
argument-hint: [arg1] [arg2]
---
Command prompt content here...
All fields are optional. Commands work without any frontmatter.
Type: String
Required: No
Default: First line of command prompt
Max Length: ~60 characters recommended for /help display
Purpose: Describes what the command does, shown in /help output
Examples:
description: Review code for security issues
description: Deploy to staging environment
description: Generate API documentation
Best practices:
Good:
Bad:
Type: String or Array of strings Required: No Default: Inherits from conversation permissions
Purpose: Restrict or specify which tools command can use
Formats:
Single tool:
allowed-tools: Read
Multiple tools (comma-separated):
allowed-tools: Read, Write, Edit
Multiple tools (array):
allowed-tools:
- Read
- Write
- Bash(git:*)
Tool Patterns:
Specific tools:
allowed-tools: Read, Grep, Edit
Bash with command filter:
allowed-tools: Bash(git:*) # Only git commands
allowed-tools: Bash(npm:*) # Only npm commands
allowed-tools: Bash(docker:*) # Only docker commands
All tools (not recommended):
allowed-tools: "*"
When to use:
Security: Restrict command to safe operations
allowed-tools: Read, Grep # Read-only command
Clarity: Document required tools
allowed-tools: Bash(git:*), Read
Bash execution: Enable bash command output
allowed-tools: Bash(git status:*), Bash(git diff:*)
Best practices:
git:* not *)Type: String
Required: No
Default: Inherits from conversation
Values: sonnet, opus, haiku
Purpose: Specify which Claude model executes the command
Examples:
model: haiku # Fast, efficient for simple tasks
model: sonnet # Balanced performance (default)
model: opus # Maximum capability for complex tasks
When to use:
Use haiku for:
---
description: Format code file
model: haiku
---
Use sonnet for:
---
description: Review code changes
model: sonnet
---
Use opus for:
---
description: Analyze system architecture
model: opus
---
Best practices:
haiku for speed when possibleopus for genuinely complex tasksType: String Required: No Default: None
Purpose: Document expected arguments for users and autocomplete
Format:
argument-hint: [arg1] [arg2] [optional-arg]
Examples:
Single argument:
argument-hint: [pr-number]
Multiple required arguments:
argument-hint: [environment] [version]
Optional arguments:
argument-hint: [file-path] [options]
Descriptive names:
argument-hint: [source-branch] [target-branch] [commit-message]
Best practices:
[] for each argumentarg1, arg2)Examples by pattern:
Simple command:
---
description: Fix issue by number
argument-hint: [issue-number]
---
Fix issue #$1...
Multi-argument:
---
description: Deploy to environment
argument-hint: [app-name] [environment] [version]
---
Deploy $1 to $2 using version $3...
With options:
---
description: Run tests with options
argument-hint: [test-pattern] [options]
---
Run tests matching $1 with options: $2
Type: Boolean Required: No Default: false
Purpose: Prevent SlashCommand tool from programmatically invoking command
Examples:
disable-model-invocation: true
When to use:
Manual-only commands: Commands requiring user judgment
---
description: Approve deployment to production
disable-model-invocation: true
---
Destructive operations: Commands with irreversible effects
---
description: Delete all test data
disable-model-invocation: true
---
Interactive workflows: Commands needing user input
---
description: Walk through setup wizard
disable-model-invocation: true
---
Default behavior (false):
When true:
/commandBest practices:
No frontmatter needed:
Review this code for common issues and suggest improvements.
Just description:
---
description: Review code for issues
---
Review this code for common issues and suggest improvements.
Description and tools:
---
description: Review Git changes
allowed-tools: Bash(git:*), Read
---
Current changes: !`git diff --name-only`
Review each changed file for:
- Code quality
- Potential bugs
- Best practices
All common fields:
---
description: Deploy application to environment
argument-hint: [app-name] [environment] [version]
allowed-tools: Bash(kubectl:*), Bash(helm:*), Read
model: sonnet
---
Deploy $1 to $2 environment using version $3
Pre-deployment checks:
- Verify $2 configuration
- Check cluster status: !`kubectl cluster-info`
- Validate version $3 exists
Proceed with deployment following deployment runbook.
Restricted invocation:
---
description: Approve production deployment
argument-hint: [deployment-id]
disable-model-invocation: true
allowed-tools: Bash(gh:*)
---
<!--
MANUAL APPROVAL REQUIRED
This command requires human judgment and cannot be automated.
-->
Review deployment $1 for production approval:
Deployment details: !`gh api /deployments/$1`
Verify:
- All tests passed
- Security scan clean
- Stakeholder approval
- Rollback plan ready
Type "APPROVED" to confirm deployment.
Invalid YAML syntax:
---
description: Missing quote
allowed-tools: Read, Write
model: sonnet
--- # ❌ Missing closing quote above
Fix: Validate YAML syntax
Incorrect tool specification:
allowed-tools: Bash # ❌ Missing command filter
Fix: Use Bash(git:*) format
Invalid model name:
model: gpt4 # ❌ Not a valid Claude model
Fix: Use sonnet, opus, or haiku
Before committing command:
/help