1---
2name: Command Development
3description: 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.
4version: 0.2.0
5---
6 
7# Command Development for Claude Code
8 
9## Overview
10 
11Slash 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 
24A 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 
34When 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
38Review this code for security vulnerabilities including:
39- SQL injection
40- XSS attacks
41- Authentication issues
42 
43Provide specific line numbers and severity ratings.
44```
45 
46**Incorrect approach (messages to user):**
47```markdown
48This command will review your code for security issues.
49You'll receive a report with vulnerability details.
50```
51 
52The 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 
78Commands 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
89Review this code for security vulnerabilities including:
90- SQL injection
91- XSS attacks
92- Authentication bypass
93- Insecure data handling
94```
95 
96No frontmatter needed for basic commands.
97 
98### With YAML Frontmatter
99 
100Add configuration using YAML frontmatter:
101 
102```markdown
103---
104description: Review code for security issues
105allowed-tools: Read, Grep, Bash(git:*)
106model: sonnet
107---
108 
109Review 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---
122description: 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---
136allowed-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---
155model: 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---
172argument-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---
189disable-model-invocation: true
190---
191```
192 
193**Use when:** Command should only be manually invoked
194 
195## Dynamic Arguments
196 
197### Using $ARGUMENTS
198 
199Capture all arguments as single string:
200 
201```markdown
202---
203description: Fix issue by number
204argument-hint: [issue-number]
205---
206 
207Fix 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```
218Fix issue #123 following our coding standards...
219Fix issue #456 following our coding standards...
220```
221 
222### Using Positional Arguments
223 
224Capture individual arguments with `$1`, `$2`, `$3`, etc.:
225 
226```markdown
227---
228description: Review PR with priority and assignee
229argument-hint: [pr-number] [priority] [assignee]
230---
231 
232Review pull request #$1 with priority level $2.
233After review, assign to $3 for follow-up.
234```
235 
236**Usage:**
237```
238> /review-pr 123 high alice
239```
240 
241**Expands to:**
242```
243Review pull request #123 with priority level high.
244After review, assign to alice for follow-up.
245```
246 
247### Combining Arguments
248 
249Mix positional and remaining arguments:
250 
251```markdown
252Deploy $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```
262Deploy api to staging environment with options: --force --skip-tests
263```
264 
265## File References
266 
267### Using @ Syntax
268 
269Include file contents in command:
270 
271```markdown
272---
273description: Review specific file
274argument-hint: [file-path]
275---
276 
277Review @$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 
292Reference multiple files:
293 
294```markdown
295Compare @src/old-version.js with @src/new-version.js
296 
297Identify:
298- Breaking changes
299- New features
300- Bug fixes
301```
302 
303### Static File References
304 
305Reference known files without arguments:
306 
307```markdown
308Review @package.json and @tsconfig.json for consistency
309 
310Ensure:
311- TypeScript version matches
312- Dependencies are aligned
313- Build configuration is correct
314```
315 
316## Bash Execution in Commands
317 
318Commands 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:**
326For 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 
332Simple 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 
347Organize 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 
3741. **Single responsibility:** One command, one task
3752. **Clear descriptions:** Self-explanatory in `/help`
3763. **Explicit dependencies:** Use `allowed-tools` when needed
3774. **Document arguments:** Always provide `argument-hint`
3785. **Consistent naming:** Use verb-noun pattern (review-pr, fix-issue)
379 
380### Argument Handling
381 
3821. **Validate arguments:** Check for required arguments in prompt
3832. **Provide defaults:** Suggest defaults when arguments missing
3843. **Document format:** Explain expected argument format
3854. **Handle edge cases:** Consider missing or invalid arguments
386 
387```markdown
388---
389argument-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 
4001. **Explicit paths:** Use clear file paths
4012. **Check existence:** Handle missing files gracefully
4023. **Relative paths:** Use project-relative paths
4034. **Glob support:** Consider using Glob tool for patterns
404 
405### Bash Commands
406 
4071. **Limit scope:** Use `Bash(git:*)` not `Bash(*)`
4082. **Safe commands:** Avoid destructive operations
4093. **Handle errors:** Consider command failures
4104. **Keep fast:** Long-running commands slow invocation
411 
412### Documentation
413 
4141. **Add comments:** Explain complex logic
4152. **Provide examples:** Show usage in comments
4163. **List requirements:** Document dependencies
4174. **Version commands:** Note breaking changes
418 
419```markdown
420---
421description: Deploy application to environment
422argument-hint: [environment] [version]
423---
424 
425<!--
426Usage: /deploy [staging|production] [version]
427Requires: AWS credentials configured
428Example: /deploy staging v1.2.3
429-->
430 
431Deploy application to $1 environment using version $2...
432```
433 
434## Common Patterns
435 
436### Review Pattern
437 
438```markdown
439---
440description: Review code changes
441allowed-tools: Read, Bash(git:*)
442---
443 
444Files changed: !`git diff --name-only`
445 
446Review each file for:
4471. Code quality and style
4482. Potential bugs or issues
4493. Test coverage
4504. Documentation needs
451 
452Provide specific feedback for each file.
453```
454 
455### Testing Pattern
456 
457```markdown
458---
459description: Run tests for specific file
460argument-hint: [test-file]
461allowed-tools: Bash(npm:*)
462---
463 
464Run tests: !`npm test $1`
465 
466Analyze results and suggest fixes for failures.
467```
468 
469### Documentation Pattern
470 
471```markdown
472---
473description: Generate documentation for file
474argument-hint: [source-file]
475---
476 
477Generate 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---
489description: Complete PR workflow
490argument-hint: [pr-number]
491allowed-tools: Bash(gh:*), Read
492---
493 
494PR #$1 Workflow:
495 
4961. Fetch PR: !`gh pr view $1`
4972. Review changes
4983. Run checks
4994. 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 
531Plugin 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---
543description: Analyze using plugin script
544allowed-tools: Bash(node:*)
545---
546 
547Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`
548 
549Review 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 
576Plugin commands discovered automatically from `commands/` directory:
577 
578```
579plugin-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---
606description: Deploy using plugin configuration
607argument-hint: [environment]
608allowed-tools: Read, Bash(*)
609---
610 
611Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json
612 
613Deploy to $1 using configuration settings.
614Monitor deployment and report status.
615```
616 
617**Template-based pattern:**
618 
619```markdown
620---
621description: Generate docs from template
622argument-hint: [component]
623---
624 
625Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md
626 
627Generate documentation for $1 following template structure.
628```
629 
630**Multi-script pattern:**
631 
632```markdown
633---
634description: Complete build workflow
635allowed-tools: Bash(*)
636---
637 
638Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
639Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
640Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`
641 
642Review outputs and report workflow status.
643```
644 
645**See `references/plugin-features-reference.md` for detailed patterns.**
646 
647## Integration with Plugin Components
648 
649Commands can integrate with other plugin components for powerful workflows.
650 
651### Agent Integration
652 
653Launch plugin agents for complex tasks:
654 
655```markdown
656---
657description: Deep code review
658argument-hint: [file-path]
659---
660 
661Initiate comprehensive review of @$1 using the code-reviewer agent.
662 
663The agent will analyze:
664- Code structure
665- Security issues
666- Performance
667- Best practices
668 
669Agent 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 
682Leverage plugin skills for specialized knowledge:
683 
684```markdown
685---
686description: Document API with standards
687argument-hint: [api-file]
688---
689 
690Document API in @$1 following plugin standards.
691 
692Use the api-docs-standards skill to ensure:
693- Complete endpoint documentation
694- Consistent formatting
695- Example quality
696- Error documentation
697 
698Generate 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 
709Design 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 
715See `references/plugin-features-reference.md` for examples of commands that coordinate with hooks
716 
717### Multi-Component Workflows
718 
719Combine agents, skills, and scripts:
720 
721```markdown
722---
723description: Comprehensive review workflow
724argument-hint: [file]
725allowed-tools: Bash(node:*), Read
726---
727 
728Target: @$1
729 
730Phase 1 - Static Analysis:
731!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
732 
733Phase 2 - Deep Review:
734Launch code-reviewer agent for detailed analysis.
735 
736Phase 3 - Standards Check:
737Use coding-standards skill for validation.
738 
739Phase 4 - Report:
740Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md
741 
742Compile 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 
753Commands should validate inputs and resources before processing.
754 
755### Argument Validation
756 
757```markdown
758---
759description: Deploy with validation
760argument-hint: [environment]
761---
762 
763Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`
764 
765If $1 is valid environment:
766  Deploy to $1
767Otherwise:
768  Explain valid environments: dev, staging, prod
769  Show usage: /deploy [environment]
770```
771 
772### File Existence Checks
773 
774```markdown
775---
776description: Process configuration
777argument-hint: [config-file]
778---
779 
780Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`
781 
782If file exists:
783  Process configuration: @$1
784Otherwise:
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---
794description: Run plugin analyzer
795allowed-tools: Bash(test:*)
796---
797 
798Validate 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 
802If all checks pass, run analysis.
803Otherwise, report missing components.
804```
805 
806### Error Handling
807 
808```markdown
809---
810description: Build with error handling
811allowed-tools: Bash(*)
812---
813 
814Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`
815 
816If build succeeded:
817  Report success and output location
818If 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 
832For detailed frontmatter field specifications, see `references/frontmatter-reference.md`.
833For plugin-specific features and patterns, see `references/plugin-features-reference.md`.
834For command pattern examples, see `examples/` directory.
835