diff --git a/plugins/plugin-dev/skills/command-development/README.md b/plugins/plugin-dev/skills/command-development/README.md deleted file mode 100644 index d6c0d83..0000000 --- a/plugins/plugin-dev/skills/command-development/README.md +++ /dev/null @@ -1,272 +0,0 @@ -# Command Development Skill - -Comprehensive guidance on creating Claude Code slash commands, including file format, frontmatter options, dynamic arguments, and best practices. - -## Overview - -This skill provides knowledge about: -- Slash command file format and structure -- YAML frontmatter configuration fields -- Dynamic arguments ($ARGUMENTS, $1, $2, etc.) -- File references with @ syntax -- Bash execution with ` syntax -- Command organization and namespacing -- Best practices for command development -- Plugin-specific features (${CLAUDE_PLUGIN_ROOT}, plugin patterns) -- Integration with plugin components (agents, skills, hooks) -- Validation patterns and error handling - -## Skill Structure - -### SKILL.md (~2,470 words) - -Core skill content covering: - -**Fundamentals:** -- Command basics and locations -- File format (Markdown with optional frontmatter) -- YAML frontmatter fields overview -- Dynamic arguments ($ARGUMENTS and positional) -- File references (@ syntax) -- Bash execution (` syntax) -- Command organization patterns -- Best practices and common patterns -- Troubleshooting - -**Plugin-Specific:** -- ${CLAUDE_PLUGIN_ROOT} environment variable -- Plugin command discovery and organization -- Plugin command patterns (configuration, template, multi-script) -- Integration with plugin components (agents, skills, hooks) -- Validation patterns (argument, file, resource, error handling) - -### References - -Detailed documentation: - -- **frontmatter-reference.md**: Complete YAML frontmatter field specifications - - All field descriptions with types and defaults - - When to use each field - - Examples and best practices - - Validation and common errors - -- **plugin-features-reference.md**: Plugin-specific command features - - Plugin command discovery and organization - - ${CLAUDE_PLUGIN_ROOT} environment variable usage - - Plugin command patterns (configuration, template, multi-script) - - Integration with plugin agents, skills, and hooks - - Validation patterns and error handling - -### Examples - -Practical command examples: - -- **simple-commands.md**: 10 complete command examples - - Code review commands - - Testing commands - - Deployment commands - - Documentation generators - - Git integration commands - - Analysis and research commands - -- **plugin-commands.md**: 10 plugin-specific command examples - - Simple plugin commands with scripts - - Multi-script workflows - - Template-based generation - - Configuration-driven deployment - - Agent and skill integration - - Multi-component workflows - - Validated input commands - - Environment-aware commands - -## When This Skill Triggers - -Claude Code activates this skill when users: -- Ask to "create a slash command" or "add a command" -- Need to "write a custom command" -- Want to "define command arguments" -- Ask about "command frontmatter" or YAML configuration -- Need to "organize commands" or use namespacing -- Want to create commands with file references -- Ask about "bash execution in commands" -- Need command development best practices - -## Progressive Disclosure - -The skill uses progressive disclosure: - -1. **SKILL.md** (~2,470 words): Core concepts, common patterns, and plugin features overview -2. **References** (~13,500 words total): Detailed specifications - - frontmatter-reference.md (~1,200 words) - - plugin-features-reference.md (~1,800 words) - - interactive-commands.md (~2,500 words) - - advanced-workflows.md (~1,700 words) - - testing-strategies.md (~2,200 words) - - documentation-patterns.md (~2,000 words) - - marketplace-considerations.md (~2,200 words) -3. **Examples** (~6,000 words total): Complete working command examples - - simple-commands.md - - plugin-commands.md - -Claude loads references and examples as needed based on task. - -## Command Basics Quick Reference - -### File Format - -```markdown ---- -description: Brief description -argument-hint: [arg1] [arg2] -allowed-tools: Read, Bash(git:*) ---- - -Command prompt content with: -- Arguments: $1, $2, or $ARGUMENTS -- Files: @path/to/file -- Bash: `command here` -``` - -### Locations - -- **Project**: `.claude/commands/` (shared with team) -- **Personal**: `~/.claude/commands/` (your commands) -- **Plugin**: `plugin-name/commands/` (plugin-specific) - -### Key Features - -**Dynamic arguments:** -- `$ARGUMENTS` - All arguments as single string -- `$1`, `$2`, `$3` - Positional arguments - -**File references:** -- `@path/to/file` - Include file contents - -**Bash execution:** -- ``command`` - Execute and include output - -## Frontmatter Fields Quick Reference - -| Field | Purpose | Example | -|-------|---------|---------| -| `description` | Brief description for /help | `"Review code for issues"` | -| `allowed-tools` | Restrict tool access | `Read, Bash(git:*)` | -| `model` | Specify model | `sonnet`, `opus`, `haiku` | -| `argument-hint` | Document arguments | `[pr-number] [priority]` | -| `disable-model-invocation` | Manual-only command | `true` | - -## Common Patterns - -### Simple Review Command - -```markdown ---- -description: Review code for issues ---- - -Review this code for quality and potential bugs. -``` - -### Command with Arguments - -```markdown ---- -description: Deploy to environment -argument-hint: [environment] [version] ---- - -Deploy to $1 environment using version $2 -``` - -### Command with File Reference - -```markdown ---- -description: Document file -argument-hint: [file-path] ---- - -Generate documentation for @$1 -``` - -### Command with Bash Execution - -```markdown ---- -description: Show Git status -allowed-tools: Bash(git:*) ---- - -Current status: `git status` -Recent commits: `git log --oneline -5` -``` - -## Development Workflow - -1. **Design command:** - - Define purpose and scope - - Determine required arguments - - Identify needed tools - -2. **Create file:** - - Choose appropriate location - - Create `.md` file with command name - - Write basic prompt - -3. **Add frontmatter:** - - Start minimal (just description) - - Add fields as needed (allowed-tools, etc.) - - Document arguments with argument-hint - -4. **Test command:** - - Invoke with `/command-name` - - Verify arguments work - - Check bash execution - - Test file references - -5. **Refine:** - - Improve prompt clarity - - Handle edge cases - - Add examples in comments - - Document requirements - -## Best Practices Summary - -1. **Single responsibility**: One command, one clear purpose -2. **Clear descriptions**: Make discoverable in `/help` -3. **Document arguments**: Always use argument-hint -4. **Minimal tools**: Use most restrictive allowed-tools -5. **Test thoroughly**: Verify all features work -6. **Add comments**: Explain complex logic -7. **Handle errors**: Consider missing arguments/files - -## Status - -**Completed enhancements:** -- ✓ Plugin command patterns (${CLAUDE_PLUGIN_ROOT}, discovery, organization) -- ✓ Integration patterns (agents, skills, hooks coordination) -- ✓ Validation patterns (input, file, resource validation, error handling) - -**Remaining enhancements (in progress):** -- Advanced workflows (multi-step command sequences) -- Testing strategies (how to test commands effectively) -- Documentation patterns (command documentation best practices) -- Marketplace considerations (publishing and distribution) - -## Maintenance - -To update this skill: -1. Keep SKILL.md focused on core fundamentals -2. Move detailed specifications to references/ -3. Add new examples/ for different use cases -4. Update frontmatter when new fields added -5. Ensure imperative/infinitive form throughout -6. Test examples work with current Claude Code - -## Version History - -**v0.1.0** (2025-01-15): -- Initial release with basic command fundamentals -- Frontmatter field reference -- 10 simple command examples -- Ready for plugin-specific pattern additions diff --git a/plugins/plugin-dev/skills/command-development/SKILL.md b/plugins/plugin-dev/skills/command-development/SKILL.md index d71ce21..e229de1 100644 --- a/plugins/plugin-dev/skills/command-development/SKILL.md +++ b/plugins/plugin-dev/skills/command-development/SKILL.md @@ -334,6 +334,46 @@ Ensure: Commands 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. +### Syntax: The `!` Prefix + +In actual command files, use the `!` prefix before backticks for pre-execution: + +```markdown +Current branch: !`git branch --show-current` +Files changed: !`git diff --name-only` +Environment: !`echo $NODE_ENV` +``` + +**How it works:** + +1. Before Claude sees the command, Claude Code executes `!`command`` blocks +2. The bash output replaces the entire `!`command`` expression +3. Claude receives the expanded prompt with actual values + +**Example expansion:** + +Command file contains: + +```markdown +Review the !`git diff --name-only | wc -l | tr -d ' '` changed files on branch !`git branch --show-current`. +``` + +Claude receives (after pre-execution): + +```markdown +Review the 3 changed files on branch feature/add-auth. +``` + +### Why Skill Examples Omit `!` + +Examples in skill documentation use plain backticks without `!`: + +```markdown +Files changed: `git diff --name-only` +``` + +This is intentional. When skill content loads into Claude's context, `!`command`` would actually execute. Skill examples show the conceptual pattern; add the `!` prefix when writing actual command files. + **When to use:** - Include dynamic context (git status, environment vars, etc.) @@ -341,7 +381,7 @@ Commands can execute bash commands inline to dynamically gather context before C - Build context-aware workflows **Implementation details:** -For 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 +For advanced patterns, environment-specific configurations, and plugin integration, see `references/plugin-features-reference.md` ## Command Organization diff --git a/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md b/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md index bc9c215..d13867e 100644 --- a/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md +++ b/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md @@ -94,14 +94,15 @@ description: Analyze using plugin script allowed-tools: Bash(node:*), Read --- -Run analysis: `node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js` +Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js` Read template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md ``` **Expands to:** -``` -Run analysis: `node /path/to/plugins/plugin-name/scripts/analyze.js` + +```markdown +Run analysis: [actual output from analyze.js] Read template: @/path/to/plugins/plugin-name/templates/report.md ``` @@ -116,7 +117,7 @@ description: Run custom linter from plugin allowed-tools: Bash(node:*) --- -Lint results: `node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1` +Lint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1` Review the linting output and suggest fixes. ``` @@ -154,9 +155,9 @@ description: Complete plugin workflow allowed-tools: Bash(*), Read --- -Step 1 - Prepare: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1` +Step 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1` Step 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json -Step 3 - Execute: `${CLAUDE_PLUGIN_ROOT}/bin/execute $1` +Step 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1` Review results and report status. ``` @@ -179,7 +180,7 @@ Review results and report status. allowed-tools: Bash(test:*), Read --- - `test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "exists" || echo "missing"` + !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "exists" || echo "missing"` If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json Otherwise, use defaults... @@ -198,7 +199,7 @@ Review results and report status. 4. **Combine with arguments:** ```markdown - Run: `${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2` + Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2` ``` ### Troubleshooting @@ -234,8 +235,8 @@ Load configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json Deploy to $1 environment using: 1. Configuration settings above -2. Current git branch: `git branch --show-current` -3. Application version: `cat package.json | grep version` +2. Current git branch: !`git branch --show-current` +3. Application version: !`cat package.json | grep version` Execute deployment and monitor progress. ``` @@ -274,9 +275,9 @@ description: Complete build and test workflow allowed-tools: Bash(*) --- -Build: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` -Validate: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh` -Test: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh` +Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` +Validate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh` +Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh` Review all outputs and report: 1. Build status @@ -299,7 +300,7 @@ argument-hint: [dev|staging|prod] Environment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json -Environment check: `echo "Deploying to: $1"` +Environment check: !`echo "Deploying to: $1"` Deploy application using $1 environment configuration. Verify deployment and run smoke tests. @@ -320,7 +321,7 @@ allowed-tools: Bash(*), Read, Write Cache directory: ${CLAUDE_PLUGIN_ROOT}/cache/ Analyze @$1 and save results to cache: -`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt` +!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt` Store analysis for future reference and comparison. ``` @@ -420,7 +421,7 @@ File to review: @$1 Execute comprehensive review: 1. **Static Analysis** (via plugin scripts) - `node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1` + !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1` 2. **Deep Review** (via plugin agent) Launch the code-reviewer agent for detailed analysis. @@ -448,7 +449,7 @@ description: Deploy to environment with validation argument-hint: [environment] --- -Validate environment: `echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"` +Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"` $IF($1 in [dev, staging, prod], Deploy to $1 environment using validated configuration, @@ -471,7 +472,7 @@ description: Process configuration file argument-hint: [config-file] --- -Check file: `test -f $1 && echo "EXISTS" || echo "MISSING"` +Check file: !`test -f $1 && echo "EXISTS" || echo "MISSING"` Process configuration if file exists: @$1 @@ -491,7 +492,7 @@ description: Create deployment with version argument-hint: [environment] [version] --- -Validate inputs: `test -n "$1" -a -n "$2" && echo "OK" || echo "MISSING"` +Validate inputs: !`test -n "$1" -a -n "$2" && echo "OK" || echo "MISSING"` $IF($1 AND $2, Deploy version $2 to $1 environment, @@ -510,9 +511,9 @@ allowed-tools: Bash(test:*) --- Validate plugin setup: -- Config exists: `test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"` -- Scripts exist: `test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo "✓" || echo "✗"` -- Tools available: `test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"` +- Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"` +- Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo "✓" || echo "✗"` +- Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"` If all checks pass, proceed with analysis. Otherwise, report missing components and installation steps. @@ -528,12 +529,12 @@ description: Build and validate output allowed-tools: Bash(*) --- -Build: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` +Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` Validate output: -- Exit code: `echo $?` -- Output exists: `test -d dist && echo "✓" || echo "✗"` -- File count: `find dist -type f | wc -l` +- Exit code: !`echo $?` +- Output exists: !`test -d dist && echo "✓" || echo "✗"` +- File count: !`find dist -type f | wc -l` Report build status and any validation failures. ``` @@ -548,7 +549,7 @@ description: Process file with error handling argument-hint: [file-path] --- -Try processing: `node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo "ERROR: $?"` +Try processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo "ERROR: $?"` If processing succeeded: - Report results