docs: document [BANG] security workaround for Claude Code #12781 (#156)

## Description

Document the `[BANG]` placeholder security workaround used in skill
documentation to prevent unintended shell execution during skill
loading.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [x] Documentation update (improvements to README, CLAUDE.md, or
component docs)
- [ ] Refactoring (code change that neither fixes a bug nor adds a
feature)
- [ ] Configuration change (changes to .markdownlint.json, plugin.json,
etc.)

## Component(s) Affected

- [ ] Commands (`/plugin-dev:*`)
- [x] Skills (methodology and best practices)
- [ ] Agents (requirements-assistant)
- [ ] Hooks (UserPromptSubmit)
- [x] Documentation (README.md, CLAUDE.md, SECURITY.md)
- [ ] Configuration (.markdownlint.json, plugin.json, marketplace.json)
- [ ] Issue/PR templates
- [ ] Other (please specify):

## Motivation and Context

The plugin uses a `[BANG]` placeholder to prevent [Claude Code issue
#12781](anthropics/claude-code#12781) where
inline bash patterns in fenced code blocks can execute during skill
loading. This workaround was implemented in PR #142 but never
documented, risking future maintainers accidentally reverting it.

Fixes #151

## Solution

Added comprehensive documentation explaining:
- What the vulnerability is
- Why `[BANG]` is used instead of `!`
- How to audit for unescaped patterns
- Reference to the original fix (PR #142)

### Changes

- **SECURITY.md**: Added "Known Security Mitigations" section with full
explanation, audit command, and maintainer guidance
- **CONTRIBUTING.md**: Added "Shell Pattern Escaping" subsection to
Markdown Style guidelines
- **testing-strategies.md**: Fixed unescaped `!`` pattern using hex
escape (`\x60`) to avoid triggering the bug

### Alternatives Considered

1. **Just add a comment in CHANGELOG**: Insufficient - future
maintainers may not read changelog
2. **Add CI check**: Good idea but out of scope - could be follow-up
work

## How Has This Been Tested?

**Test Configuration**:
- Claude Code version: Latest
- GitHub CLI version: 2.x
- OS: macOS

**Test Steps**:
1. Verified no unescaped patterns remain: `grep -rn '!`'
plugins/plugin-dev/skills/ --include='*.md' | grep -v '\[BANG\]' | grep
-v '\\x60'`
2. Ran markdownlint on all modified files - passes
3. Verified links in SECURITY.md point to correct anchors

## Checklist

### General

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
(if applicable)
- [x] My changes generate no new warnings or errors

### Documentation

- [x] I have updated the documentation accordingly (README.md,
CLAUDE.md, or component docs)
- [ ] I have updated YAML frontmatter (if applicable)
- [x] I have verified all links work correctly

### Markdown

- [x] I have run `markdownlint` and fixed all issues
- [x] My markdown follows the repository style (ATX headers, dash lists,
fenced code blocks)
- [ ] I have verified special HTML elements are properly closed
(`<example>`, `<commentary>`, etc.)

### Testing

- [x] I have tested the plugin locally with `cc --plugin-dir
plugins/plugin-dev`
- [ ] I have tested the full workflow (if applicable)
- [ ] I have verified GitHub CLI integration works (if applicable)
- [ ] I have tested in a clean repository (not my development repo)

### Version Management (if applicable)

- [ ] I have updated version numbers in both `plugin.json` and
`marketplace.json` (if this is a release)
- [ ] I have updated CHANGELOG.md with relevant changes

## Reviewer Notes

**Areas that need special attention**:
- Verify the hex escape `\x60` in testing-strategies.md works correctly
- Confirm SECURITY.md anchor link works from CONTRIBUTING.md

**Known limitations or trade-offs**:
- Does not add CI check to prevent reintroduction (could be follow-up
issue)

---

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

Co-authored-by: Claude <noreply@anthropic.com>

Author: sjnims

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:*`)

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_

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