docs: comprehensive documentation improvements

Critical fixes:
- Update README.md version badge from 0.1.0 to 0.2.0
- Add 0.2.x to SECURITY.md supported versions table

Medium priority improvements:
- Change test repo command to use --private (security)
- Reword "No External Dependencies" to "Minimal Dependencies"
- Change grep to rg in SECURITY.md audit command
- Add CI checks table and version release reference to CONTRIBUTING.md
- Add cleanup instructions for test repositories

Low priority enhancements:
- Add FAQ section to README.md
- Add mermaid diagram text fallback for viewers without mermaid support
- Expand Best Practices with anti-patterns table
- Add [BANG] security pattern mention to README.md
- Add Quick Links section to CLAUDE.md
- Make Architecture Note more prominent with table format
- Add Troubleshooting section to CLAUDE.md
- Add Common Mistakes to Avoid table to CONTRIBUTING.md

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

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

Author: sjnims

CLAUDE.md

@@ -10,6 +10,33 @@ This repository is a **plugin marketplace** containing the **plugin-dev** plugin
 
 **Current Version**: v0.2.0 (see [CHANGELOG.md](CHANGELOG.md) for release history)
 
+### Quick Links
+
+| Topic | Location |
+|-------|----------|
+| Testing locally | [Testing](#testing) |
+| Version release | [Version Release Procedure](#version-release-procedure) |
+| Linting | [Linting](#linting) |
+| Component patterns | [Component Patterns](#component-patterns) |
+| Workflows | [Workflow](#workflow) |
+| CI/CD | [CI/CD](#cicd) |
+
+## ⚠️ Architecture Note (Important)
+
+**This repo has two levels of `.claude-plugin/`:**
+
+| Level | Path | Purpose |
+|-------|------|---------|
+| Root | `/.claude-plugin/marketplace.json` | Marketplace manifest listing available plugins |
+| Plugin | `/plugins/plugin-dev/.claude-plugin/plugin.json` | Individual plugin manifest |
+
+**When testing locally**, point to the plugin directory, not the root:
+
+```bash
+claude --plugin-dir plugins/plugin-dev  # ✓ Correct
+claude --plugin-dir .                    # ✗ Wrong (loads marketplace, not plugin)
+```
+
 ## Repository Structure
 
 ```
@@ -26,15 +53,6 @@ plugin-dev/                      # Marketplace root
 └── .github/workflows/           # CI/CD workflows
 ```
 
-## Architecture Note
-
-This repo has two levels of `.claude-plugin/`:
-
-- **Root level**: `/.claude-plugin/marketplace.json` - Marketplace manifest listing available plugins
-- **Plugin level**: `/plugins/plugin-dev/.claude-plugin/plugin.json` - Individual plugin manifest
-
-When testing locally, point to the plugin directory, not the root.
-
 ## Key Conventions
 
 ### Skill Structure
@@ -115,6 +133,41 @@ Utility scripts (paths relative to `plugins/plugin-dev/`):
 ./skills/plugin-settings/scripts/parse-frontmatter.sh .claude/plugin.local.md
 ```
 
+## Troubleshooting
+
+### Common Issues
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| Plugin not loading | Wrong directory path | Use `plugins/plugin-dev`, not root |
+| Skill not triggering | Weak trigger phrases | Add specific user queries to description |
+| Hook not firing | Incorrect matcher pattern | Check regex syntax, test with `test-hook.sh` |
+| Validation script fails | Missing dependencies (`jq`) | Install required tools (see [README.md](README.md#prerequisites)) |
+| Shell execution in skills | Using `!` backtick pattern | Replace with `[BANG]` placeholder |
+
+### Debug Mode
+
+Run Claude Code with debug output:
+
+```bash
+claude --debug --plugin-dir plugins/plugin-dev
+```
+
+### Validation Failures
+
+If components fail validation:
+
+1. **Run the specific validator** for the component type (see utility scripts above)
+2. **Check frontmatter** - ensure all required fields are present
+3. **Verify file location** - components must be in correct directories
+4. **Check naming** - use kebab-case for names (e.g., `my-agent`, not `myAgent`)
+
+### Getting More Help
+
+- Check [README.md FAQ](README.md#faq) for common questions
+- Review [CONTRIBUTING.md](CONTRIBUTING.md#common-mistakes-to-avoid) for common mistakes
+- Open an [issue](https://github.com/sjnims/plugin-dev/issues) if you're stuck
+
 ## Linting
 
 ```bash

CONTRIBUTING.md

@@ -120,7 +120,7 @@ gh auth status  # Should show logged in with 'repo' and 'project' scopes
 
 1. **Simplicity First**: Don't over-engineer. Keep solutions simple and focused.
 2. **Consistency**: Follow existing patterns in the codebase.
-3. **No External Dependencies**: This is a pure Claude Code plugin (only GitHub CLI dependency).
+3. **Minimal Dependencies**: This plugin only requires GitHub CLI (`gh`) as an external dependency.
 4. **Documentation**: Document all user-facing changes.
 5. **Testing**: Always test locally before submitting.
 
@@ -279,6 +279,19 @@ When creating and/or modifying hooks:
 2. **Timeout**: Set appropriate timeouts (default: 10 seconds)
 3. **Testing**: Test thoroughly to avoid false positives
 
+## Common Mistakes to Avoid
+
+| Mistake | Problem | Solution |
+|---------|---------|----------|
+| Testing in development repo | Pollutes your environment with test files | Create a separate test repository |
+| Using `!` in skill documentation | Shell execution during skill load | Use `[BANG]` placeholder (see [SECURITY.md](SECURITY.md)) |
+| Missing trigger phrases | Skills don't load when expected | Include specific user queries in descriptions |
+| Overly broad tool matchers | Hooks trigger unexpectedly | Use specific patterns like `Write\|Edit` not `*` |
+| Hardcoded paths | Plugin breaks on other machines | Use `${CLAUDE_PLUGIN_ROOT}` |
+| Large SKILL.md files | Slow loading, excessive context | Keep core <2,000 words; use `references/` for details |
+| Missing frontmatter fields | Components fail validation | Always include required fields (`name`, `description`) |
+| Committing test files | Repository bloat | Use `.gitignore` and clean up test repos |
+
 ## Testing
 
 ### Validation Scripts
@@ -321,17 +334,27 @@ For significant changes, test the complete lifecycle:
 Create a test repository to avoid polluting your development environment:
 
 ```bash
-# Create a test repo
-mkdir test-requirements-repo
-cd test-requirements-repo
+# Create a private test repo (recommended for security)
+mkdir test-plugin-repo
+cd test-plugin-repo
 git init
-gh repo create test-requirements-repo --public --source=. --remote=origin
+gh repo create test-plugin-repo --private --source=. --remote=origin
 git push -u origin main
 
 # Now test the plugin
 claude --plugin-dir /path/to/plugin-dev/plugins/plugin-dev
 ```
 
+**Cleanup**: After testing, delete the test repository:
+
+```bash
+# Delete local directory
+cd .. && rm -rf test-plugin-repo
+
+# Delete remote repository
+gh repo delete test-plugin-repo --yes
+```
+
 ## Submitting Changes
 
 ### 1. Update Documentation
@@ -388,6 +411,25 @@ See [pull_request_template.md](.github/pull_request_template.md) for the complet
 - [ ] Component-specific checks completed
 - [ ] No breaking changes (or clearly documented)
 
+### CI Checks on Pull Requests
+
+Your PR will automatically run these checks:
+
+| Workflow | What It Checks |
+|----------|----------------|
+| `markdownlint.yml` | Markdown style and formatting |
+| `links.yml` | Broken links in documentation |
+| `component-validation.yml` | Plugin component structure |
+| `version-check.yml` | Version consistency across manifests |
+| `validate-workflows.yml` | GitHub Actions syntax |
+| `claude-pr-review.yml` | AI-powered code review |
+
+All checks must pass before merging. Fix any failures before requesting review.
+
+### Version Releases
+
+Version releases are handled by maintainers. If your contribution requires a version bump, maintainers will follow the [Version Release Procedure](CLAUDE.md#version-release-procedure) in CLAUDE.md.
+
 ## Style Guide
 
 ### Markdown

README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/sjnims/plugin-dev/actions/workflows/component-validation.yml/badge.svg)](https://github.com/sjnims/plugin-dev/actions/workflows/component-validation.yml)
 [![Markdown](https://github.com/sjnims/plugin-dev/actions/workflows/markdownlint.yml/badge.svg)](https://github.com/sjnims/plugin-dev/actions/workflows/markdownlint.yml)
-[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](https://github.com/sjnims/plugin-dev/releases)
+[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](https://github.com/sjnims/plugin-dev/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 A comprehensive toolkit for developing Claude Code plugins with expert guidance on hooks, MCP integration, plugin structure, and marketplace publishing.
@@ -24,6 +24,7 @@ A comprehensive toolkit for developing Claude Code plugins with expert guidance
 - [Development Workflow](#development-workflow)
 - [Use Cases](#use-cases)
 - [Best Practices](#best-practices)
+- [FAQ](#faq)
 - [Contributing](#contributing)
 - [Getting Help](#getting-help)
 - [Attribution](#attribution)
@@ -275,6 +276,19 @@ graph TD
     E -.- E1[validation agents + scripts]
 ```
 
+<!-- Text fallback for viewers that don't render mermaid -->
+<details>
+<summary>Workflow diagram (text version)</summary>
+
+```
+Design Structure → Add Components → Integrate Services → Add Automation → Test & Validate
+       ↓                 ↓                  ↓                  ↓                ↓
+plugin-structure   command/agent/     mcp-integration    hook-development   validation
+    skill          skill skills           skill              skill         agents + scripts
+```
+
+</details>
+
 | Phase | Skill/Tool | What You Do |
 |-------|------------|-------------|
 | **Design** | plugin-structure | Define manifest, directory layout |
@@ -317,6 +331,7 @@ graph TD
 - HTTPS/WSS for MCP servers
 - Environment variables for credentials
 - Principle of least privilege
+- Use `[BANG]` placeholder in skill documentation for shell patterns (see [SECURITY.md](SECURITY.md))
 
 ### Portability
 
@@ -329,13 +344,46 @@ graph TD
 - Validate configurations before deployment
 - Test hooks with sample inputs
 - Use debug mode (`claude --debug`)
+- Create separate test repositories to avoid polluting development
 
 ### Documentation
 
 - Clear README files for each plugin
 - Document all environment variables
 - Include usage examples
 
+### What to Avoid
+
+| Anti-Pattern | Why It's Bad | Better Approach |
+|--------------|--------------|-----------------|
+| Hardcoded absolute paths | Breaks portability | Use `${CLAUDE_PLUGIN_ROOT}` |
+| Overly broad hook matchers (`*`) | Unexpected triggers, performance impact | Use specific patterns like `Write\|Edit` |
+| Large SKILL.md files (>2,000 words) | Slow loading, context bloat | Use `references/` for detailed docs |
+| Storing secrets in manifests | Security risk | Use environment variables |
+| Testing in your main dev repo | File pollution, git noise | Use dedicated test repositories |
+
+## FAQ
+
+**Q: How do I test my plugin without affecting my development environment?**
+
+Create a separate test repository and load the plugin from there. See [CONTRIBUTING.md](CONTRIBUTING.md#test-repository) for detailed instructions.
+
+**Q: My skill isn't loading when I ask trigger questions. What's wrong?**
+
+Check that your skill description includes the specific phrases users might say. The description should start with "This skill should be used when..." and include example queries like `"create a hook"`, `"add MCP server"`.
+
+**Q: What's the `[BANG]` placeholder I see in documentation?**
+
+Due to a Claude Code issue, inline bash patterns (`!` followed by backtick) can execute during skill loading. The `[BANG]` placeholder prevents this. See [SECURITY.md](SECURITY.md#shell-pattern-escaping-with-bang-placeholder) for details.
+
+**Q: How do I structure a plugin with both commands and MCP integration?**
+
+Start with `/plugin-dev:create-plugin` for a guided walkthrough, or ask: "What's the best directory structure for a plugin with commands and MCP integration?" The plugin-structure skill will guide you.
+
+**Q: Can I restrict which tools my skill or agent can use?**
+
+Yes, use the `allowed-tools` frontmatter field. For example: `allowed-tools: Read, Grep, Glob` creates a read-only skill.
+
 ## Contributing
 
 To contribute improvements:

SECURITY.md

@@ -6,6 +6,7 @@ We release patches for security vulnerabilities for the following versions:
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 0.2.x   | :white_check_mark: |
 | 0.1.x   | :white_check_mark: |
 
 ## Reporting a Vulnerability
@@ -94,7 +95,7 @@ Current branch: [BANG]`git branch --show-current`
 
 - 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\]'`
+- Audit command: `rg '!\`' plugins/plugin-dev/skills/ --glob '*.md' | rg -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