{"id":"command-development","name":"Command Development","summary":"このスキルは、ユーザーが「スラッシュコマンドを作成」「コマンドを追加」「カスタムコマンドを書く」「コマンド引数を定義する」「フロントマターコマンドを使う」「コマンドを整理する」「ファイル参照付きコマンドを作成」「インタラクティブコマンド」「コマンドでAskUserQuestionを使う」など、または...","body":"# 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.","author":"@tzachbon","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/tzachbon/smart-ralph/tree/main/.agents/skills/Command Development","license":"MIT","category":"writing","lang":"en","tokens":4172,"stars":0,"calls30d":0,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"examples/plugin-commands.md","size":13989,"sha256":"7d71d7b516020a6c171171399b40dd2cad02b842c9faa78b90e0983906c9ee94"},{"path":"examples/simple-commands.md","size":8675,"sha256":"f2533ed834305166603bcb4dd870d695af4a33b9a49d330937a4c70ed964767c"},{"path":"references/advanced-workflows.md","size":13618,"sha256":"eb258095b5a411b68377c96730effe597884a14b619cb0c1a7ab1c801d80a7d9"},{"path":"references/documentation-patterns.md","size":14971,"sha256":"70c6c9b0a9b2d46a925ada6c45808a73498a457e1d641c82cc05de8a29a33b05"},{"path":"references/frontmatter-reference.md","size":9162,"sha256":"db1ea175ca4b0bb7d11c75cb8a7d00b353ea7cf4df2027b4263e45ded4d39475"},{"path":"references/interactive-commands.md","size":20980,"sha256":"09ab1f18bfa3ff5f7088e45d5810ac20eb25ffc97fc9e8bb79416d40e0b4516b"},{"path":"references/marketplace-considerations.md","size":16437,"sha256":"ab30835431d06a8e65cd629ba0e73b3f1de5b043126c6fef7ea70163400e90f4"},{"path":"references/plugin-features-reference.md","size":14622,"sha256":"57e11ae6a4bbc1a4a295d1f036202970911d6029d64f4ab058b63a4c5a899072"},{"path":"references/testing-strategies.md","size":14803,"sha256":"e6ccf78d85c23bc58582dbc8b91731c4e412568705ed2c87ac699a1ded9adc67"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["community.example.com","docs.example.com","git-scm.com","nodejs.org","releases.example.com","stedolan.github.io"]}}