davila7--claude-code-templates
wehub-resource-sync
1 行
19 KiB
JSON
1 行
19 KiB
JSON
{"content": "---\nname: Command Development\ndescription: 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.\nversion: 0.2.0\n---\n\n# Command Development for Claude Code\n\n## Overview\n\nSlash 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.\n\n**Key concepts:**\n- Markdown file format for commands\n- YAML frontmatter for configuration\n- Dynamic arguments and file references\n- Bash execution for context\n- Command organization and namespacing\n\n## Command Basics\n\n### What is a Slash Command?\n\nA slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:\n- **Reusability**: Define once, use repeatedly\n- **Consistency**: Standardize common workflows\n- **Sharing**: Distribute across team or projects\n- **Efficiency**: Quick access to complex prompts\n\n### Critical: Commands are Instructions FOR Claude\n\n**Commands are written for agent consumption, not human consumption.**\n\nWhen 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.\n\n**Correct approach (instructions for Claude):**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication issues\n\nProvide specific line numbers and severity ratings.\n```\n\n**Incorrect approach (messages to user):**\n```markdown\nThis command will review your code for security issues.\nYou'll receive a report with vulnerability details.\n```\n\nThe 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.\n\n### Command Locations\n\n**Project commands** (shared with team):\n- Location: `.claude/commands/`\n- Scope: Available in specific project\n- Label: Shown as \"(project)\" in `/help`\n- Use for: Team workflows, project-specific tasks\n\n**Personal commands** (available everywhere):\n- Location: `~/.claude/commands/`\n- Scope: Available in all projects\n- Label: Shown as \"(user)\" in `/help`\n- Use for: Personal workflows, cross-project utilities\n\n**Plugin commands** (bundled with plugins):\n- Location: `plugin-name/commands/`\n- Scope: Available when plugin installed\n- Label: Shown as \"(plugin-name)\" in `/help`\n- Use for: Plugin-specific functionality\n\n## File Format\n\n### Basic Structure\n\nCommands are Markdown files with `.md` extension:\n\n```\n.claude/commands/\n├── review.md # /review command\n├── test.md # /test command\n└── deploy.md # /deploy command\n```\n\n**Simple command:**\n```markdown\nReview this code for security vulnerabilities including:\n- SQL injection\n- XSS attacks\n- Authentication bypass\n- Insecure data handling\n```\n\nNo frontmatter needed for basic commands.\n\n### With YAML Frontmatter\n\nAdd configuration using YAML frontmatter:\n\n```markdown\n---\ndescription: Review code for security issues\nallowed-tools: Read, Grep, Bash(git:*)\nmodel: sonnet\n---\n\nReview this code for security vulnerabilities...\n```\n\n## YAML Frontmatter Fields\n\n### description\n\n**Purpose:** Brief description shown in `/help`\n**Type:** String\n**Default:** First line of command prompt\n\n```yaml\n---\ndescription: Review pull request for code quality\n---\n```\n\n**Best practice:** Clear, actionable description (under 60 characters)\n\n### allowed-tools\n\n**Purpose:** Specify which tools command can use\n**Type:** String or Array\n**Default:** Inherits from conversation\n\n```yaml\n---\nallowed-tools: Read, Write, Edit, Bash(git:*)\n---\n```\n\n**Patterns:**\n- `Read, Write, Edit` - Specific tools\n- `Bash(git:*)` - Bash with git commands only\n- `*` - All tools (rarely needed)\n\n**Use when:** Command requires specific tool access\n\n### model\n\n**Purpose:** Specify model for command execution\n**Type:** String (sonnet, opus, haiku)\n**Default:** Inherits from conversation\n\n```yaml\n---\nmodel: haiku\n---\n```\n\n**Use cases:**\n- `haiku` - Fast, simple commands\n- `sonnet` - Standard workflows\n- `opus` - Complex analysis\n\n### argument-hint\n\n**Purpose:** Document expected arguments for autocomplete\n**Type:** String\n**Default:** None\n\n```yaml\n---\nargument-hint: [pr-number] [priority] [assignee]\n---\n```\n\n**Benefits:**\n- Helps users understand command arguments\n- Improves command discovery\n- Documents command interface\n\n### disable-model-invocation\n\n**Purpose:** Prevent SlashCommand tool from programmatically calling command\n**Type:** Boolean\n**Default:** false\n\n```yaml\n---\ndisable-model-invocation: true\n---\n```\n\n**Use when:** Command should only be manually invoked\n\n## Dynamic Arguments\n\n### Using $ARGUMENTS\n\nCapture all arguments as single string:\n\n```markdown\n---\ndescription: Fix issue by number\nargument-hint: [issue-number]\n---\n\nFix issue #$ARGUMENTS following our coding standards and best practices.\n```\n\n**Usage:**\n```\n> /fix-issue 123\n> /fix-issue 456\n```\n\n**Expands to:**\n```\nFix issue #123 following our coding standards...\nFix issue #456 following our coding standards...\n```\n\n### Using Positional Arguments\n\nCapture individual arguments with `$1`, `$2`, `$3`, etc.:\n\n```markdown\n---\ndescription: Review PR with priority and assignee\nargument-hint: [pr-number] [priority] [assignee]\n---\n\nReview pull request #$1 with priority level $2.\nAfter review, assign to $3 for follow-up.\n```\n\n**Usage:**\n```\n> /review-pr 123 high alice\n```\n\n**Expands to:**\n```\nReview pull request #123 with priority level high.\nAfter review, assign to alice for follow-up.\n```\n\n### Combining Arguments\n\nMix positional and remaining arguments:\n\n```markdown\nDeploy $1 to $2 environment with options: $3\n```\n\n**Usage:**\n```\n> /deploy api staging --force --skip-tests\n```\n\n**Expands to:**\n```\nDeploy api to staging environment with options: --force --skip-tests\n```\n\n## File References\n\n### Using @ Syntax\n\nInclude file contents in command:\n\n```markdown\n---\ndescription: Review specific file\nargument-hint: [file-path]\n---\n\nReview @$1 for:\n- Code quality\n- Best practices\n- Potential bugs\n```\n\n**Usage:**\n```\n> /review-file src/api/users.ts\n```\n\n**Effect:** Claude reads `src/api/users.ts` before processing command\n\n### Multiple File References\n\nReference multiple files:\n\n```markdown\nCompare @src/old-version.js with @src/new-version.js\n\nIdentify:\n- Breaking changes\n- New features\n- Bug fixes\n```\n\n### Static File References\n\nReference known files without arguments:\n\n```markdown\nReview @package.json and @tsconfig.json for consistency\n\nEnsure:\n- TypeScript version matches\n- Dependencies are aligned\n- Build configuration is correct\n```\n\n## Bash Execution in Commands\n\nCommands 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.\n\n**When to use:**\n- Include dynamic context (git status, environment vars, etc.)\n- Gather project/repository state\n- Build context-aware workflows\n\n**Implementation details:**\nFor 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\n\n## Command Organization\n\n### Flat Structure\n\nSimple organization for small command sets:\n\n```\n.claude/commands/\n├── build.md\n├── test.md\n├── deploy.md\n├── review.md\n└── docs.md\n```\n\n**Use when:** 5-15 commands, no clear categories\n\n### Namespaced Structure\n\nOrganize commands in subdirectories:\n\n```\n.claude/commands/\n├── ci/\n│ ├── build.md # /build (project:ci)\n│ ├── test.md # /test (project:ci)\n│ └── lint.md # /lint (project:ci)\n├── git/\n│ ├── commit.md # /commit (project:git)\n│ └── pr.md # /pr (project:git)\n└── docs/\n ├── generate.md # /generate (project:docs)\n └── publish.md # /publish (project:docs)\n```\n\n**Benefits:**\n- Logical grouping by category\n- Namespace shown in `/help`\n- Easier to find related commands\n\n**Use when:** 15+ commands, clear categories\n\n## Best Practices\n\n### Command Design\n\n1. **Single responsibility:** One command, one task\n2. **Clear descriptions:** Self-explanatory in `/help`\n3. **Explicit dependencies:** Use `allowed-tools` when needed\n4. **Document arguments:** Always provide `argument-hint`\n5. **Consistent naming:** Use verb-noun pattern (review-pr, fix-issue)\n\n### Argument Handling\n\n1. **Validate arguments:** Check for required arguments in prompt\n2. **Provide defaults:** Suggest defaults when arguments missing\n3. **Document format:** Explain expected argument format\n4. **Handle edge cases:** Consider missing or invalid arguments\n\n```markdown\n---\nargument-hint: [pr-number]\n---\n\n$IF($1,\n Review PR #$1,\n Please provide a PR number. Usage: /review-pr [number]\n)\n```\n\n### File References\n\n1. **Explicit paths:** Use clear file paths\n2. **Check existence:** Handle missing files gracefully\n3. **Relative paths:** Use project-relative paths\n4. **Glob support:** Consider using Glob tool for patterns\n\n### Bash Commands\n\n1. **Limit scope:** Use `Bash(git:*)` not `Bash(*)`\n2. **Safe commands:** Avoid destructive operations\n3. **Handle errors:** Consider command failures\n4. **Keep fast:** Long-running commands slow invocation\n\n### Documentation\n\n1. **Add comments:** Explain complex logic\n2. **Provide examples:** Show usage in comments\n3. **List requirements:** Document dependencies\n4. **Version commands:** Note breaking changes\n\n```markdown\n---\ndescription: Deploy application to environment\nargument-hint: [environment] [version]\n---\n\n<!--\nUsage: /deploy [staging|production] [version]\nRequires: AWS credentials configured\nExample: /deploy staging v1.2.3\n-->\n\nDeploy application to $1 environment using version $2...\n```\n\n## Common Patterns\n\n### Review Pattern\n\n```markdown\n---\ndescription: Review code changes\nallowed-tools: Read, Bash(git:*)\n---\n\nFiles changed: !`git diff --name-only`\n\nReview each file for:\n1. Code quality and style\n2. Potential bugs or issues\n3. Test coverage\n4. Documentation needs\n\nProvide specific feedback for each file.\n```\n\n### Testing Pattern\n\n```markdown\n---\ndescription: Run tests for specific file\nargument-hint: [test-file]\nallowed-tools: Bash(npm:*)\n---\n\nRun tests: !`npm test $1`\n\nAnalyze results and suggest fixes for failures.\n```\n\n### Documentation Pattern\n\n```markdown\n---\ndescription: Generate documentation for file\nargument-hint: [source-file]\n---\n\nGenerate comprehensive documentation for @$1 including:\n- Function/class descriptions\n- Parameter documentation\n- Return value descriptions\n- Usage examples\n- Edge cases and errors\n```\n\n### Workflow Pattern\n\n```markdown\n---\ndescription: Complete PR workflow\nargument-hint: [pr-number]\nallowed-tools: Bash(gh:*), Read\n---\n\nPR #$1 Workflow:\n\n1. Fetch PR: !`gh pr view $1`\n2. Review changes\n3. Run checks\n4. Approve or request changes\n```\n\n## Troubleshooting\n\n**Command not appearing:**\n- Check file is in correct directory\n- Verify `.md` extension present\n- Ensure valid Markdown format\n- Restart Claude Code\n\n**Arguments not working:**\n- Verify `$1`, `$2` syntax correct\n- Check `argument-hint` matches usage\n- Ensure no extra spaces\n\n**Bash execution failing:**\n- Check `allowed-tools` includes Bash\n- Verify command syntax in backticks\n- Test command in terminal first\n- Check for required permissions\n\n**File references not working:**\n- Verify `@` syntax correct\n- Check file path is valid\n- Ensure Read tool allowed\n- Use absolute or project-relative paths\n\n## Plugin-Specific Features\n\n### CLAUDE_PLUGIN_ROOT Variable\n\nPlugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path.\n\n**Purpose:**\n- Reference plugin files portably\n- Execute plugin scripts\n- Load plugin configuration\n- Access plugin templates\n\n**Basic usage:**\n\n```markdown\n---\ndescription: Analyze using plugin script\nallowed-tools: Bash(node:*)\n---\n\nRun analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`\n\nReview results and report findings.\n```\n\n**Common patterns:**\n\n```markdown\n# Execute plugin script\n!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`\n\n# Load plugin configuration\n@${CLAUDE_PLUGIN_ROOT}/config/settings.json\n\n# Use plugin template\n@${CLAUDE_PLUGIN_ROOT}/templates/report.md\n\n# Access plugin resources\n@${CLAUDE_PLUGIN_ROOT}/docs/reference.md\n```\n\n**Why use it:**\n- Works across all installations\n- Portable between systems\n- No hardcoded paths needed\n- Essential for multi-file plugins\n\n### Plugin Command Organization\n\nPlugin commands discovered automatically from `commands/` directory:\n\n```\nplugin-name/\n├── commands/\n│ ├── foo.md # /foo (plugin:plugin-name)\n│ ├── bar.md # /bar (plugin:plugin-name)\n│ └── utils/\n│ └── helper.md # /helper (plugin:plugin-name:utils)\n└── plugin.json\n```\n\n**Namespace benefits:**\n- Logical command grouping\n- Shown in `/help` output\n- Avoid name conflicts\n- Organize related commands\n\n**Naming conventions:**\n- Use descriptive action names\n- Avoid generic names (test, run)\n- Consider plugin-specific prefix\n- Use hyphens for multi-word names\n\n### Plugin Command Patterns\n\n**Configuration-based pattern:**\n\n```markdown\n---\ndescription: Deploy using plugin configuration\nargument-hint: [environment]\nallowed-tools: Read, Bash(*)\n---\n\nLoad configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json\n\nDeploy to $1 using configuration settings.\nMonitor deployment and report status.\n```\n\n**Template-based pattern:**\n\n```markdown\n---\ndescription: Generate docs from template\nargument-hint: [component]\n---\n\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md\n\nGenerate documentation for $1 following template structure.\n```\n\n**Multi-script pattern:**\n\n```markdown\n---\ndescription: Complete build workflow\nallowed-tools: Bash(*)\n---\n\nBuild: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`\nTest: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`\nPackage: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`\n\nReview outputs and report workflow status.\n```\n\n**See `references/plugin-features-reference.md` for detailed patterns.**\n\n## Integration with Plugin Components\n\nCommands can integrate with other plugin components for powerful workflows.\n\n### Agent Integration\n\nLaunch plugin agents for complex tasks:\n\n```markdown\n---\ndescription: Deep code review\nargument-hint: [file-path]\n---\n\nInitiate comprehensive review of @$1 using the code-reviewer agent.\n\nThe agent will analyze:\n- Code structure\n- Security issues\n- Performance\n- Best practices\n\nAgent uses plugin resources:\n- ${CLAUDE_PLUGIN_ROOT}/config/rules.json\n- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md\n```\n\n**Key points:**\n- Agent must exist in `plugin/agents/` directory\n- Claude uses Task tool to launch agent\n- Document agent capabilities\n- Reference plugin resources agent uses\n\n### Skill Integration\n\nLeverage plugin skills for specialized knowledge:\n\n```markdown\n---\ndescription: Document API with standards\nargument-hint: [api-file]\n---\n\nDocument API in @$1 following plugin standards.\n\nUse the api-docs-standards skill to ensure:\n- Complete endpoint documentation\n- Consistent formatting\n- Example quality\n- Error documentation\n\nGenerate production-ready API docs.\n```\n\n**Key points:**\n- Skill must exist in `plugin/skills/` directory\n- Mention skill name to trigger invocation\n- Document skill purpose\n- Explain what skill provides\n\n### Hook Coordination\n\nDesign commands that work with plugin hooks:\n- Commands can prepare state for hooks to process\n- Hooks execute automatically on tool events\n- Commands should document expected hook behavior\n- Guide Claude on interpreting hook output\n\nSee `references/plugin-features-reference.md` for examples of commands that coordinate with hooks\n\n### Multi-Component Workflows\n\nCombine agents, skills, and scripts:\n\n```markdown\n---\ndescription: Comprehensive review workflow\nargument-hint: [file]\nallowed-tools: Bash(node:*), Read\n---\n\nTarget: @$1\n\nPhase 1 - Static Analysis:\n!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`\n\nPhase 2 - Deep Review:\nLaunch code-reviewer agent for detailed analysis.\n\nPhase 3 - Standards Check:\nUse coding-standards skill for validation.\n\nPhase 4 - Report:\nTemplate: @${CLAUDE_PLUGIN_ROOT}/templates/review.md\n\nCompile findings into report following template.\n```\n\n**When to use:**\n- Complex multi-step workflows\n- Leverage multiple plugin capabilities\n- Require specialized analysis\n- Need structured outputs\n\n## Validation Patterns\n\nCommands should validate inputs and resources before processing.\n\n### Argument Validation\n\n```markdown\n---\ndescription: Deploy with validation\nargument-hint: [environment]\n---\n\nValidate environment: !`echo \"$1\" | grep -E \"^(dev|staging|prod)$\" || echo \"INVALID\"`\n\nIf $1 is valid environment:\n Deploy to $1\nOtherwise:\n Explain valid environments: dev, staging, prod\n Show usage: /deploy [environment]\n```\n\n### File Existence Checks\n\n```markdown\n---\ndescription: Process configuration\nargument-hint: [config-file]\n---\n\nCheck file exists: !`test -f $1 && echo \"EXISTS\" || echo \"MISSING\"`\n\nIf file exists:\n Process configuration: @$1\nOtherwise:\n Explain where to place config file\n Show expected format\n Provide example configuration\n```\n\n### Plugin Resource Validation\n\n```markdown\n---\ndescription: Run plugin analyzer\nallowed-tools: Bash(test:*)\n---\n\nValidate plugin setup:\n- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo \"✓\" || echo \"✗\"`\n- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo \"✓\" || echo \"✗\"`\n\nIf all checks pass, run analysis.\nOtherwise, report missing components.\n```\n\n### Error Handling\n\n```markdown\n---\ndescription: Build with error handling\nallowed-tools: Bash(*)\n---\n\nExecute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo \"BUILD_FAILED\"`\n\nIf build succeeded:\n Report success and output location\nIf build failed:\n Analyze error output\n Suggest likely causes\n Provide troubleshooting steps\n```\n\n**Best practices:**\n- Validate early in command\n- Provide helpful error messages\n- Suggest corrective actions\n- Handle edge cases gracefully\n\n---\n\nFor detailed frontmatter field specifications, see `references/frontmatter-reference.md`.\nFor plugin-specific features and patterns, see `references/plugin-features-reference.md`.\nFor command pattern examples, see `examples/` directory.\n"} |