## 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>