1# Command Development Skill
2 
3Comprehensive guidance on creating Claude Code slash commands, including file format, frontmatter options, dynamic arguments, and best practices.
4 
5## Overview
6 
7This 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 
23Core 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 
45Detailed 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 
62Practical 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 
84Claude 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 
96The skill uses progressive disclosure:
97 
981. **SKILL.md** (~2,470 words): Core concepts, common patterns, and plugin features overview
992. **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)
1073. **Examples** (~6,000 words total): Complete working command examples
108   - simple-commands.md
109   - plugin-commands.md
110 
111Claude loads references and examples as needed based on task.
112 
113## Command Basics Quick Reference
114 
115### File Format
116 
117```markdown
118---
119description: Brief description
120argument-hint: [arg1] [arg2]
121allowed-tools: Read, Bash(git:*)
122---
123 
124Command 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---
164description: Review code for issues
165---
166 
167Review this code for quality and potential bugs.
168```
169 
170### Command with Arguments
171 
172```markdown
173---
174description: Deploy to environment
175argument-hint: [environment] [version]
176---
177 
178Deploy to $1 environment using version $2
179```
180 
181### Command with File Reference
182 
183```markdown
184---
185description: Document file
186argument-hint: [file-path]
187---
188 
189Generate documentation for @$1
190```
191 
192### Command with Bash Execution
193 
194```markdown
195---
196description: Show Git status
197allowed-tools: Bash(git:*)
198---
199 
200Current status: !`git status`
201Recent commits: !`git log --oneline -5`
202```
203 
204## Development Workflow
205 
2061. **Design command:**
207   - Define purpose and scope
208   - Determine required arguments
209   - Identify needed tools
210 
2112. **Create file:**
212   - Choose appropriate location
213   - Create `.md` file with command name
214   - Write basic prompt
215 
2163. **Add frontmatter:**
217   - Start minimal (just description)
218   - Add fields as needed (allowed-tools, etc.)
219   - Document arguments with argument-hint
220 
2214. **Test command:**
222   - Invoke with `/command-name`
223   - Verify arguments work
224   - Check bash execution
225   - Test file references
226 
2275. **Refine:**
228   - Improve prompt clarity
229   - Handle edge cases
230   - Add examples in comments
231   - Document requirements
232 
233## Best Practices Summary
234 
2351. **Single responsibility**: One command, one clear purpose
2362. **Clear descriptions**: Make discoverable in `/help`
2373. **Document arguments**: Always use argument-hint
2384. **Minimal tools**: Use most restrictive allowed-tools
2395. **Test thoroughly**: Verify all features work
2406. **Add comments**: Explain complex logic
2417. **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 
258To update this skill:
2591. Keep SKILL.md focused on core fundamentals
2602. Move detailed specifications to references/
2613. Add new examples/ for different use cases
2624. Update frontmatter when new fields added
2635. Ensure imperative/infinitive form throughout
2646. 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
273