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

272 lines · 7.5 KBPreview CodeRaw

1	# Command Development Skill
2
3	Comprehensive guidance on creating Claude Code slash commands, including file format, frontmatter options, dynamic arguments, and best practices.
4
5	## Overview
6
7	This skill provides knowledge about:
8	- Slash command file format and structure
9	- YAML frontmatter configuration fields
10	- Dynamic arguments ($ARGUMENTS, $1, $2, etc.)
11	- File references with @ syntax
12	- Bash execution with !` syntax
13	- Command organization and namespacing
14	- Best practices for command development
15	- Plugin-specific features (${CLAUDE_PLUGIN_ROOT}, plugin patterns)
16	- Integration with plugin components (agents, skills, hooks)
17	- Validation patterns and error handling
18
19	## Skill Structure
20
21	### SKILL.md (~2,470 words)
22
23	Core skill content covering:
24
25	Fundamentals:
26	- Command basics and locations
27	- File format (Markdown with optional frontmatter)
28	- YAML frontmatter fields overview
29	- Dynamic arguments ($ARGUMENTS and positional)
30	- File references (@ syntax)
31	- Bash execution (!` syntax)
32	- Command organization patterns
33	- Best practices and common patterns
34	- Troubleshooting
35
36	Plugin-Specific:
37	- ${CLAUDE_PLUGIN_ROOT} environment variable
38	- Plugin command discovery and organization
39	- Plugin command patterns (configuration, template, multi-script)
40	- Integration with plugin components (agents, skills, hooks)
41	- Validation patterns (argument, file, resource, error handling)
42
43	### References
44
45	Detailed documentation:
46
47	- frontmatter-reference.md: Complete YAML frontmatter field specifications
48	- All field descriptions with types and defaults
49	- When to use each field
50	- Examples and best practices
51	- Validation and common errors
52
53	- plugin-features-reference.md: Plugin-specific command features
54	- Plugin command discovery and organization
55	- ${CLAUDE_PLUGIN_ROOT} environment variable usage
56	- Plugin command patterns (configuration, template, multi-script)
57	- Integration with plugin agents, skills, and hooks
58	- Validation patterns and error handling
59
60	### Examples
61
62	Practical command examples:
63
64	- simple-commands.md: 10 complete command examples
65	- Code review commands
66	- Testing commands
67	- Deployment commands
68	- Documentation generators
69	- Git integration commands
70	- Analysis and research commands
71
72	- plugin-commands.md: 10 plugin-specific command examples
73	- Simple plugin commands with scripts
74	- Multi-script workflows
75	- Template-based generation
76	- Configuration-driven deployment
77	- Agent and skill integration
78	- Multi-component workflows
79	- Validated input commands
80	- Environment-aware commands
81
82	## When This Skill Triggers
83
84	Claude Code activates this skill when users:
85	- Ask to "create a slash command" or "add a command"
86	- Need to "write a custom command"
87	- Want to "define command arguments"
88	- Ask about "command frontmatter" or YAML configuration
89	- Need to "organize commands" or use namespacing
90	- Want to create commands with file references
91	- Ask about "bash execution in commands"
92	- Need command development best practices
93
94	## Progressive Disclosure
95
96	The skill uses progressive disclosure:
97
98	1. SKILL.md (~2,470 words): Core concepts, common patterns, and plugin features overview
99	2. References (~13,500 words total): Detailed specifications
100	- frontmatter-reference.md (~1,200 words)
101	- plugin-features-reference.md (~1,800 words)
102	- interactive-commands.md (~2,500 words)
103	- advanced-workflows.md (~1,700 words)
104	- testing-strategies.md (~2,200 words)
105	- documentation-patterns.md (~2,000 words)
106	- marketplace-considerations.md (~2,200 words)
107	3. Examples (~6,000 words total): Complete working command examples
108	- simple-commands.md
109	- plugin-commands.md
110
111	Claude loads references and examples as needed based on task.
112
113	## Command Basics Quick Reference
114
115	### File Format
116
117	```markdown
118	---
119	description: Brief description
120	argument-hint: [arg1] [arg2]
121	allowed-tools: Read, Bash(git:*)
122	---
123
124	Command prompt content with:
125	- Arguments: $1, $2, or $ARGUMENTS
126	- Files: @path/to/file
127	- Bash: !`command here`
128	```
129
130	### Locations
131
132	- Project: `.claude/commands/` (shared with team)
133	- Personal: `~/.claude/commands/` (your commands)
134	- Plugin: `plugin-name/commands/` (plugin-specific)
135
136	### Key Features
137
138	Dynamic arguments:
139	- `$ARGUMENTS` - All arguments as single string
140	- `$1`, `$2`, `$3` - Positional arguments
141
142	File references:
143	- `@path/to/file` - Include file contents
144
145	Bash execution:
146	- `!`command`` - Execute and include output
147
148	## Frontmatter Fields Quick Reference
149
150	\| Field \| Purpose \| Example \|
151	\|-------\|---------\|---------\|
152	\| `description` \| Brief description for /help \| `"Review code for issues"` \|
153	\| `allowed-tools` \| Restrict tool access \| `Read, Bash(git:*)` \|
154	\| `model` \| Specify model \| `sonnet`, `opus`, `haiku` \|
155	\| `argument-hint` \| Document arguments \| `[pr-number] [priority]` \|
156	\| `disable-model-invocation` \| Manual-only command \| `true` \|
157
158	## Common Patterns
159
160	### Simple Review Command
161
162	```markdown
163	---
164	description: Review code for issues
165	---
166
167	Review this code for quality and potential bugs.
168	```
169
170	### Command with Arguments
171
172	```markdown
173	---
174	description: Deploy to environment
175	argument-hint: [environment] [version]
176	---
177
178	Deploy to $1 environment using version $2
179	```
180
181	### Command with File Reference
182
183	```markdown
184	---
185	description: Document file
186	argument-hint: [file-path]
187	---
188
189	Generate documentation for @$1
190	```
191
192	### Command with Bash Execution
193
194	```markdown
195	---
196	description: Show Git status
197	allowed-tools: Bash(git:*)
198	---
199
200	Current status: !`git status`
201	Recent commits: !`git log --oneline -5`
202	```
203
204	## Development Workflow
205
206	1. Design command:
207	- Define purpose and scope
208	- Determine required arguments
209	- Identify needed tools
210
211	2. Create file:
212	- Choose appropriate location
213	- Create `.md` file with command name
214	- Write basic prompt
215
216	3. Add frontmatter:
217	- Start minimal (just description)
218	- Add fields as needed (allowed-tools, etc.)
219	- Document arguments with argument-hint
220
221	4. Test command:
222	- Invoke with `/command-name`
223	- Verify arguments work
224	- Check bash execution
225	- Test file references
226
227	5. Refine:
228	- Improve prompt clarity
229	- Handle edge cases
230	- Add examples in comments
231	- Document requirements
232
233	## Best Practices Summary
234
235	1. Single responsibility: One command, one clear purpose
236	2. Clear descriptions: Make discoverable in `/help`
237	3. Document arguments: Always use argument-hint
238	4. Minimal tools: Use most restrictive allowed-tools
239	5. Test thoroughly: Verify all features work
240	6. Add comments: Explain complex logic
241	7. Handle errors: Consider missing arguments/files
242
243	## Status
244
245	Completed enhancements:
246	- ✓ Plugin command patterns (${CLAUDE_PLUGIN_ROOT}, discovery, organization)
247	- ✓ Integration patterns (agents, skills, hooks coordination)
248	- ✓ Validation patterns (input, file, resource validation, error handling)
249
250	Remaining enhancements (in progress):
251	- Advanced workflows (multi-step command sequences)
252	- Testing strategies (how to test commands effectively)
253	- Documentation patterns (command documentation best practices)
254	- Marketplace considerations (publishing and distribution)
255
256	## Maintenance
257
258	To update this skill:
259	1. Keep SKILL.md focused on core fundamentals
260	2. Move detailed specifications to references/
261	3. Add new examples/ for different use cases
262	4. Update frontmatter when new fields added
263	5. Ensure imperative/infinitive form throughout
264	6. Test examples work with current Claude Code
265
266	## Version History
267
268	v0.1.0 (2025-01-15):
269	- Initial release with basic command fundamentals
270	- Frontmatter field reference
271	- 10 simple command examples
272	- Ready for plugin-specific pattern additions