docs: close documentation gaps vs official Claude Code docs

sjnims · claude · sjnims · commit bb5b84599c8c · 2026-02-10T20:16:44.000-05:00
Close 19 gaps identified by comprehensive audit of official Claude Code
documentation against plugin-dev skill content:

Skills (6 files):
- hook-development: Remove fake "Setup" event, add prompt/agent hook
  response schema, add SessionStart matchers, new hook-input-schemas
  reference with per-event and per-tool input fields, add
  updatedMCPToolOutput and additionalContext to advanced reference
- agent-development: Add MCP background limitation, agent scope
  hierarchy, detailed permission specifier syntax (Bash/path/MCP/Task
  patterns), team permission inheritance/context isolation/token costs
- mcp-integration: Add CLI commands, scope system, specific output
  limits (10K/25K), ${VAR:-default} syntax, CLI OAuth flags
- skill-development: Add skill precedence hierarchy, $N shorthand,
  argument-hint frontmatter field
- plugin-settings: Add settings scope precedence note

Project docs (6 files):
- Fix CHANGELOG.md version comparison links (add v0.4.0, v0.3.4)
- Add 0.4.x to SECURITY.md supported versions
- Fix missing hook events and permission modes in component-patterns
- Fix markdownlint -&gt; markdownlint-cli2 in README, CONTRIBUTING, and
  release-procedure docs

Also: update Serena memories, bump .nvmrc to 25.6.1, fix prettier
formatting on github-actions reference.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-25.5.0
+25.6.1
diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md
@@ -6,7 +6,7 @@ A **plugin marketplace** containing the **plugin-dev** plugin - a comprehensive
 
 ## Version
 
-Current: v0.3.4
+Current: v0.4.0
 
 ## Two-Level Architecture
 
@@ -45,8 +45,10 @@ plugin-dev/                      # Marketplace root
 │           ├── agent-development/
 │           ├── command-development/
 │           ├── hook-development/
+│           ├── lsp-integration/
 │           ├── marketplace-structure/
 │           ├── mcp-integration/
+│           ├── plugin-dev-guide/
 │           ├── plugin-settings/
 │           ├── plugin-structure/
 │           └── skill-development/
@@ -82,11 +84,16 @@ Each skill follows this pattern:
 - `examples/` - Complete working examples for copy-paste
 - `scripts/` - Utility scripts (executable without loading into context)
 
-## Recent Enhancements (v0.3.4)
+## Recent Enhancements (v0.4.0)
 
-Added 5 new reference files from claude-docs audit:
-- `skill-development/references/advanced-frontmatter.md` - model, hooks, visibility budget
-- `plugin-structure/references/headless-ci-mode.md` - headless/CI compatibility
-- `plugin-structure/references/github-actions.md` - GitHub Actions integration
-- `plugin-settings/references/memory-rules-system.md` - CLAUDE.md, rules, hierarchy
-- `plugin-structure/references/advanced-topics.md` - consolidated advanced topics
+Closed documentation gaps vs official Claude Code docs:
+
+- Removed fake "Setup" hook event (bug fix)
+- Added prompt/agent hook response schema (`ok`/`reason` format)
+- New `hook-development/references/hook-input-schemas.md` — per-event and per-tool input schemas
+- New `agent-development/references/permission-modes-rules.md` — detailed permission specifier syntax
+- New `plugin-structure/references/output-styles.md` — output styles guidance
+- Expanded agent teams section (permission inheritance, context isolation, token costs)
+- Added MCP CLI commands, scope system, specific output limits (10K/25K)
+- Added skill/agent/settings precedence hierarchies
+- Added `$N` argument shorthand, `argument-hint` frontmatter for skills
diff --git a/.serena/memories/style_conventions.md b/.serena/memories/style_conventions.md
@@ -44,7 +44,12 @@ color: blue/cyan/green/yellow/magenta/red
 tools: Read, Write, Edit # Optional, allowlist (comma-separated)
 disallowedTools: Bash, Write # Optional, denylist (use one or the other)
 skills: skill-name # Optional, comma-separated
-permissionMode: acceptEdits/dontAsk/bypassPermissions/plan # Optional
+permissionMode: default/acceptEdits/delegate/dontAsk/bypassPermissions/plan # Optional
+maxTurns: 50 # Optional, limit agentic turns
+memory: user/project/local # Optional, persistent memory
+mcpServers: server-name # Optional, scoped MCP access
+hooks: # Optional, scoped to agent lifecycle
+  PreToolUse: [...]
 ```
 
 ### Skills (YAML)
@@ -54,6 +59,12 @@ name: skill-name
 description: "This skill should be used when..."
 allowed-tools: Read, Grep # Optional, for read-only workflows
 model: inherit/sonnet/opus/haiku # Optional
+context: fork # Optional, run in subagent
+agent: Explore/Plan/general-purpose # Optional, with context: fork
+skills: other-skill # Optional, load into forked agent
+user-invocable: true/false # Optional, visibility in / menu
+disable-model-invocation: true/false # Optional, prevent auto-loading
+argument-hint: "<arg>" # Optional, autocomplete hint
 hooks: # Optional, scoped to skill lifecycle
   PreToolUse: [...]
 ```
diff --git a/.serena/memories/task_completion.md b/.serena/memories/task_completion.md
@@ -53,7 +53,7 @@ Test that:
 ```bash
 # Verify versions match in all files
 rg '"version"' plugins/plugin-dev/.claude-plugin/plugin.json .claude-plugin/marketplace.json
-rg 'Current Version.*v[0-9]' CLAUDE.md
+rg 'Version.*v[0-9]' CLAUDE.md
 ```
 
 Version must be synchronized in:
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -287,7 +287,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Based on original plugin by Daisy Hollman at Anthropic
 - Expanded with enhanced skills, additional utilities, and CI/CD infrastructure
 
-[Unreleased]: https://github.com/sjnims/plugin-dev/compare/v0.3.3...HEAD
+[Unreleased]: https://github.com/sjnims/plugin-dev/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/sjnims/plugin-dev/compare/v0.3.4...v0.4.0
+[0.3.4]: https://github.com/sjnims/plugin-dev/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/sjnims/plugin-dev/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/sjnims/plugin-dev/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/sjnims/plugin-dev/compare/v0.3.0...v0.3.1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -143,7 +143,7 @@ markdownlint-cli2 '**/*.md'
 
 # Format with prettier
 prettier --check '**/*.md'
-prettier --write '**/*.md'
+prettier --write '**/*.md'  # fix formatting issues
 ```
 
 ### YAML Linting
diff --git a/README.md b/README.md
@@ -392,7 +392,7 @@ To contribute improvements:
 1. Fork this repository
 2. Make changes to `plugins/plugin-dev/`
 3. Test locally with `claude --plugin-dir plugins/plugin-dev`
-4. Run linters: `markdownlint '**/*.md'` and `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh`
+4. Run linters: `markdownlint-cli2 '**/*.md'` and `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh`
 5. Create a PR with your changes
 
 ## Getting Help
diff --git a/SECURITY.md b/SECURITY.md
@@ -6,6 +6,7 @@ We release patches for security vulnerabilities for the following versions:
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 0.4.x   | :white_check_mark: |
 | 0.3.x   | :white_check_mark: |
 | 0.2.x   | :white_check_mark: |
 | 0.1.x   | :white_check_mark: |
@@ -158,4 +159,4 @@ _No security issues have been reported yet._
 
 ---
 
-**Note:** _This security policy was last updated: January 24, 2026_
+**Note:** _This security policy was last updated: February 10, 2026_
diff --git a/docs/component-patterns.md b/docs/component-patterns.md
@@ -13,7 +13,7 @@ Agents require YAML frontmatter with:
 - `tools`: Comma-separated list of allowed tools (optional, allowlist)
 - `disallowedTools`: Comma-separated list of blocked tools (optional, denylist — use one or the other)
 - `skills`: Comma-separated list of skills the agent can load (optional)
-- `permissionMode`: acceptEdits/dontAsk/bypassPermissions/plan (optional)
+- `permissionMode`: default/acceptEdits/delegate/dontAsk/bypassPermissions/plan (optional)
 - `maxTurns`: Number limiting agentic turns (optional)
 - `memory`: user/project/local for persistent memory (optional)
 - `mcpServers`: Scoped MCP server access (optional)
@@ -69,7 +69,7 @@ disallowedTools: Bash, Write # Denylist
 
 Hooks defined in `hooks/hooks.json`:
 
-- Events: PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, TeammateIdle, TaskCompleted
+- Events: PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStart, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, TeammateIdle, TaskCompleted
 - Types: `prompt` (LLM-driven), `command` (bash scripts), or `agent` (multi-step with tools)
 - Use matchers for tool filtering (e.g., "Write|Edit", "\*")
 
diff --git a/docs/release-procedure.md b/docs/release-procedure.md
@@ -61,7 +61,7 @@ rg 'Version.*v[0-9]' CLAUDE.md
 
 ```bash
 # Lint markdown files
-markdownlint '**/*.md' --ignore node_modules
+markdownlint-cli2 '**/*.md'
 
 # Verify version consistency
 rg '"version"' plugins/plugin-dev/.claude-plugin/plugin.json .claude-plugin/marketplace.json
diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md
@@ -489,6 +489,8 @@ plugin-name/
 
 All `.md` files in `agents/` are auto-discovered.
 
+**Agent precedence:** `--agents` CLI flag > `.claude/agents/` (project) > `~/.claude/agents/` (personal) > Plugin `agents/` directory. Higher-priority agents with the same name shadow lower-priority ones. Use distinctive, namespaced names for plugin agents to avoid collisions.
+
 ### Portable Paths
 
 When referencing files within your plugin (scripts, references, etc.) from agent system prompts, use `${CLAUDE_PLUGIN_ROOT}` for portable paths:
@@ -595,6 +597,8 @@ Agents can run in foreground (blocking) or background (concurrent) mode:
 
 Background agents that need an unapproved permission will fail. Plan tool restrictions accordingly.
 
+**MCP limitation:** MCP tools are unavailable in background subagents. If your agent relies on MCP tools (from the plugin's `.mcp.json`), it must run in foreground mode. Design agents that may run in background to use only built-in tools.
+
 **Resuming agents:** Each Task invocation creates a fresh agent. To continue with full prior context, ask Claude to "resume that agent" — it will restore the previous transcript.
 
 **Restricting spawnable agents:** Use `Task(agent_type1, agent_type2)` syntax in settings.json allow rules to control which agent types can be spawned. Omitting `Task` entirely prevents subagent spawning.
diff --git a/plugins/plugin-dev/skills/agent-development/references/advanced-agent-fields.md b/plugins/plugin-dev/skills/agent-development/references/advanced-agent-fields.md
@@ -189,6 +189,18 @@ Team leads coordinate work across multiple teammates. Key design considerations:
 permissionMode: delegate
 ```
 
+### Permission Inheritance
+
+Teammates inherit the team lead's permission settings. If the lead runs with `--dangerously-skip-permissions`, all teammates inherit that too. Plan permission modes accordingly — a permissive lead creates permissive teammates.
+
+### Context Isolation
+
+Teammates load CLAUDE.md, MCP servers, and skills from the project, but do NOT inherit the lead's conversation history. Each teammate starts with a fresh context window; the spawn prompt provides initial task context.
+
+### Token Cost
+
+Each teammate is a separate Claude Code session with its own context window. Token costs scale linearly with team size. Worth the extra cost for genuinely parallel work, but avoid spawning teammates for tasks that could be done sequentially.
+
 ### Designing Teammate Agents
 
 Teammates are spawned by the team lead and work independently on assigned tasks:
@@ -200,7 +212,13 @@ Teammates are spawned by the team lead and work independently on assigned tasks:
 
 ### Display Modes
 
-Agent teams display in the terminal using split panes when available, with each teammate getting its own output area. In environments without split pane support, teammates run in-process with interleaved output.
+The `teammateMode` setting controls how agent teams display in the terminal:
+
+| Mode         | Behavior                                                  |
+| ------------ | --------------------------------------------------------- |
+| `in-process` | All teammates in main terminal; Shift+Up/Down to navigate |
+| `tmux`       | Split panes, each teammate in its own pane                |
+| `auto`       | Split panes if in tmux, in-process otherwise (default)    |
 
 ### Team Hooks
 
diff --git a/plugins/plugin-dev/skills/agent-development/references/permission-modes-rules.md b/plugins/plugin-dev/skills/agent-development/references/permission-modes-rules.md
@@ -64,6 +64,84 @@ Restricts the agent to team coordination tools only: spawning teammates, sending
 permissionMode: delegate
 ```
 
+## Permission Specifier Syntax
+
+Permission specifiers define exactly which tool invocations a rule matches. Each tool type has its own pattern syntax.
+
+### Bash Patterns
+
+| Pattern          | Behavior                     | Example Match             | Non-Match          |
+| ---------------- | ---------------------------- | ------------------------- | ------------------ |
+| `Bash(npm test)` | Exact match                  | `npm test`                | `npm test --watch` |
+| `Bash(npm *)`    | Prefix with word boundary    | `npm test`, `npm install` | `npmx build`       |
+| `Bash(git*)`     | Prefix without word boundary | `git`, `git push`, `gitk` | —                  |
+
+Space before `*` means word boundary: `Bash(ls *)` matches `ls -la` but NOT `lsof`. No space means substring: `Bash(git*)` matches both `git push` and `gitk`.
+
+### Path Patterns for Edit/Read/Write
+
+Path specifiers follow the gitignore specification:
+
+| Pattern  | Meaning                                      | Example                |
+| -------- | -------------------------------------------- | ---------------------- |
+| `//path` | Absolute from filesystem root                | `Edit(//etc/config)`   |
+| `~/path` | Relative to home directory                   | `Read(~/Documents/**)` |
+| `/path`  | Relative to settings file location           | `Edit(/src/**)`        |
+| `./path` | Relative to current directory                | `Write(./output/*)`    |
+| `path`   | Relative to current directory (same as `./`) | `Edit(src/**)`         |
+| `*`      | Single directory level wildcard              | `Read(src/*)`          |
+| `**`     | Recursive directory wildcard                 | `Edit(src/**)`         |
+
+### WebFetch Patterns
+
+Restrict by domain:
+
+```
+WebFetch(domain:example.com)
+```
+
+### MCP Tool Patterns
+
+| Pattern             | Matches                   |
+| ------------------- | ------------------------- |
+| `mcp__server`       | All tools from server     |
+| `mcp__server__*`    | All tools from server     |
+| `mcp__server__tool` | Specific tool from server |
+
+### Task (Agent) Patterns
+
+| Pattern              | Matches                      |
+| -------------------- | ---------------------------- |
+| `Task(agent-name)`   | Only the named agent type    |
+| `Task(name1, name2)` | Only listed agent types      |
+| `Task`               | All subagent types           |
+| _(omit entirely)_    | No subagent spawning allowed |
+
+### Skill Patterns
+
+| Pattern         | Matches                     |
+| --------------- | --------------------------- |
+| `Skill(name)`   | Exact skill name match      |
+| `Skill(name *)` | Prefix match with arguments |
+
+### Evaluation Order
+
+Rules are evaluated in a strict order — first match wins within each tier:
+
+1. **Deny** rules checked first
+2. **Ask** rules checked second
+3. **Allow** rules checked last
+
+### Default Permission Tiers
+
+Tools fall into three default permission tiers:
+
+| Tier              | Tools                     | Behavior                                           |
+| ----------------- | ------------------------- | -------------------------------------------------- |
+| Read-only         | Read, Glob, Grep          | No approval needed                                 |
+| Bash commands     | Bash                      | Manual approval on first use per directory/command |
+| File modification | Write, Edit, NotebookEdit | Approval required per session                      |
+
 ## Permission Rules
 
 Permission rules provide fine-grained control over specific tool access. They are configured in settings files (not agent frontmatter) and apply based on precedence.
diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/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", "scoped hooks", "frontmatter hooks", "hook in skill", "hook in agent", "agent hook type", "async hooks", "once handler", "statusMessage", "hook decision control", "TeammateIdle hook", "TaskCompleted hook", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SubagentStart, Setup, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, TeammateIdle, TaskCompleted). 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", "async hooks", "once handler", "statusMessage", "hook decision control", "TeammateIdle hook", "TaskCompleted hook", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, TeammateIdle, TaskCompleted). 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
@@ -33,6 +33,19 @@ Use LLM-driven decision making for context-aware validation:
 
 **Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse
 
+**Response format:**
+
+Prompt hooks must return:
+
+```json
+{ "ok": true, "reason": "Explanation of decision" }
+```
+
+- `ok: true` -- approve/allow the action
+- `ok: false` -- block/deny the action
+- `reason` -- required when `ok: false`, fed back to Claude
+- Default model: Haiku
+
 **Benefits:**
 
 - Context-aware decisions based on natural language reasoning
@@ -338,28 +351,6 @@ Execute when a subagent is started. Use to initialize subagent state or perform
 }
 ```
 
-### Setup
-
-Execute once at session start to perform global setup or initialize resources.
-
-**Example:**
-
-```json
-{
-  "Setup": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-setup.sh"
-        }
-      ]
-    }
-  ]
-}
-```
-
 ### UserPromptSubmit
 
 Execute when user submits a prompt. Use to add context, validate, or block prompts.
@@ -386,6 +377,8 @@ Execute when user submits a prompt. Use to add context, validate, or block promp
 
 Execute when Claude Code session begins. Use to load context and set environment.
 
+**Supported matchers:** `startup` (first launch), `resume` (resuming session), `clear` (after /clear), `compact` (after context compaction).
+
 **Example:**
 
 ```json
@@ -468,6 +461,8 @@ All hooks receive JSON via stdin with common fields:
 
 Access fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc.
 
+For comprehensive per-tool and per-event input schemas, see [Hook Input Schemas](references/hook-input-schemas.md).
+
 ## Environment Variables
 
 Available in all command hooks:
@@ -767,7 +762,6 @@ echo "$output" | jq .
 
 | Event              | When               | Use For                  |
 | ------------------ | ------------------ | ------------------------ |
-| Setup              | Session init       | Global initialization    |
 | PreToolUse         | Before tool        | Validation, modification |
 | PermissionRequest  | Permission dialog  | Auto-allow/deny          |
 | PostToolUse        | After tool success | Feedback, logging        |
diff --git a/plugins/plugin-dev/skills/hook-development/references/advanced.md b/plugins/plugin-dev/skills/hook-development/references/advanced.md
diff --git a/plugins/plugin-dev/skills/hook-development/references/hook-input-schemas.md b/plugins/plugin-dev/skills/hook-development/references/hook-input-schemas.md
diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md
diff --git a/plugins/plugin-dev/skills/mcp-integration/references/authentication.md b/plugins/plugin-dev/skills/mcp-integration/references/authentication.md
diff --git a/plugins/plugin-dev/skills/plugin-settings/SKILL.md b/plugins/plugin-dev/skills/plugin-settings/SKILL.md
diff --git a/plugins/plugin-dev/skills/plugin-structure/references/github-actions.md b/plugins/plugin-dev/skills/plugin-structure/references/github-actions.md
diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md
