docs(command-development): document bash ! prefix for pre-execution syntax

Document the `!`command`` syntax required for bash pre-execution in
actual command files:

- Add "Syntax: The `!` Prefix" section explaining how pre-execution
  works
- Document that `!`command`` executes before Claude sees the prompt
- Explain why skill examples omit `!` (would execute when loaded)
- Update reference file examples to use `!` prefix consistently

Users copying examples from the reference file into actual command
files will now have the correct syntax.

Fixes #46

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: sjnims

plugins/plugin-dev/skills/command-development/SKILL.md

@@ -334,14 +334,54 @@ 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.)
 - Gather project/repository state
 - 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
 

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