docs: address 20 documentation gaps from claude-docs audit (#203)

## Summary

Comprehensive audit of the official Claude Code documentation
(`claude-docs`) against plugin-dev skills identified 20 gaps — topics
relevant to plugin developers that were missing or insufficiently
covered. This PR addresses all of them.

- **5 new reference files** (~5,400 words total)
- **9 modified files** (~1,400 lines added)
- **6 SKILL.md description updates** with new trigger phrases
- **0 markdownlint errors**, all files prettier-formatted

### Phase 1: Inline additions to existing skills (gaps 1–8)

- **skill-development**: `model` field, scoped `hooks` in frontmatter,
visibility budget (`SLASH_COMMAND_TOOL_CHAR_BUDGET`)
- **hook-development**: Scoped hooks in skill/agent frontmatter, `agent`
hook type
- **agent-development**: `disallowedTools` field (denylist complement to
`tools`)
- **mcp-integration**: MCP prompts as commands (`/mcp__server__prompt`),
tool search auto-enable behavior
- **command-development**: Load-time injection vs runtime execution
clarification

### Phase 2: New reference docs for cross-cutting topics (gaps 9–11)

- `plugin-structure/references/headless-ci-mode.md` — Plugin behavior in
`claude -p` and CI pipelines
- `plugin-structure/references/github-actions.md` — Integration with
`claude-code-action@v1`
- `plugin-settings/references/memory-rules-system.md` — CLAUDE.md
imports, `.claude/rules/`, priority hierarchy

### Phase 3: Consolidated lower-priority gaps (gaps 12–20)

- `plugin-structure/references/advanced-topics.md` — Keybindings plugin
context, status line integration, Claude as MCP server, `@` resource
syntax, agent hook type details, auto-update behavior, plugin caching,
CLI management commands, installation scopes

### Phase 4: Description trigger phrase updates

All 6 modified SKILL.md files have updated `description` frontmatter
with trigger phrases for the new content.

## Test plan

- [x] `markdownlint-cli2 '**/*.md'` — 87 files, 0 errors
- [x] `prettier --check '**/*.md'` — all files formatted
- [x] `rg '!\x60' plugins/plugin-dev/skills/ --glob '*.md'` — no literal
`!` backtick violations
- [x] All SKILL.md files under 3,000 words (range: 1,701–2,508)
- [x] All 5 new reference files exist and are referenced from parent
SKILL.md
- [ ] CI passes
- [ ] Verify plugin loads: `claude --plugin-dir plugins/plugin-dev`

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

---------

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

Author: sjnims

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

@@ -1,6 +1,6 @@
 ---
 name: agent-development
-description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
+description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", "disallowedTools", "block tools", "agent denylist", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
 ---
 
 # Agent Development for Claude Code Plugins
@@ -251,6 +251,27 @@ tools: Read, Write, Grep, Bash
 
 > **Important:** Agents use `tools` while Skills use `allowed-tools`. The field names differ between component types. For skill tool restrictions, see the `skill-development` skill.
 
+### disallowedTools (optional)
+
+Denylist complement to `tools`. Block specific tools while allowing all others:
+
+```yaml
+disallowedTools: Bash, Write
+```
+
+**Format:** Comma-separated tool names
+
+**Default:** No tools blocked
+
+| Field             | Approach  | Use When                                |
+| ----------------- | --------- | --------------------------------------- |
+| `tools`           | Allowlist | Few tools needed, restrict to minimum   |
+| `disallowedTools` | Denylist  | Most tools needed, block specific risks |
+
+**Best practice:** Prefer `tools` (allowlist) for tighter security. Use `disallowedTools` when an agent needs broad access but specific tools are dangerous.
+
+> **Note:** Use one or the other. If both are specified, behavior is undefined.
+
 ### skills (optional)
 
 Load specific skills into the agent's context:
@@ -470,15 +491,16 @@ Ensure system prompt is complete:
 
 ### Frontmatter Fields Summary
 
-| Field          | Required | Format                     | Example                  |
-| -------------- | -------- | -------------------------- | ------------------------ |
-| name           | Yes      | lowercase-hyphens          | code-reviewer            |
-| description    | Yes      | Text + examples            | Use when... <example>... |
-| model          | Yes      | inherit/sonnet/opus/haiku  | inherit                  |
-| color          | Yes      | Color name                 | blue                     |
-| tools          | No       | Comma-separated tool names | Read, Grep               |
-| skills         | No       | Array of skill names       | [testing, security]      |
-| permissionMode | No       | Permission mode string     | acceptEdits              |
+| Field           | Required | Format                     | Example                  |
+| --------------- | -------- | -------------------------- | ------------------------ |
+| name            | Yes      | lowercase-hyphens          | code-reviewer            |
+| description     | Yes      | Text + examples            | Use when... <example>... |
+| model           | Yes      | inherit/sonnet/opus/haiku  | inherit                  |
+| color           | Yes      | Color name                 | blue                     |
+| tools           | No       | Comma-separated tool names | Read, Grep               |
+| disallowedTools | No       | Comma-separated tool names | Bash, Write              |
+| skills          | No       | Array of skill names       | [testing, security]      |
+| permissionMode  | No       | Permission mode string     | acceptEdits              |
 
 > **Note:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. The field names differ between component types.
 

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

@@ -406,6 +406,10 @@ This is intentional. When skill content loads into Claude's context, `[BANG]` fo
 - Gather project/repository state
 - Build context-aware workflows
 
+### Load-Time Injection vs Runtime Execution
+
+The `[BANG]` syntax performs **load-time context injection**: commands execute when the skill or command is loaded, and their output becomes static text in the prompt Claude receives. This is different from Claude choosing to run commands at runtime via the Bash tool. Use `[BANG]` for gathering context (git status, environment variables, config files) that informs Claude's starting state, not for actions Claude should perform during the task.
+
 **Implementation details:**
 For advanced patterns, environment-specific configurations, and plugin integration, see `references/plugin-features-reference.md`
 

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

@@ -1,6 +1,6 @@
 ---
 name: hook-development
-description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SubagentStart, Setup, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
+description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", "scoped hooks", "frontmatter hooks", "hook in skill", "hook in agent", "agent hook type", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SubagentStart, Setup, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
 ---
 
 # Hook Development for Claude Code Plugins
@@ -59,6 +59,22 @@ Execute bash commands for deterministic checks:
 - External tool integrations
 - Performance-critical checks
 
+### Agent Hooks
+
+Use an LLM agent for complex, multi-step verification that requires tool access:
+
+```json
+{
+  "type": "agent",
+  "prompt": "Verify all generated code has tests and passes linting",
+  "timeout": 120
+}
+```
+
+**Supported events:** Stop, SubagentStop
+
+Agent hooks spawn a subagent that can use tools (Read, Bash, etc.) for thorough verification — useful when prompt hooks lack sufficient context or tool access. See `references/advanced.md` for patterns.
+
 ## Hook Configuration Formats
 
 ### Plugin hooks.json Format
@@ -507,6 +523,29 @@ In plugins, define hooks in `hooks/hooks.json` using the **plugin wrapper format
 
 **Note:** Plugin hooks use the `{"hooks": {...}}` wrapper format, not the direct settings format. Plugin hooks merge with user's hooks and run in parallel.
 
+## Scoped Hooks in Skill/Agent Frontmatter
+
+Beyond `hooks.json` (global) and settings (user-level), hooks can be defined directly in skill or agent YAML frontmatter. Scoped hooks activate only when that component is in use:
+
+```yaml
+---
+name: validated-writer
+description: Write files with safety checks...
+hooks:
+  PreToolUse:
+    - matcher: Write
+      hooks:
+        - type: command
+          command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh"
+---
+```
+
+**Supported events in frontmatter:** `PreToolUse`, `PostToolUse`, `Stop`
+
+Scoped hooks use the same event/matcher/hook structure but are lifecycle-bound — they activate when the skill loads and deactivate when it completes. This is ideal for skill-specific validation without affecting other workflows.
+
+See `references/advanced.md` for detailed syntax and comparison with `hooks.json`.
+
 ## Matchers
 
 ### Tool Name Matching

plugins/plugin-dev/skills/hook-development/references/advanced.md

@@ -481,6 +481,146 @@ if [ ! -f "$file_path" ]; then
 fi
 ```
 
+## Scoped Hooks in Skill/Agent Frontmatter
+
+Hooks can be defined directly in skill or agent YAML frontmatter, scoping them to activate only when that component is in use.
+
+### Concept
+
+Unlike `hooks.json` (global, always active when plugin enabled) or settings hooks (user-level), scoped hooks are lifecycle-bound to a specific skill or agent. They activate when the component loads and deactivate when it completes.
+
+### Format
+
+The `hooks` field in frontmatter uses the same event/matcher/hook structure as `hooks.json`:
+
+```yaml
+---
+name: secure-writer
+description: Write files with safety validation...
+hooks:
+  PreToolUse:
+    - matcher: Write
+      hooks:
+        - type: command
+          command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh"
+          timeout: 10
+  PostToolUse:
+    - matcher: Write
+      hooks:
+        - type: command
+          command: "${CLAUDE_PLUGIN_ROOT}/scripts/post-write-check.sh"
+---
+```
+
+### Supported Events
+
+Only a subset of hook events apply in frontmatter scope:
+
+| Event         | Purpose in Frontmatter                                                                             |
+| ------------- | -------------------------------------------------------------------------------------------------- |
+| `PreToolUse`  | Validate or block tool calls during skill execution                                                |
+| `PostToolUse` | Run checks after tool execution during skill use                                                   |
+| `Stop`        | Verify completion criteria before skill/agent finishes (auto-converted to SubagentStop for agents) |
+
+Session-level events (`SessionStart`, `UserPromptSubmit`, `Notification`, etc.) don't apply — they operate at a different lifecycle scope.
+
+### Comparison with hooks.json
+
+| Aspect         | `hooks.json`                               | Frontmatter `hooks`                                 |
+| -------------- | ------------------------------------------ | --------------------------------------------------- |
+| Scope          | Global (always active when plugin enabled) | Component-specific (active only during use)         |
+| Events         | All 11+ hook events                        | PreToolUse, PostToolUse, Stop                       |
+| Location       | `hooks/hooks.json` file                    | YAML frontmatter in SKILL.md or agent .md           |
+| Merge behavior | Merges with user/project hooks             | Merges with global hooks during component lifecycle |
+
+### Use Cases
+
+- **Skill-specific validation:** A "database writer" skill that validates SQL before execution
+- **Restricted workflows:** A "deploy" skill that checks branch and test status before allowing Bash commands
+- **Quality gates:** A "code generator" skill that runs linting after every Write operation
+- **Agent safety:** An autonomous agent that validates all Bash commands before execution
+
+### Both Hook Types Work
+
+**Command hook** (deterministic script execution):
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-safety.sh"
+```
+
+**Prompt hook** (LLM evaluation):
+
+```yaml
+hooks:
+  Stop:
+    - hooks:
+        - type: prompt
+          prompt: 'Verify all generated code has tests. Return {"decision": "stop"} if satisfied or {"decision": "continue", "reason": "missing tests"} if not.'
+```
+
+## Agent Hook Type
+
+The `agent` hook type spawns a subagent for complex, multi-step verification workflows that require tool access.
+
+### Concept
+
+While `command` hooks execute bash scripts and `prompt` hooks evaluate a single LLM prompt, `agent` hooks create a full subagent that can use tools (Read, Bash, Grep, etc.) to perform thorough verification. This is the most powerful but most expensive hook type.
+
+### Configuration
+
+```json
+{
+  "type": "agent",
+  "prompt": "Verify that all generated code has tests and passes linting. Check each modified file.",
+  "timeout": 120
+}
+```
+
+### Supported Events
+
+Agent hooks are supported on **Stop** and **SubagentStop** events only. They aren't suitable for PreToolUse (too slow) or session-level events.
+
+### When to Use Agent Hooks
+
+| Hook Type | Speed           | Capability            | Best For                                      |
+| --------- | --------------- | --------------------- | --------------------------------------------- |
+| `command` | Fast (~1-5s)    | Bash scripts only     | Deterministic checks, file validation         |
+| `prompt`  | Medium (~5-15s) | Single LLM evaluation | Context-aware decisions, flexible logic       |
+| `agent`   | Slow (~30-120s) | Multi-step with tools | Comprehensive verification, multi-file checks |
+
+Use agent hooks when:
+
+- Verification requires reading multiple files
+- You need to run commands and analyze their output
+- Single-prompt evaluation is insufficient
+- Completion criteria are complex and multi-faceted
+
+### Example: Comprehensive Completion Check
+
+```json
+{
+  "Stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "agent",
+          "prompt": "Before approving task completion, verify: 1) All modified files have corresponding tests, 2) Tests pass (run them), 3) No linting errors exist. Report findings and return approve/block decision.",
+          "timeout": 120
+        }
+      ]
+    }
+  ]
+}
+```
+
+The agent will autonomously read files, run tests, check linting, and make a comprehensive decision about whether to allow the main agent to stop.
+
 ## Conclusion
 
 Advanced hook patterns enable sophisticated automation while maintaining reliability and performance. Use these techniques when basic hooks are insufficient, but always prioritize simplicity and maintainability.

plugins/plugin-dev/skills/mcp-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcp-integration
-description: This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", discusses MCP server types (SSE, stdio, HTTP, WebSocket), or asks to "find MCP server", "discover MCP servers", "what MCP servers exist", "recommend MCP server for [service]". Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
+description: This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", discusses MCP server types (SSE, stdio, HTTP, WebSocket), or asks to "find MCP server", "discover MCP servers", "what MCP servers exist", "recommend MCP server for [service]", "MCP prompts", "MCP prompts as commands", "tool search", "tool search threshold". Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
 ---
 
 # MCP Integration for Claude Code Plugins
@@ -261,6 +261,21 @@ Claude will fetch the resource content and include it in context.
 - **https://** - HTTP resources
 - **Custom protocols** - Server-specific (postgres://, s3://, etc.)
 
+## MCP Prompts as Commands
+
+MCP servers can expose **prompts** that appear as slash commands in Claude Code:
+
+**Format:** `/mcp__servername__promptname`
+
+**Example:**
+
+- Server `github` exposes prompt `create-pr`
+- Available as: `/mcp__github__create-pr`
+
+MCP prompts appear alongside regular commands in the `/` menu. They accept arguments and execute the server's prompt template with Claude. This enables MCP servers to provide guided workflows beyond simple tool calls.
+
+**Plugin design note:** If your MCP server exposes prompts, document their names and expected arguments in your plugin README so users can discover them.
+
 ## Tool Search
 
 For MCP servers with many tools, use Tool Search to find relevant tools:
@@ -277,6 +292,16 @@ For MCP servers with many tools, use Tool Search to find relevant tools:
 2. Search by natural language or partial names
 3. Get filtered list of matching tools
 
+### Auto-Enable Behavior
+
+Tool Search activates automatically when MCP servers collectively provide more tools than fit efficiently in Claude's context window (default threshold: 10% of context). Instead of loading all tool descriptions upfront, Claude searches for relevant tools on-demand.
+
+**Plugin design implications:**
+
+- **Many-tool servers**: Tools may not be immediately visible; use descriptive tool names and descriptions
+- **Documentation**: Note tool search behavior in README if your server provides 20+ tools
+- **Environment control**: `ENABLE_TOOL_SEARCH=auto:5` (custom 5% threshold) or `ENABLE_TOOL_SEARCH=false` (disable)
+
 This feature is automatic - just ask Claude about available tools or describe what you want to do.
 
 ### Using MCP Tools in Commands

plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md

@@ -585,3 +585,39 @@ Effective MCP tool usage requires:
 6. **Testing thoroughly** before deployment
 
 Follow these patterns for robust MCP tool integration in your plugin commands and agents.
+
+## MCP Prompts as Commands
+
+Beyond tools and resources, MCP servers can expose **prompts** — pre-defined instruction templates that appear as slash commands in Claude Code.
+
+### How Prompts Work
+
+When an MCP server declares prompts via the MCP protocol, Claude Code automatically registers them as slash commands:
+
+- **Format:** `/mcp__servername__promptname`
+- **Discovery:** Prompts appear in the `/` autocomplete menu alongside regular commands
+- **Arguments:** Prompts can accept arguments defined by the server's prompt schema
+
+### Integration with Plugin Commands
+
+If your plugin bundles an MCP server that exposes prompts, those prompts become available when the plugin is installed. This provides another mechanism for guided workflows:
+
+```markdown
+# Example: Plugin README documenting MCP prompts
+
+## Available MCP Prompts
+
+After installing this plugin, the following MCP prompts are available:
+
+- `/mcp__myserver__create-report` - Generate a structured report
+- `/mcp__myserver__analyze-data` - Run data analysis with guided inputs
+```
+
+### When to Use MCP Prompts vs Plugin Commands
+
+| Approach | Best For |
+| --- | --- |
+| MCP prompts | Server-defined workflows, dynamic templates from external services |
+| Plugin commands | Static workflows, plugin-specific logic, complex prompt composition |
+
+**Tip:** MCP prompts are ideal when the workflow logic lives on the server side and may change independently of the plugin. Plugin commands are better when you want full control over the prompt content.