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 / SKILL.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

834 lines · 18.5 KBPreview CodeRaw

1	---
2	name: Command Development
3	description: This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
4	version: 0.2.0
5	---
6
7	# Command Development for Claude Code
8
9	## Overview
10
11	Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.
12
13	Key concepts:
14	- Markdown file format for commands
15	- YAML frontmatter for configuration
16	- Dynamic arguments and file references
17	- Bash execution for context
18	- Command organization and namespacing
19
20	## Command Basics
21
22	### What is a Slash Command?
23
24	A slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:
25	- Reusability: Define once, use repeatedly
26	- Consistency: Standardize common workflows
27	- Sharing: Distribute across team or projects
28	- Efficiency: Quick access to complex prompts
29
30	### Critical: Commands are Instructions FOR Claude
31
32	Commands are written for agent consumption, not human consumption.
33
34	When a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.
35
36	Correct approach (instructions for Claude):
37	```markdown
38	Review this code for security vulnerabilities including:
39	- SQL injection
40	- XSS attacks
41	- Authentication issues
42
43	Provide specific line numbers and severity ratings.
44	```
45
46	Incorrect approach (messages to user):
47	```markdown
48	This command will review your code for security issues.
49	You'll receive a report with vulnerability details.
50	```
51
52	The first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.
53
54	### Command Locations
55
56	Project commands (shared with team):
57	- Location: `.claude/commands/`
58	- Scope: Available in specific project
59	- Label: Shown as "(project)" in `/help`
60	- Use for: Team workflows, project-specific tasks
61
62	Personal commands (available everywhere):
63	- Location: `~/.claude/commands/`
64	- Scope: Available in all projects
65	- Label: Shown as "(user)" in `/help`
66	- Use for: Personal workflows, cross-project utilities
67
68	Plugin commands (bundled with plugins):
69	- Location: `plugin-name/commands/`
70	- Scope: Available when plugin installed
71	- Label: Shown as "(plugin-name)" in `/help`
72	- Use for: Plugin-specific functionality
73
74	## File Format
75
76	### Basic Structure
77
78	Commands are Markdown files with `.md` extension:
79
80	```
81	.claude/commands/
82	├── review.md # /review command
83	├── test.md # /test command
84	└── deploy.md # /deploy command
85	```
86
87	Simple command:
88	```markdown
89	Review this code for security vulnerabilities including:
90	- SQL injection
91	- XSS attacks
92	- Authentication bypass
93	- Insecure data handling
94	```
95
96	No frontmatter needed for basic commands.
97
98	### With YAML Frontmatter
99
100	Add configuration using YAML frontmatter:
101
102	```markdown
103	---
104	description: Review code for security issues
105	allowed-tools: Read, Grep, Bash(git:*)
106	model: sonnet
107	---
108
109	Review this code for security vulnerabilities...
110	```
111
112	## YAML Frontmatter Fields
113
114	### description
115
116	Purpose: Brief description shown in `/help`
117	Type: String
118	Default: First line of command prompt
119
120	```yaml
121	---
122	description: Review pull request for code quality
123	---
124	```
125
126	Best practice: Clear, actionable description (under 60 characters)
127
128	### allowed-tools
129
130	Purpose: Specify which tools command can use
131	Type: String or Array
132	Default: Inherits from conversation
133
134	```yaml
135	---
136	allowed-tools: Read, Write, Edit, Bash(git:*)
137	---
138	```
139
140	Patterns:
141	- `Read, Write, Edit` - Specific tools
142	- `Bash(git:*)` - Bash with git commands only
143	- `*` - All tools (rarely needed)
144
145	Use when: Command requires specific tool access
146
147	### model
148
149	Purpose: Specify model for command execution
150	Type: String (sonnet, opus, haiku)
151	Default: Inherits from conversation
152
153	```yaml
154	---
155	model: haiku
156	---
157	```
158
159	Use cases:
160	- `haiku` - Fast, simple commands
161	- `sonnet` - Standard workflows
162	- `opus` - Complex analysis
163
164	### argument-hint
165
166	Purpose: Document expected arguments for autocomplete
167	Type: String
168	Default: None
169
170	```yaml
171	---
172	argument-hint: [pr-number] [priority] [assignee]
173	---
174	```
175
176	Benefits:
177	- Helps users understand command arguments
178	- Improves command discovery
179	- Documents command interface
180
181	### disable-model-invocation
182
183	Purpose: Prevent SlashCommand tool from programmatically calling command
184	Type: Boolean
185	Default: false
186
187	```yaml
188	---
189	disable-model-invocation: true
190	---
191	```
192
193	Use when: Command should only be manually invoked
194
195	## Dynamic Arguments
196
197	### Using $ARGUMENTS
198
199	Capture all arguments as single string:
200
201	```markdown
202	---
203	description: Fix issue by number
204	argument-hint: [issue-number]
205	---
206
207	Fix issue #$ARGUMENTS following our coding standards and best practices.
208	```
209
210	Usage:
211	```
212	> /fix-issue 123
213	> /fix-issue 456
214	```
215
216	Expands to:
217	```
218	Fix issue #123 following our coding standards...
219	Fix issue #456 following our coding standards...
220	```
221
222	### Using Positional Arguments
223
224	Capture individual arguments with `$1`, `$2`, `$3`, etc.:
225
226	```markdown
227	---
228	description: Review PR with priority and assignee
229	argument-hint: [pr-number] [priority] [assignee]
230	---
231
232	Review pull request #$1 with priority level $2.
233	After review, assign to $3 for follow-up.
234	```
235
236	Usage:
237	```
238	> /review-pr 123 high alice
239	```
240
241	Expands to:
242	```
243	Review pull request #123 with priority level high.
244	After review, assign to alice for follow-up.
245	```
246
247	### Combining Arguments
248
249	Mix positional and remaining arguments:
250
251	```markdown
252	Deploy $1 to $2 environment with options: $3
253	```
254
255	Usage:
256	```
257	> /deploy api staging --force --skip-tests
258	```
259
260	Expands to:
261	```
262	Deploy api to staging environment with options: --force --skip-tests
263	```
264
265	## File References
266
267	### Using @ Syntax
268
269	Include file contents in command:
270
271	```markdown
272	---
273	description: Review specific file
274	argument-hint: [file-path]
275	---
276
277	Review @$1 for:
278	- Code quality
279	- Best practices
280	- Potential bugs
281	```
282
283	Usage:
284	```
285	> /review-file src/api/users.ts
286	```
287
288	Effect: Claude reads `src/api/users.ts` before processing command
289
290	### Multiple File References
291
292	Reference multiple files:
293
294	```markdown
295	Compare @src/old-version.js with @src/new-version.js
296
297	Identify:
298	- Breaking changes
299	- New features
300	- Bug fixes
301	```
302
303	### Static File References
304
305	Reference known files without arguments:
306
307	```markdown
308	Review @package.json and @tsconfig.json for consistency
309
310	Ensure:
311	- TypeScript version matches
312	- Dependencies are aligned
313	- Build configuration is correct
314	```
315
316	## Bash Execution in Commands
317
318	Commands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.
319
320	When to use:
321	- Include dynamic context (git status, environment vars, etc.)
322	- Gather project/repository state
323	- Build context-aware workflows
324
325	Implementation details:
326	For complete syntax, examples, and best practices, see `references/plugin-features-reference.md` section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues
327
328	## Command Organization
329
330	### Flat Structure
331
332	Simple organization for small command sets:
333
334	```
335	.claude/commands/
336	├── build.md
337	├── test.md
338	├── deploy.md
339	├── review.md
340	└── docs.md
341	```
342
343	Use when: 5-15 commands, no clear categories
344
345	### Namespaced Structure
346
347	Organize commands in subdirectories:
348
349	```
350	.claude/commands/
351	├── ci/
352	│ ├── build.md # /build (project:ci)
353	│ ├── test.md # /test (project:ci)
354	│ └── lint.md # /lint (project:ci)
355	├── git/
356	│ ├── commit.md # /commit (project:git)
357	│ └── pr.md # /pr (project:git)
358	└── docs/
359	├── generate.md # /generate (project:docs)
360	└── publish.md # /publish (project:docs)
361	```
362
363	Benefits:
364	- Logical grouping by category
365	- Namespace shown in `/help`
366	- Easier to find related commands
367
368	Use when: 15+ commands, clear categories
369
370	## Best Practices
371
372	### Command Design
373
374	1. Single responsibility: One command, one task
375	2. Clear descriptions: Self-explanatory in `/help`
376	3. Explicit dependencies: Use `allowed-tools` when needed
377	4. Document arguments: Always provide `argument-hint`
378	5. Consistent naming: Use verb-noun pattern (review-pr, fix-issue)
379
380	### Argument Handling
381
382	1. Validate arguments: Check for required arguments in prompt
383	2. Provide defaults: Suggest defaults when arguments missing
384	3. Document format: Explain expected argument format
385	4. Handle edge cases: Consider missing or invalid arguments
386
387	```markdown
388	---
389	argument-hint: [pr-number]
390	---
391
392	$IF($1,
393	Review PR #$1,
394	Please provide a PR number. Usage: /review-pr [number]
395	)
396	```
397
398	### File References
399
400	1. Explicit paths: Use clear file paths
401	2. Check existence: Handle missing files gracefully
402	3. Relative paths: Use project-relative paths
403	4. Glob support: Consider using Glob tool for patterns
404
405	### Bash Commands
406
407	1. Limit scope: Use `Bash(git:)` not `Bash()`
408	2. Safe commands: Avoid destructive operations
409	3. Handle errors: Consider command failures
410	4. Keep fast: Long-running commands slow invocation
411
412	### Documentation
413
414	1. Add comments: Explain complex logic
415	2. Provide examples: Show usage in comments
416	3. List requirements: Document dependencies
417	4. Version commands: Note breaking changes
418
419	```markdown
420	---
421	description: Deploy application to environment
422	argument-hint: [environment] [version]
423	---
424
425	<!--
426	Usage: /deploy [staging\|production] [version]
427	Requires: AWS credentials configured
428	Example: /deploy staging v1.2.3
429	-->
430
431	Deploy application to $1 environment using version $2...
432	```
433
434	## Common Patterns
435
436	### Review Pattern
437
438	```markdown
439	---
440	description: Review code changes
441	allowed-tools: Read, Bash(git:*)
442	---
443
444	Files changed: !`git diff --name-only`
445
446	Review each file for:
447	1. Code quality and style
448	2. Potential bugs or issues
449	3. Test coverage
450	4. Documentation needs
451
452	Provide specific feedback for each file.
453	```
454
455	### Testing Pattern
456
457	```markdown
458	---
459	description: Run tests for specific file
460	argument-hint: [test-file]
461	allowed-tools: Bash(npm:*)
462	---
463
464	Run tests: !`npm test $1`
465
466	Analyze results and suggest fixes for failures.
467	```
468
469	### Documentation Pattern
470
471	```markdown
472	---
473	description: Generate documentation for file
474	argument-hint: [source-file]
475	---
476
477	Generate comprehensive documentation for @$1 including:
478	- Function/class descriptions
479	- Parameter documentation
480	- Return value descriptions
481	- Usage examples
482	- Edge cases and errors
483	```
484
485	### Workflow Pattern
486
487	```markdown
488	---
489	description: Complete PR workflow
490	argument-hint: [pr-number]
491	allowed-tools: Bash(gh:*), Read
492	---
493
494	PR #$1 Workflow:
495
496	1. Fetch PR: !`gh pr view $1`
497	2. Review changes
498	3. Run checks
499	4. Approve or request changes
500	```
501
502	## Troubleshooting
503
504	Command not appearing:
505	- Check file is in correct directory
506	- Verify `.md` extension present
507	- Ensure valid Markdown format
508	- Restart Claude Code
509
510	Arguments not working:
511	- Verify `$1`, `$2` syntax correct
512	- Check `argument-hint` matches usage
513	- Ensure no extra spaces
514
515	Bash execution failing:
516	- Check `allowed-tools` includes Bash
517	- Verify command syntax in backticks
518	- Test command in terminal first
519	- Check for required permissions
520
521	File references not working:
522	- Verify `@` syntax correct
523	- Check file path is valid
524	- Ensure Read tool allowed
525	- Use absolute or project-relative paths
526
527	## Plugin-Specific Features
528
529	### CLAUDE_PLUGIN_ROOT Variable
530
531	Plugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path.
532
533	Purpose:
534	- Reference plugin files portably
535	- Execute plugin scripts
536	- Load plugin configuration
537	- Access plugin templates
538
539	Basic usage:
540
541	```markdown
542	---
543	description: Analyze using plugin script
544	allowed-tools: Bash(node:*)
545	---
546
547	Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`
548
549	Review results and report findings.
550	```
551
552	Common patterns:
553
554	```markdown
555	# Execute plugin script
556	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`
557
558	# Load plugin configuration
559	@${CLAUDE_PLUGIN_ROOT}/config/settings.json
560
561	# Use plugin template
562	@${CLAUDE_PLUGIN_ROOT}/templates/report.md
563
564	# Access plugin resources
565	@${CLAUDE_PLUGIN_ROOT}/docs/reference.md
566	```
567
568	Why use it:
569	- Works across all installations
570	- Portable between systems
571	- No hardcoded paths needed
572	- Essential for multi-file plugins
573
574	### Plugin Command Organization
575
576	Plugin commands discovered automatically from `commands/` directory:
577
578	```
579	plugin-name/
580	├── commands/
581	│ ├── foo.md # /foo (plugin:plugin-name)
582	│ ├── bar.md # /bar (plugin:plugin-name)
583	│ └── utils/
584	│ └── helper.md # /helper (plugin:plugin-name:utils)
585	└── plugin.json
586	```
587
588	Namespace benefits:
589	- Logical command grouping
590	- Shown in `/help` output
591	- Avoid name conflicts
592	- Organize related commands
593
594	Naming conventions:
595	- Use descriptive action names
596	- Avoid generic names (test, run)
597	- Consider plugin-specific prefix
598	- Use hyphens for multi-word names
599
600	### Plugin Command Patterns
601
602	Configuration-based pattern:
603
604	```markdown
605	---
606	description: Deploy using plugin configuration
607	argument-hint: [environment]
608	allowed-tools: Read, Bash(*)
609	---
610
611	Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json
612
613	Deploy to $1 using configuration settings.
614	Monitor deployment and report status.
615	```
616
617	Template-based pattern:
618
619	```markdown
620	---
621	description: Generate docs from template
622	argument-hint: [component]
623	---
624
625	Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md
626
627	Generate documentation for $1 following template structure.
628	```
629
630	Multi-script pattern:
631
632	```markdown
633	---
634	description: Complete build workflow
635	allowed-tools: Bash(*)
636	---
637
638	Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
639	Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
640	Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`
641
642	Review outputs and report workflow status.
643	```
644
645	See `references/plugin-features-reference.md` for detailed patterns.
646
647	## Integration with Plugin Components
648
649	Commands can integrate with other plugin components for powerful workflows.
650
651	### Agent Integration
652
653	Launch plugin agents for complex tasks:
654
655	```markdown
656	---
657	description: Deep code review
658	argument-hint: [file-path]
659	---
660
661	Initiate comprehensive review of @$1 using the code-reviewer agent.
662
663	The agent will analyze:
664	- Code structure
665	- Security issues
666	- Performance
667	- Best practices
668
669	Agent uses plugin resources:
670	- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
671	- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md
672	```
673
674	Key points:
675	- Agent must exist in `plugin/agents/` directory
676	- Claude uses Task tool to launch agent
677	- Document agent capabilities
678	- Reference plugin resources agent uses
679
680	### Skill Integration
681
682	Leverage plugin skills for specialized knowledge:
683
684	```markdown
685	---
686	description: Document API with standards
687	argument-hint: [api-file]
688	---
689
690	Document API in @$1 following plugin standards.
691
692	Use the api-docs-standards skill to ensure:
693	- Complete endpoint documentation
694	- Consistent formatting
695	- Example quality
696	- Error documentation
697
698	Generate production-ready API docs.
699	```
700
701	Key points:
702	- Skill must exist in `plugin/skills/` directory
703	- Mention skill name to trigger invocation
704	- Document skill purpose
705	- Explain what skill provides
706
707	### Hook Coordination
708
709	Design commands that work with plugin hooks:
710	- Commands can prepare state for hooks to process
711	- Hooks execute automatically on tool events
712	- Commands should document expected hook behavior
713	- Guide Claude on interpreting hook output
714
715	See `references/plugin-features-reference.md` for examples of commands that coordinate with hooks
716
717	### Multi-Component Workflows
718
719	Combine agents, skills, and scripts:
720
721	```markdown
722	---
723	description: Comprehensive review workflow
724	argument-hint: [file]
725	allowed-tools: Bash(node:*), Read
726	---
727
728	Target: @$1
729
730	Phase 1 - Static Analysis:
731	!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
732
733	Phase 2 - Deep Review:
734	Launch code-reviewer agent for detailed analysis.
735
736	Phase 3 - Standards Check:
737	Use coding-standards skill for validation.
738
739	Phase 4 - Report:
740	Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md
741
742	Compile findings into report following template.
743	```
744
745	When to use:
746	- Complex multi-step workflows
747	- Leverage multiple plugin capabilities
748	- Require specialized analysis
749	- Need structured outputs
750
751	## Validation Patterns
752
753	Commands should validate inputs and resources before processing.
754
755	### Argument Validation
756
757	```markdown
758	---
759	description: Deploy with validation
760	argument-hint: [environment]
761	---
762
763	Validate environment: !`echo "$1" \| grep -E "^(dev\|staging\|prod)$" \|\| echo "INVALID"`
764
765	If $1 is valid environment:
766	Deploy to $1
767	Otherwise:
768	Explain valid environments: dev, staging, prod
769	Show usage: /deploy [environment]
770	```
771
772	### File Existence Checks
773
774	```markdown
775	---
776	description: Process configuration
777	argument-hint: [config-file]
778	---
779
780	Check file exists: !`test -f $1 && echo "EXISTS" \|\| echo "MISSING"`
781
782	If file exists:
783	Process configuration: @$1
784	Otherwise:
785	Explain where to place config file
786	Show expected format
787	Provide example configuration
788	```
789
790	### Plugin Resource Validation
791
792	```markdown
793	---
794	description: Run plugin analyzer
795	allowed-tools: Bash(test:*)
796	---
797
798	Validate plugin setup:
799	- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" \|\| echo "✗"`
800	- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" \|\| echo "✗"`
801
802	If all checks pass, run analysis.
803	Otherwise, report missing components.
804	```
805
806	### Error Handling
807
808	```markdown
809	---
810	description: Build with error handling
811	allowed-tools: Bash(*)
812	---
813
814	Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 \|\| echo "BUILD_FAILED"`
815
816	If build succeeded:
817	Report success and output location
818	If build failed:
819	Analyze error output
820	Suggest likely causes
821	Provide troubleshooting steps
822	```
823
824	Best practices:
825	- Validate early in command
826	- Provide helpful error messages
827	- Suggest corrective actions
828	- Handle edge cases gracefully
829
830	---
831
832	For detailed frontmatter field specifications, see `references/frontmatter-reference.md`.
833	For plugin-specific features and patterns, see `references/plugin-features-reference.md`.
834	For command pattern examples, see `examples/` directory.