1# Command Frontmatter Reference
2 
3Complete reference for YAML frontmatter fields in slash commands.
4 
5## Frontmatter Overview
6 
7YAML frontmatter is optional metadata at the start of command files:
8 
9```markdown
10---
11description: Brief description
12allowed-tools: Read, Write
13model: sonnet
14argument-hint: [arg1] [arg2]
15---
16 
17Command prompt content here...
18```
19 
20All fields are optional. Commands work without any frontmatter.
21 
22## Field Specifications
23 
24### description
25 
26**Type:** String
27**Required:** No
28**Default:** First line of command prompt
29**Max Length:** ~60 characters recommended for `/help` display
30 
31**Purpose:** Describes what the command does, shown in `/help` output
32 
33**Examples:**
34```yaml
35description: Review code for security issues
36```
37```yaml
38description: Deploy to staging environment
39```
40```yaml
41description: Generate API documentation
42```
43 
44**Best practices:**
45- Keep under 60 characters for clean display
46- Start with verb (Review, Deploy, Generate)
47- Be specific about what command does
48- Avoid redundant "command" or "slash command"
49 
50**Good:**
51- ✅ "Review PR for code quality and security"
52- ✅ "Deploy application to specified environment"
53- ✅ "Generate comprehensive API documentation"
54 
55**Bad:**
56- ❌ "This command reviews PRs" (unnecessary "This command")
57- ❌ "Review" (too vague)
58- ❌ "A command that reviews pull requests for code quality, security issues, and best practices" (too long)
59 
60### allowed-tools
61 
62**Type:** String or Array of strings
63**Required:** No
64**Default:** Inherits from conversation permissions
65 
66**Purpose:** Restrict or specify which tools command can use
67 
68**Formats:**
69 
70**Single tool:**
71```yaml
72allowed-tools: Read
73```
74 
75**Multiple tools (comma-separated):**
76```yaml
77allowed-tools: Read, Write, Edit
78```
79 
80**Multiple tools (array):**
81```yaml
82allowed-tools:
83  - Read
84  - Write
85  - Bash(git:*)
86```
87 
88**Tool Patterns:**
89 
90**Specific tools:**
91```yaml
92allowed-tools: Read, Grep, Edit
93```
94 
95**Bash with command filter:**
96```yaml
97allowed-tools: Bash(git:*)           # Only git commands
98allowed-tools: Bash(npm:*)           # Only npm commands
99allowed-tools: Bash(docker:*)        # Only docker commands
100```
101 
102**All tools (not recommended):**
103```yaml
104allowed-tools: "*"
105```
106 
107**When to use:**
108 
1091. **Security:** Restrict command to safe operations
110   ```yaml
111   allowed-tools: Read, Grep  # Read-only command
112   ```
113 
1142. **Clarity:** Document required tools
115   ```yaml
116   allowed-tools: Bash(git:*), Read
117   ```
118 
1193. **Bash execution:** Enable bash command output
120   ```yaml
121   allowed-tools: Bash(git status:*), Bash(git diff:*)
122   ```
123 
124**Best practices:**
125- Be as restrictive as possible
126- Use command filters for Bash (e.g., `git:*` not `*`)
127- Only specify when different from conversation permissions
128- Document why specific tools are needed
129 
130### model
131 
132**Type:** String
133**Required:** No
134**Default:** Inherits from conversation
135**Values:** `sonnet`, `opus`, `haiku`
136 
137**Purpose:** Specify which Claude model executes the command
138 
139**Examples:**
140```yaml
141model: haiku    # Fast, efficient for simple tasks
142```
143```yaml
144model: sonnet   # Balanced performance (default)
145```
146```yaml
147model: opus     # Maximum capability for complex tasks
148```
149 
150**When to use:**
151 
152**Use `haiku` for:**
153- Simple, formulaic commands
154- Fast execution needed
155- Low complexity tasks
156- Frequent invocations
157 
158```yaml
159---
160description: Format code file
161model: haiku
162---
163```
164 
165**Use `sonnet` for:**
166- Standard commands (default)
167- Balanced speed/quality
168- Most common use cases
169 
170```yaml
171---
172description: Review code changes
173model: sonnet
174---
175```
176 
177**Use `opus` for:**
178- Complex analysis
179- Architectural decisions
180- Deep code understanding
181- Critical tasks
182 
183```yaml
184---
185description: Analyze system architecture
186model: opus
187---
188```
189 
190**Best practices:**
191- Omit unless specific need
192- Use `haiku` for speed when possible
193- Reserve `opus` for genuinely complex tasks
194- Test with different models to find right balance
195 
196### argument-hint
197 
198**Type:** String
199**Required:** No
200**Default:** None
201 
202**Purpose:** Document expected arguments for users and autocomplete
203 
204**Format:**
205```yaml
206argument-hint: [arg1] [arg2] [optional-arg]
207```
208 
209**Examples:**
210 
211**Single argument:**
212```yaml
213argument-hint: [pr-number]
214```
215 
216**Multiple required arguments:**
217```yaml
218argument-hint: [environment] [version]
219```
220 
221**Optional arguments:**
222```yaml
223argument-hint: [file-path] [options]
224```
225 
226**Descriptive names:**
227```yaml
228argument-hint: [source-branch] [target-branch] [commit-message]
229```
230 
231**Best practices:**
232- Use square brackets `[]` for each argument
233- Use descriptive names (not `arg1`, `arg2`)
234- Indicate optional vs required in description
235- Match order to positional arguments in command
236- Keep concise but clear
237 
238**Examples by pattern:**
239 
240**Simple command:**
241```yaml
242---
243description: Fix issue by number
244argument-hint: [issue-number]
245---
246 
247Fix issue #$1...
248```
249 
250**Multi-argument:**
251```yaml
252---
253description: Deploy to environment
254argument-hint: [app-name] [environment] [version]
255---
256 
257Deploy $1 to $2 using version $3...
258```
259 
260**With options:**
261```yaml
262---
263description: Run tests with options
264argument-hint: [test-pattern] [options]
265---
266 
267Run tests matching $1 with options: $2
268```
269 
270### disable-model-invocation
271 
272**Type:** Boolean
273**Required:** No
274**Default:** false
275 
276**Purpose:** Prevent SlashCommand tool from programmatically invoking command
277 
278**Examples:**
279```yaml
280disable-model-invocation: true
281```
282 
283**When to use:**
284 
2851. **Manual-only commands:** Commands requiring user judgment
286   ```yaml
287   ---
288   description: Approve deployment to production
289   disable-model-invocation: true
290   ---
291   ```
292 
2932. **Destructive operations:** Commands with irreversible effects
294   ```yaml
295   ---
296   description: Delete all test data
297   disable-model-invocation: true
298   ---
299   ```
300 
3013. **Interactive workflows:** Commands needing user input
302   ```yaml
303   ---
304   description: Walk through setup wizard
305   disable-model-invocation: true
306   ---
307   ```
308 
309**Default behavior (false):**
310- Command available to SlashCommand tool
311- Claude can invoke programmatically
312- Still available for manual invocation
313 
314**When true:**
315- Command only invokable by user typing `/command`
316- Not available to SlashCommand tool
317- Safer for sensitive operations
318 
319**Best practices:**
320- Use sparingly (limits Claude's autonomy)
321- Document why in command comments
322- Consider if command should exist if always manual
323 
324## Complete Examples
325 
326### Minimal Command
327 
328No frontmatter needed:
329 
330```markdown
331Review this code for common issues and suggest improvements.
332```
333 
334### Simple Command
335 
336Just description:
337 
338```markdown
339---
340description: Review code for issues
341---
342 
343Review this code for common issues and suggest improvements.
344```
345 
346### Standard Command
347 
348Description and tools:
349 
350```markdown
351---
352description: Review Git changes
353allowed-tools: Bash(git:*), Read
354---
355 
356Current changes: !`git diff --name-only`
357 
358Review each changed file for:
359- Code quality
360- Potential bugs
361- Best practices
362```
363 
364### Complex Command
365 
366All common fields:
367 
368```markdown
369---
370description: Deploy application to environment
371argument-hint: [app-name] [environment] [version]
372allowed-tools: Bash(kubectl:*), Bash(helm:*), Read
373model: sonnet
374---
375 
376Deploy $1 to $2 environment using version $3
377 
378Pre-deployment checks:
379- Verify $2 configuration
380- Check cluster status: !`kubectl cluster-info`
381- Validate version $3 exists
382 
383Proceed with deployment following deployment runbook.
384```
385 
386### Manual-Only Command
387 
388Restricted invocation:
389 
390```markdown
391---
392description: Approve production deployment
393argument-hint: [deployment-id]
394disable-model-invocation: true
395allowed-tools: Bash(gh:*)
396---
397 
398<!--
399MANUAL APPROVAL REQUIRED
400This command requires human judgment and cannot be automated.
401-->
402 
403Review deployment $1 for production approval:
404 
405Deployment details: !`gh api /deployments/$1`
406 
407Verify:
408- All tests passed
409- Security scan clean
410- Stakeholder approval
411- Rollback plan ready
412 
413Type "APPROVED" to confirm deployment.
414```
415 
416## Validation
417 
418### Common Errors
419 
420**Invalid YAML syntax:**
421```yaml
422---
423description: Missing quote
424allowed-tools: Read, Write
425model: sonnet
426---  # ❌ Missing closing quote above
427```
428 
429**Fix:** Validate YAML syntax
430 
431**Incorrect tool specification:**
432```yaml
433allowed-tools: Bash  # ❌ Missing command filter
434```
435 
436**Fix:** Use `Bash(git:*)` format
437 
438**Invalid model name:**
439```yaml
440model: gpt4  # ❌ Not a valid Claude model
441```
442 
443**Fix:** Use `sonnet`, `opus`, or `haiku`
444 
445### Validation Checklist
446 
447Before committing command:
448- [ ] YAML syntax valid (no errors)
449- [ ] Description under 60 characters
450- [ ] allowed-tools uses proper format
451- [ ] model is valid value if specified
452- [ ] argument-hint matches positional arguments
453- [ ] disable-model-invocation used appropriately
454 
455## Best Practices Summary
456 
4571. **Start minimal:** Add frontmatter only when needed
4582. **Document arguments:** Always use argument-hint with arguments
4593. **Restrict tools:** Use most restrictive allowed-tools that works
4604. **Choose right model:** Use haiku for speed, opus for complexity
4615. **Manual-only sparingly:** Only use disable-model-invocation when necessary
4626. **Clear descriptions:** Make commands discoverable in `/help`
4637. **Test thoroughly:** Verify frontmatter works as expected
464