surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / command-development / references / frontmatter-reference.md

Claudedocs: Add skills frontmatter field documentation 13530b1 · on Dec 11, 2025 History

511 lines · 10.3 KBPreview CodeRaw

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