From 275ae6c2ef1b680e0a724c09bbc6052b4b6b325f Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 13 Dec 2025 08:40:00 -0500
Subject: [PATCH] docs: document [BANG] security workaround for Claude Code
 #12781
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation explaining why the [BANG] placeholder is used in skill
documentation to prevent unintended shell execution during skill loading.

Changes:
- SECURITY.md: Add "Known Security Mitigations" section with full explanation
- CONTRIBUTING.md: Add "Shell Pattern Escaping" subsection to Markdown Style
- testing-strategies.md: Fix unescaped pattern using hex escape (\x60)

This ensures future maintainers understand the workaround and don't
accidentally revert it.

Fixes #151

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CONTRIBUTING.md                               | 17 +++++++++++
 SECURITY.md                                   | 30 ++++++++++++++++++-
 .../references/testing-strategies.md          |  5 ++--
 3 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6a53b6d..43c50d8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -150,6 +150,23 @@ markdownlint '**/*.md' --ignore node_modules --fix
 - No line length limits
 - Allowed HTML: `<p>`, `<img>`, `<example>`, `<commentary>`
 
+### Shell Pattern Escaping
+
+When documenting bash execution patterns in skill files, use `[BANG]` instead of `!` to prevent unintended execution during skill loading ([Claude Code #12781](https://github.com/anthropics/claude-code/issues/12781)).
+
+```markdown
+<!-- In skill documentation (SKILL.md, references/, examples/) -->
+Current branch: [BANG]`git branch --show-current`
+
+<!-- The [BANG] placeholder prevents execution while loading -->
+```
+
+**Important**:
+
+- This applies to skill files that get loaded into context
+- Command files (`.claude/commands/*.md`) use actual `!` syntax
+- See [SECURITY.md](SECURITY.md#shell-pattern-escaping-with-bang-placeholder) for full details
+
 ## Component-Specific Guidelines
 
 ### Commands (`/plugin-dev:*`)
diff --git a/SECURITY.md b/SECURITY.md
index 8e62b0b..e97a632 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -72,6 +72,34 @@ When a security vulnerability is confirmed:
 4. **Markdown Linting**: Run `markdownlint` before committing to catch potential issues
 5. **Test Locally**: Always test with `cc --plugin-dir plugins/plugin-dev` before pushing
 
+## Known Security Mitigations
+
+### Shell Pattern Escaping with [BANG] Placeholder
+
+**Issue**: [Claude Code #12781](https://github.com/anthropics/claude-code/issues/12781)
+
+Due to a Claude Code issue, inline bash execution patterns (exclamation mark followed by backtick) inside fenced code blocks can be executed when skills are loaded—even when they appear as documentation examples.
+
+**Mitigation**: This plugin uses a `[BANG]` placeholder instead of `!` in skill documentation that shows bash execution patterns.
+
+```markdown
+<!-- UNSAFE - may execute during skill load -->
+Current branch: !`git branch --show-current`
+
+<!-- SAFE - displays as documentation only -->
+Current branch: [BANG]`git branch --show-current`
+```
+
+**For maintainers**:
+
+- Do NOT "fix" `[BANG]` back to `!` - this is intentional
+- When adding new documentation with bash patterns, use `[BANG]`
+- Audit command: `grep -rn '!`' plugins/plugin-dev/skills/ --include='*.md' | grep -v '\[BANG\]'`
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for documentation guidelines
+- Reference: [command-development skill](plugins/plugin-dev/skills/command-development/SKILL.md) lines 340-378
+
+**History**: Fixed in PR #142 (v0.2.0)
+
 ## Scope
 
 This security policy applies to:
@@ -125,4 +153,4 @@ _No security issues have been reported yet._
 
 ---
 
-**Note:** _This security policy was last updated: December 7, 2025_
+**Note:** _This security policy was last updated: December 13, 2025_
diff --git a/plugins/plugin-dev/skills/command-development/references/testing-strategies.md b/plugins/plugin-dev/skills/command-development/references/testing-strategies.md
index 422fb62..912de8c 100644
--- a/plugins/plugin-dev/skills/command-development/references/testing-strategies.md
+++ b/plugins/plugin-dev/skills/command-development/references/testing-strategies.md
@@ -676,8 +676,9 @@ echo "Test: \$1 and \$2" > .claude/commands/test-args.md
 # Check allowed-tools
 grep "allowed-tools" .claude/commands/my-command.md
 
-# Verify command syntax
-grep '!`' .claude/commands/my-command.md
+# Verify command has bash execution syntax (! followed by backtick)
+# Note: Command files use actual ! syntax, not [BANG] placeholder
+grep -E '!\x60' .claude/commands/my-command.md
 
 # Test command manually
 date