From ae29b9d7bc44daf48c0d9db416fcdd634dbccad5 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Mon, 26 Jan 2026 13:00:26 +1300 Subject: [PATCH 01/33] feat: add plugin-dev-guide meta-skill for skill navigation Adds a guide skill that helps users navigate the 9 specialized plugin-dev skills. Routes users to the appropriate skill based on their task. - New skill: plugin-dev-guide with decision tree and workflows - New command: plugin-dev-guide for autocomplete discoverability - Update skill count to 10 in plugin.json and marketplace.json Closes #184 --- .claude-plugin/marketplace.json | 2 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../plugin-dev/commands/plugin-dev-guide.md | 10 + .../skills/plugin-dev-guide/SKILL.md | 214 ++++++++++++++++++ 4 files changed, 226 insertions(+), 2 deletions(-) create mode 100644 plugins/plugin-dev/commands/plugin-dev-guide.md create mode 100644 plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 478fd8a..aac066b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "plugins": [ { "name": "plugin-dev", - "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 9 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.", + "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "version": "0.3.2", "author": { "name": "Daisy Hollman", diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 47ac0c3..1f9bb66 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "plugin-dev", "version": "0.3.2", - "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 9 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices. AI-assisted plugin creation and validation.", + "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Daisy Hollman", "email": "daisy@anthropic.com" diff --git a/plugins/plugin-dev/commands/plugin-dev-guide.md b/plugins/plugin-dev/commands/plugin-dev-guide.md new file mode 100644 index 0000000..2700370 --- /dev/null +++ b/plugins/plugin-dev/commands/plugin-dev-guide.md @@ -0,0 +1,10 @@ +--- +description: Get an overview of plugin development capabilities and skill routing +argument-hint: [question or task] +--- + +Invoke the plugin-dev:plugin-dev-guide skill to load plugin development guidance. + +Then help with: $ARGUMENTS + +If no arguments provided, summarize what plugin development capabilities are available and ask the user what they want to build or learn about. diff --git a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md new file mode 100644 index 0000000..c842d0b --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md @@ -0,0 +1,214 @@ +--- +name: plugin-dev-guide +description: This skill should be used when the user asks about "Claude Code plugins", "plugin development", "how to build a plugin", "what plugin components exist", "plugin architecture", "extending Claude Code", or needs an overview of plugin development capabilities. Acts as a guide to the 9 specialized plugin-dev skills, explaining when to activate each one. Load this skill first when the user is new to plugin development or unsure which specific skill they need. +--- + +# Plugin Development Guide + +This meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand. + +## Plugin Development Skills Overview + +The plugin-dev toolkit provides 9 specialized skills for building Claude Code plugins. Each skill handles a specific domain of plugin development. + +### Skill Quick Reference + +| Skill | Purpose | +| ------- | --------- | +| **plugin-structure** | Directory layout, manifest, component organization | +| **command-development** | Slash commands with frontmatter | +| **agent-development** | Autonomous subagents | +| **skill-development** | Creating skills with progressive disclosure | +| **hook-development** | Event-driven automation | +| **mcp-integration** | Model Context Protocol servers | +| **lsp-integration** | Language Server Protocol for code intelligence | +| **plugin-settings** | User configuration via .local.md | +| **marketplace-structure** | Plugin marketplace creation | + +## When to Use Each Skill + +### Starting a New Plugin + +**Skill: `plugin-structure`** + +Use when the user needs to: + +- Create a new plugin from scratch +- Understand plugin directory layout +- Configure plugin.json manifest +- Learn about component auto-discovery +- Use ${CLAUDE_PLUGIN_ROOT} for portable paths + +### Adding User-Facing Commands + +**Skill: `command-development`** + +Use when the user needs to: + +- Create slash commands (/command-name) +- Configure command frontmatter (description, allowed-tools, model) +- Use dynamic arguments ($ARGUMENTS, $1, $2) +- Reference files with @ syntax +- Execute bash inline with `[BANG]` backticks + +### Creating Autonomous Agents + +**Skill: `agent-development`** + +Use when the user needs to: + +- Create subagents for complex tasks +- Write agent system prompts +- Configure agent triggering (description with examples) +- Choose agent models and colors +- Restrict agent tool access + +### Building Skills + +**Skill: `skill-development`** + +Use when the user needs to: + +- Create skills that extend Claude's capabilities +- Write SKILL.md with proper frontmatter +- Organize skill content with progressive disclosure +- Create references/, examples/, scripts/ directories +- Write effective trigger phrases + +### Implementing Event Hooks + +**Skill: `hook-development`** + +Use when the user needs to: + +- React to Claude Code events (PreToolUse, Stop, SessionStart, etc.) +- Create prompt-based or command-based hooks +- Validate tool inputs before execution +- Enforce completion standards +- Block dangerous operations + +### Integrating External Services via MCP + +**Skill: `mcp-integration`** + +Use when the user needs to: + +- Add MCP servers to plugins +- Configure stdio, SSE, HTTP, or WebSocket servers +- Set up authentication (OAuth, tokens) +- Use MCP tools in commands and agents +- Discover existing MCP servers on PulseMCP + +### Adding Code Intelligence via LSP + +**Skill: `lsp-integration`** + +Use when the user needs to: + +- Add Language Server Protocol servers to plugins +- Enable go-to-definition and find-references +- Configure language-specific servers (pyright, gopls, rust-analyzer) +- Set up extensionToLanguage mappings +- Enhance Claude's code understanding + +### Managing Plugin Configuration + +**Skill: `plugin-settings`** + +Use when the user needs to: + +- Store user-configurable settings +- Use .claude/plugin-name.local.md pattern +- Parse YAML frontmatter in hooks +- Create temporarily active hooks +- Manage agent state + +### Creating Plugin Marketplaces + +**Skill: `marketplace-structure`** + +Use when the user needs to: + +- Create a marketplace for multiple plugins +- Configure marketplace.json +- Set up plugin sources (relative, GitHub, git URL) +- Distribute plugins to teams +- Organize plugin collections + +## Decision Tree for Skill Selection + +``` +User wants to... +├── Create/organize a plugin structure? → plugin-structure +├── Add a slash command? → command-development +├── Create an autonomous agent? → agent-development +├── Add domain expertise/knowledge? → skill-development +├── React to Claude Code events? → hook-development +├── Integrate external service/API? → mcp-integration +├── Add code intelligence/LSP? → lsp-integration +├── Make plugin configurable? → plugin-settings +└── Distribute multiple plugins? → marketplace-structure +``` + +## Common Multi-Skill Workflows + +### Building a Complete Plugin + +1. **Start**: Load `plugin-structure` skill to create directory layout +2. **Add features**: Load `command-development` for user-facing commands +3. **Automation**: Load `hook-development` for event-driven behavior +4. **Configuration**: Load `plugin-settings` if user configuration needed +5. **Validation**: Use plugin-validator agent to validate structure + +### Creating an MCP-Powered Plugin + +1. **Start**: Load `plugin-structure` for basic structure +2. **Integration**: Load `mcp-integration` to configure MCP servers +3. **Commands**: Load `command-development` to create commands that use MCP tools +4. **Agents**: Load `agent-development` for autonomous MCP workflows + +### Building a Code Intelligence Plugin + +1. **Start**: Load `plugin-structure` for basic structure +2. **LSP**: Load `lsp-integration` to configure language servers +3. **Commands**: Load `command-development` for commands using LSP features + +### Building a Skill-Focused Plugin + +1. **Start**: Load `plugin-structure` for basic structure +2. **Skills**: Load `skill-development` to create specialized skills +3. **Validation**: Use skill-reviewer agent to validate skill quality + +## Available Agents + +The plugin-dev plugin also provides 3 agents: + +| Agent | Purpose | +|-------|---------| +| **plugin-validator** | Validates plugin structure and manifests | +| **skill-reviewer** | Reviews skill quality and triggering | +| **agent-creator** | Generates new agents from descriptions | + +Use agents proactively after creating components to ensure quality. + +## Available Commands + +| Command | Purpose | +|---------|---------| +| `/plugin-dev:start` | Entry point - choose plugin or marketplace creation | +| `/plugin-dev:create-plugin` | 8-phase guided plugin creation workflow | +| `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow | + +--- + +## User Request + +$ARGUMENTS + +If the user provided a request above, analyze it and either: + +1. **Route to a specific skill** if the request clearly matches one domain +2. **Answer directly** using this guide's overview information +3. **Ask for clarification** if the request is ambiguous + +If no request was provided, summarize the available plugin development capabilities and ask what the user wants to build or learn about. From fc97a0a68489e50ba2125687f5ce782a29179dbb Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Mon, 26 Jan 2026 17:23:04 +1300 Subject: [PATCH 02/33] =?UTF-8?q?chore:=20bump=20version=200.3.2=20?= =?UTF-8?q?=E2=86=92=200.3.3=20and=20update=20component=20counts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Bump plugin version to 0.3.3 in plugin.json and marketplace.json - Update CLAUDE.md version reference and component counts (10 skills, 3 agents, 4 slash commands) - Add command frontmatter (allowed-tools, model) to plugin-dev-guide - Clarify skill count statement in plugin-dev-guide SKILL.md --- .claude-plugin/marketplace.json | 4 ++-- CLAUDE.md | 4 ++-- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- plugins/plugin-dev/commands/plugin-dev-guide.md | 2 ++ plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md | 2 +- 5 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5f737f8..2137a34 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, now maintained by Steve Nims.", - "version": "0.3.2" + "version": "0.3.3" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.3.2", + "version": "0.3.3", "author": { "name": "Steve Nims", "url": "https://github.com/sjnims" diff --git a/CLAUDE.md b/CLAUDE.md index 35b4477..882fcb4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,9 +4,9 @@ Guidance for Claude Code working in this repository. ## What This Is -Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 9 skills, 3 agents, 3 slash commands. +Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 3 agents, 4 slash commands. -**Version**: v0.3.2 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.3.3 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 1c78c38..6821991 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.3.2", + "version": "0.3.3", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Steve Nims", diff --git a/plugins/plugin-dev/commands/plugin-dev-guide.md b/plugins/plugin-dev/commands/plugin-dev-guide.md index 2700370..d393236 100644 --- a/plugins/plugin-dev/commands/plugin-dev-guide.md +++ b/plugins/plugin-dev/commands/plugin-dev-guide.md @@ -1,6 +1,8 @@ --- description: Get an overview of plugin development capabilities and skill routing argument-hint: [question or task] +allowed-tools: Skill, AskUserQuestion +model: sonnet --- Invoke the plugin-dev:plugin-dev-guide skill to load plugin development guidance. diff --git a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md index c842d0b..33ab28b 100644 --- a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md @@ -9,7 +9,7 @@ This meta-skill provides an overview of Claude Code plugin development and route ## Plugin Development Skills Overview -The plugin-dev toolkit provides 9 specialized skills for building Claude Code plugins. Each skill handles a specific domain of plugin development. +The plugin-dev toolkit provides 9 specialized skills for building Claude Code plugins, plus this guide. Each skill handles a specific domain of plugin development. ### Skill Quick Reference From bdf46bda9a9523f82346f76d00d38e2febeaf26d Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Fri, 20 Mar 2026 12:02:49 +1300 Subject: [PATCH 03/33] feat: document all 22 Claude Code hook events with complete schemas - Rewrite SKILL.md to cover all 22 hook events organized by category (was 13 events). Remove nonexistent "Setup" event. - Add references/event-schemas.md with complete input/output JSON schemas for every event, including SDK parity notes - Add 8 new patterns (11-18) for StopFailure, TaskCompleted, TeammateIdle, WorktreeCreate/Remove, ConfigChange, Elicitation, PreCompact/PostCompact, and InstructionsLoaded - Add HTTP and Agent hook types (was only prompt and command) - Fix deprecated PreToolUse output fields (permissionDecision replaces decision approve/block) - Update validate-hook-schema.sh: recognize all 22 events, validate all 4 hook types, check event-specific type restrictions --- .../skills/hook-development/SKILL.md | 827 ++++++++++------ .../references/event-schemas.md | 892 ++++++++++++++++++ .../hook-development/references/patterns.md | 365 +++++++ .../scripts/validate-hook-schema.sh | 50 +- 4 files changed, 1851 insertions(+), 283 deletions(-) create mode 100644 plugins/plugin-dev/skills/hook-development/references/event-schemas.md diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index 1626ddb..b3a5e30 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/plugins/plugin-dev/skills/hook-development/SKILL.md @@ -1,44 +1,64 @@ --- 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. +version: 0.2.0 +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, StopFailure, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, Notification, ConfigChange, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove, InstructionsLoaded, Elicitation, ElicitationResult). 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 ## Overview -Hooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows. +Hooks are event-driven automation that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows. -**Key capabilities:** +Claude Code has **22 hook events** across these categories: -- Validate tool calls before execution (PreToolUse) -- React to tool results (PostToolUse) -- Enforce completion standards (Stop, SubagentStop) -- Load project context (SessionStart) -- Automate workflows across the development lifecycle +- **Session Lifecycle** -- SessionStart, InstructionsLoaded, SessionEnd +- **User Input** -- UserPromptSubmit +- **Tool Lifecycle** -- PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure +- **Turn Control** -- Stop, StopFailure +- **Subagents** -- SubagentStart, SubagentStop +- **Teams** -- TeammateIdle, TaskCompleted +- **Context Management** -- PreCompact, PostCompact +- **Configuration** -- ConfigChange +- **Worktrees** -- WorktreeCreate, WorktreeRemove +- **MCP Elicitation** -- Elicitation, ElicitationResult +- **Notifications** -- Notification + +For complete input/output JSON schemas for every event, see **`references/event-schemas.md`**. ## Hook Types +Four hook types are available. Not all events support all types. + ### Prompt-Based Hooks (Recommended) -Use LLM-driven decision making for context-aware validation: +LLM-driven decision making for context-aware validation: ```json { "type": "prompt", "prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT", + "model": "haiku", "timeout": 30 } ``` -**Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse +**Benefits:** Context-aware decisions, flexible evaluation, better edge case handling, easier to maintain. -**Benefits:** +### Agent Hooks -- Context-aware decisions based on natural language reasoning -- Flexible evaluation logic without bash scripting -- Better edge case handling -- Easier to maintain and extend +Like prompt hooks but with tool access for multi-step validation: + +```json +{ + "type": "agent", + "prompt": "Review the code change and run tests to verify correctness.", + "model": "sonnet", + "timeout": 60 +} +``` + +**Benefits:** Can read files, run commands, and reason across multiple steps. Higher cost and latency than prompt hooks. ### Command Hooks @@ -52,12 +72,23 @@ Execute bash commands for deterministic checks: } ``` -**Use for:** +**Use for:** Fast deterministic validations, file system operations, external tool integrations. + +### HTTP Hooks + +Send event data to an HTTP endpoint: + +```json +{ + "type": "http", + "url": "https://hooks.example.com/claude", + "headers": { "Authorization": "Bearer $API_TOKEN" }, + "allowedEnvVars": ["API_TOKEN"], + "timeout": 30 +} +``` -- Fast deterministic validations -- File system operations -- External tool integrations -- Performance-critical checks +**Use for:** External service integration, centralized logging, webhook-driven workflows. ## Hook Configuration Formats @@ -76,33 +107,10 @@ Execute bash commands for deterministic checks: } ``` -**Key points:** - - `description` field is optional - `hooks` field is required wrapper containing actual hook events - This is the **plugin-specific format** -**Example:** - -```json -{ - "description": "Validation hooks for code quality", - "hooks": { - "PreToolUse": [ - { - "matcher": "Write", - "hooks": [ - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh" - } - ] - } - ] - } -} -``` - ### Settings Format (Direct) **For user settings** in `.claude/settings.json`, use direct format: @@ -115,21 +123,128 @@ Execute bash commands for deterministic checks: } ``` -**Key points:** +- No wrapper -- events directly at top level inside the `"hooks"` key of settings +- Plugin hooks merge with user hooks and run in parallel -- No wrapper - events directly at top level -- No description field -- This is the **settings format** +### Hook Entry Schema + +Each hook entry in a matcher group supports these fields: + +```json +{ + "type": "command|http|prompt|agent", + "command": "string (command type only)", + "url": "string (http type only)", + "headers": { "X-Key": "$ENV_VAR" }, + "allowedEnvVars": ["ENV_VAR"], + "prompt": "string (prompt/agent type only)", + "model": "string (prompt/agent, optional)", + "timeout": 600, + "statusMessage": "Validating...", + "once": false, + "async": false +} +``` + +- `timeout`: Max execution time in seconds. Defaults vary by type (command: 60s, prompt: 30s, http: 30s, agent: 60s) +- `statusMessage`: Shown in the UI while the hook runs +- `once`: Run only once per session (not per event occurrence) +- `async`: Fire-and-forget, cannot block (command hooks only) **Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{"hooks": {...}}`. ## Hook Events -### PreToolUse +### Session Lifecycle + +#### SessionStart + +Execute when a Claude Code session begins. Use to load context and set environment. + +**Matchers:** `startup`, `resume`, `clear`, `compact` +**Hook types:** Command only +**Decision control:** Can halt with `continue: false` + +```json +{ + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh" + } + ] + } + ] +} +``` + +**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`: + +```bash +echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE" +``` + +See `examples/load-context.sh` for a complete example. + +#### InstructionsLoaded + +Execute when CLAUDE.md or `.claude/rules/*.md` files are loaded into context. + +**Matchers:** `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (observability only, runs async) + +**Input includes:** `file_path`, `memory_type` (User|Project|Local|Managed), `load_reason` + +Use to track which instruction files are loaded, enforce policies on instruction content, or log instruction loading patterns. + +#### SessionEnd + +Execute when a session terminates. Use for cleanup, logging, and state preservation. + +**Matchers:** `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `resume`, `other` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (observability only) + +**Gotcha:** Default timeout is only **1.5 seconds**. Override with `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` environment variable for longer-running cleanup. + +### User Input + +#### UserPromptSubmit + +Execute when a user submits a prompt, before Claude processes it. + +**Matchers:** Not supported (silently ignored) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can block with `decision: "block"` and `reason` + +```json +{ + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings via additionalContext." + } + ] + } + ] +} +``` + +### Tool Lifecycle + +#### PreToolUse Execute before any tool runs. Use to approve, deny, or modify tool calls. -**Example (prompt-based):** +**Matchers:** Tool names -- `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, MCP tools as `mcp____`. Regex supported. +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Full -- approve, deny, or modify tool input ```json { @@ -139,7 +254,7 @@ Execute before any tool runs. Use to approve, deny, or modify tool calls. "hooks": [ { "type": "prompt", - "prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'." + "prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content." } ] } @@ -147,23 +262,29 @@ Execute before any tool runs. Use to approve, deny, or modify tool calls. } ``` -**Output for PreToolUse:** +**Output:** ```json { "hookSpecificOutput": { + "hookEventName": "PreToolUse", "permissionDecision": "allow|deny|ask", - "updatedInput": { "field": "modified_value" } - }, - "systemMessage": "Explanation for Claude" + "permissionDecisionReason": "Explanation", + "updatedInput": { "file_path": "/modified/path" }, + "additionalContext": "Extra context for Claude" + } } ``` -### PermissionRequest +> **Deprecated:** The old top-level `decision: "approve|block"` fields still work but are superseded by `hookSpecificOutput.permissionDecision`. Use `permissionDecision` for new hooks. -Execute when user is shown a permission dialog. Use to automatically allow or deny permissions. +#### PermissionRequest -**Example:** +Execute when a permission dialog is about to display. Use to automatically allow or deny permissions without user interaction. + +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Allow or deny the permission ```json { @@ -181,14 +302,16 @@ Execute when user is shown a permission dialog. Use to automatically allow or de } ``` -**Output for PermissionRequest:** +**Output:** ```json { "hookSpecificOutput": { + "hookEventName": "PermissionRequest", "decision": { "behavior": "allow|deny", "updatedInput": { "command": "modified command" }, + "updatedPermissions": [], "message": "Reason for denial", "interrupt": false } @@ -197,21 +320,22 @@ Execute when user is shown a permission dialog. Use to automatically allow or de ``` - `behavior`: "allow" to approve, "deny" to reject -- `updatedInput`: Optional modified tool parameters (only with "allow") +- `updatedInput`: Modified tool parameters (only with "allow") +- `updatedPermissions`: Apply permission rules so user isn't prompted again (only with "allow") - `message`: Explanation shown to user (only with "deny") -- `interrupt`: If true with "deny", stops the current operation +- `interrupt`: If true with "deny", stops the current operation entirely -**Use cases:** +**Difference from PreToolUse:** PreToolUse runs before every tool execution regardless of permission status. PermissionRequest runs only when a permission dialog would be shown to the user. -- Auto-approve safe commands matching patterns -- Block dangerous operations with explanations -- Modify tool inputs before execution +**Known issues:** `additionalContext` is parsed but silently dropped (works in PreToolUse but not here). Race condition where dialog may briefly show despite returning "allow" ([#12176](https://github.com/anthropics/claude-code/issues/12176)). -### PostToolUse +#### PostToolUse -Execute after tool completes. Use to react to results, provide feedback, or log. +Execute after a tool completes successfully. Use to react to results, provide feedback, or log. -**Example:** +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can block further processing with `decision: "block"` and `reason` ```json { @@ -229,27 +353,36 @@ Execute after tool completes. Use to react to results, provide feedback, or log. } ``` -**Output behavior:** +**MCP-specific output:** For MCP tools, `hookSpecificOutput.updatedMCPToolOutput` lets you modify the tool's response before Claude sees it. + +#### PostToolUseFailure + +Execute when a tool fails. Use to handle errors, provide fallback actions, or add diagnostic context. -- Exit 0: stdout shown in transcript -- Exit 2: stderr fed back to Claude -- systemMessage included in context +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Context injection via `additionalContext` -### PostToolUseFailure +**Input includes:** `error` (string), `is_interrupt` (boolean, optional) -Execute when a tool fails after PostToolUse hooks have run. Use to handle errors or provide fallback actions. +### Turn Control -**Example:** +#### Stop + +Execute when the main agent finishes responding. Use to validate completeness before the turn ends. + +**Matchers:** Not supported +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can block the stop, forcing Claude to continue ```json { - "PostToolUseFailure": [ + "Stop": [ { - "matcher": "Edit", "hooks": [ { "type": "prompt", - "prompt": "Error occurred during edit. Provide fallback action or ask for user input." + "prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'block' with reason to continue working, or allow the stop." } ] } @@ -257,26 +390,50 @@ Execute when a tool fails after PostToolUse hooks have run. Use to handle errors } ``` -**Output behavior:** +**Output:** + +```json +{ + "decision": "block", + "reason": "Tests were not run after code changes. Please run the test suite." +} +``` + +When `decision` is `"block"`, `reason` is required and Claude receives it as feedback to continue working. + +**Input includes:** `stop_hook_active` (boolean), `last_assistant_message` (string) + +#### StopFailure -- Exit 2: stderr fed back to Claude -- systemMessage included in context +Execute when a turn ends due to an API error (not a normal stop). Use for alerting and diagnostics. -### Stop +**Matchers:** `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, `unknown` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (output and exit code are ignored) -Execute when main agent considers stopping. Use to validate completeness. +**Input includes:** `error`, `error_details` (optional), `last_assistant_message` -**Example:** +Use to send alerts when rate limits hit, auth fails, or billing errors occur. + +### Subagents + +#### SubagentStart + +Execute when a subagent is spawned via the Agent tool. Use to initialize state or inject context. + +**Matchers:** Agent type names (`Bash`, `Explore`, `Plan`, custom agent names) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Context injection via `additionalContext` ```json { - "Stop": [ + "SubagentStart": [ { - "matcher": "*", + "matcher": "code-reviewer", "hooks": [ { - "type": "prompt", - "prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue." + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/subagent-init.sh" } ] } @@ -284,37 +441,65 @@ Execute when main agent considers stopping. Use to validate completeness. } ``` -**Decision output:** +**Input includes:** `agent_id`, `agent_type` + +#### SubagentStop + +Execute when a subagent finishes responding. Use to validate subagent output before returning to the parent. + +**Matchers:** Agent type names (same as SubagentStart) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can block the stop (same as Stop) + +**Input includes:** `agent_id`, `agent_type`, `agent_transcript_path`, `last_assistant_message`, `stop_hook_active` + +**Gotcha:** Stop hooks defined in a subagent's context automatically convert to SubagentStop events. + +### Teams + +#### TeammateIdle + +Execute when an agent team teammate is about to go idle. Use as a quality gate before allowing idle. + +**Matchers:** Not supported +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Exit code 2 sends stderr as feedback (teammate keeps working). JSON `{"continue": false, "stopReason": "..."}` stops the teammate entirely. + +**Input includes:** `teammate_name`, `team_name` ```json { - "decision": "approve|block", - "reason": "Explanation", - "systemMessage": "Additional context" + "TeammateIdle": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-teammate-done.sh" + } + ] + } + ] } ``` -### SubagentStop - -Execute when subagent considers stopping. Use to ensure subagent completed its task. +#### TaskCompleted -Similar to Stop hook, but for subagents. +Execute when a task is marked as completed. Use to validate task output or enforce quality standards. -### SubagentStart +**Matchers:** Not supported +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Exit code 2 rejects completion (stderr fed back as feedback, agent continues). JSON `{"continue": false, "stopReason": "..."}` stops the teammate. -Execute when a subagent is started. Use to initialize subagent state or perform setup. - -**Example:** +**Input includes:** `task_id`, `task_subject`, `task_description` (optional), `teammate_name` (optional), `team_name` (optional) ```json { - "SubagentStart": [ + "TaskCompleted": [ { - "matcher": "mcp__subagent_name", "hooks": [ { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/subagent-init.sh" + "type": "prompt", + "prompt": "Review the completed task. Verify the deliverable matches the task description. If incomplete, return exit code 2 with feedback." } ] } @@ -322,21 +507,47 @@ Execute when a subagent is started. Use to initialize subagent state or perform } ``` -### Setup +### Context Management + +#### PreCompact + +Execute before context compaction. Use to inject critical information that should survive compaction. + +**Matchers:** `manual`, `auto` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (observability only) + +**Input includes:** `trigger` ("manual"|"auto"), `custom_instructions` + +#### PostCompact + +Execute after context compaction completes. Use to verify preserved state or log compaction results. -Execute once at session start to perform global setup or initialize resources. +**Matchers:** `manual`, `auto` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (observability only) -**Example:** +**Input includes:** `trigger` ("manual"|"auto"), `compact_summary` + +### Configuration + +#### ConfigChange + +Execute when a configuration file changes during a session. Use for security monitoring or config validation. + +**Matchers:** `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can block with `decision: "block"` and `reason` ```json { - "Setup": [ + "ConfigChange": [ { - "matcher": "*", + "matcher": "project_settings|local_settings", "hooks": [ { "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-setup.sh" + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-config.sh" } ] } @@ -344,21 +555,28 @@ Execute once at session start to perform global setup or initialize resources. } ``` -### UserPromptSubmit +**Input includes:** `source`, `file_path` (optional) + +**Gotcha:** `policy_settings` changes cannot be blocked. The block decision is silently ignored. + +### Worktrees + +#### WorktreeCreate -Execute when user submits a prompt. Use to add context, validate, or block prompts. +Execute when a git worktree is created (via `--worktree` flag or subagent `isolation: "worktree"`). -**Example:** +**Matchers:** Not supported +**Hook types:** Command only +**Decision control:** Hook must print the **absolute path** to the created worktree directory on stdout. Non-zero exit code fails the creation. ```json { - "UserPromptSubmit": [ + "WorktreeCreate": [ { - "matcher": "*", "hooks": [ { - "type": "prompt", - "prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings." + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/create-worktree.sh" } ] } @@ -366,21 +584,39 @@ Execute when user submits a prompt. Use to add context, validate, or block promp } ``` -### SessionStart +**Input includes:** `name` (worktree identifier) + +This is the only hook where stdout is the return value (a path), not JSON. + +#### WorktreeRemove + +Execute when a worktree is being removed (session exit or subagent finish). -Execute when Claude Code session begins. Use to load context and set environment. +**Matchers:** Not supported +**Hook types:** Command only +**Decision control:** None (cleanup only) -**Example:** +**Input includes:** `worktree_path` + +### MCP Elicitation + +#### Elicitation + +Execute when an MCP server requests user input mid-task. Use to auto-respond or filter elicitation requests. + +**Matchers:** MCP server name +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can accept, decline, or cancel the elicitation ```json { - "SessionStart": [ + "Elicitation": [ { - "matcher": "*", + "matcher": "my-mcp-server", "hooks": [ { "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh" + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/handle-elicitation.sh" } ] } @@ -388,25 +624,45 @@ Execute when Claude Code session begins. Use to load context and set environment } ``` -**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`: +**Input includes:** `mcp_server_name`, `message`, `mode` ("form"|"url", optional), `url` (optional), `elicitation_id` (optional), `requested_schema` (optional) -```bash -echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE" +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "Elicitation", + "action": "accept|decline|cancel", + "content": { "field": "value" } + } +} ``` -See `examples/load-context.sh` for complete example. +- `accept`: Provide response via `content` (matching `requested_schema`) +- `decline`: Reject the elicitation request +- `cancel`: Cancel the entire MCP operation + +#### ElicitationResult + +Execute after a user responds to an MCP elicitation, before the response is sent back to the server. Use to modify, validate, or log user responses. -### SessionEnd +**Matchers:** MCP server name +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can override user response with `action` and `content` -Execute when session ends. Use for cleanup, logging, and state preservation. +**Input includes:** `mcp_server_name`, `elicitation_id`, `user_response` -### PreCompact +### Notifications -Execute before context compaction. Use to add critical information to preserve. +#### Notification -### Notification +Execute when Claude Code sends notifications. Use for logging, external alerting, or custom notification routing. -Execute when Claude sends notifications. Use to react to user notifications. +**Matchers:** `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (observability only) + +**Input includes:** `message`, `title` (optional), `notification_type` ## Hook Output Format @@ -415,53 +671,77 @@ Execute when Claude sends notifications. Use to react to user notifications. ```json { "continue": true, + "stopReason": "Why processing should halt", "suppressOutput": false, - "systemMessage": "Message for Claude" + "decision": "block", + "reason": "Feedback for Claude when blocking", + "systemMessage": "Warning shown to user", + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "additionalContext": "Extra context injected for Claude" + } } ``` +All fields are optional. Behavior by field: + - `continue`: If false, halt processing (default true) -- `suppressOutput`: Hide output from transcript (default false) -- `systemMessage`: Message shown to Claude +- `stopReason`: Displayed when `continue` is false +- `suppressOutput`: Hide hook output from transcript (default false) +- `decision`: Set to `"block"` to block the operation +- `reason`: Required when `decision` is `"block"` -- fed back to Claude +- `systemMessage`: Warning displayed to the user +- `hookSpecificOutput`: Event-specific fields (see `references/event-schemas.md`) ### Exit Codes -- `0` - Success (stdout shown in transcript) -- `2` - Blocking error (stderr fed back to Claude) -- Other - Non-blocking error +| Code | Behavior | +| ----- | ------------------------------------------------ | +| 0 | Success. JSON on stdout parsed if present | +| 2 | Blocking error. stderr fed to Claude/user | +| Other | Non-blocking. Shown in verbose/debug mode only | + +**Gotcha:** If your shell profile (`.bashrc`/`.zshrc`) prints text, it contaminates stdout and breaks JSON parsing. Redirect profile output to stderr. + +### Async Hooks + +Command hooks can run fire-and-forget with `"async": true`. Async hooks: + +- Cannot block (exit code 2 is ignored) +- Cannot return decisions +- Run without blocking Claude's workflow +- Useful for logging, metrics, external notifications ## Hook Input Format -All hooks receive JSON via stdin with common fields: +All hooks receive JSON via stdin with these common fields: ```json { "session_id": "abc123", - "transcript_path": "/path/to/transcript.txt", + "transcript_path": "/path/to/transcript.jsonl", "cwd": "/current/working/dir", - "permission_mode": "ask|allow", - "hook_event_name": "PreToolUse" + "hook_event_name": "PreToolUse", + "permission_mode": "default|plan|acceptEdits|dontAsk|bypassPermissions" } ``` -**Event-specific fields:** +When inside a subagent, `agent_id` and `agent_type` are also present. -- **PreToolUse/PermissionRequest/PostToolUse:** `tool_name`, `tool_input`, `tool_result` -- **UserPromptSubmit:** `user_prompt` -- **Stop/SubagentStop:** `reason` +**Event-specific fields vary.** See `references/event-schemas.md` for complete input schemas per event. -Access fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc. +**Access in prompt hooks:** Use `$TOOL_INPUT`, `$TOOL_NAME`, `$USER_PROMPT`, etc. in prompt strings. ## Environment Variables Available in all command hooks: -- `$CLAUDE_PROJECT_DIR` - Project root path -- `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths) -- `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here -- `$CLAUDE_CODE_REMOTE` - Set if running in remote context +- `$CLAUDE_PROJECT_DIR` -- Project root path +- `$CLAUDE_PLUGIN_ROOT` -- Plugin directory (use for portable paths) +- `$CLAUDE_ENV_FILE` -- SessionStart only: write `export VAR=value` lines here to persist env vars +- `$CLAUDE_CODE_REMOTE` -- Set if running in remote context -**Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:** +**Always use `${CLAUDE_PLUGIN_ROOT}` in hook commands for portability:** ```json { @@ -470,46 +750,13 @@ Available in all command hooks: } ``` -## Plugin Hook Configuration - -In plugins, define hooks in `hooks/hooks.json` using the **plugin wrapper format** described in [Hook Configuration Formats](#hook-configuration-formats): - -```json -{ - "hooks": { - "PreToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [{ "type": "prompt", "prompt": "Validate file write safety" }] - } - ], - "Stop": [ - { - "matcher": "*", - "hooks": [{ "type": "prompt", "prompt": "Verify task completion" }] - } - ], - "SessionStart": [ - { - "matcher": "*", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh", - "timeout": 10 - } - ] - } - ] - } -} -``` +## Matchers -**Note:** Plugin hooks use the `{"hooks": {...}}` wrapper format, not the direct settings format. Plugin hooks merge with user's hooks and run in parallel. +### How Matchers Work -## Matchers +Matchers filter which hooks run for a given event. Each event defines what values its matchers accept (tool names, source types, server names, etc.). A hook entry without a `matcher` field matches all occurrences of that event. -### Tool Name Matching +### Tool Name Matching (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure) **Exact match:** @@ -517,41 +764,87 @@ In plugins, define hooks in `hooks/hooks.json` using the **plugin wrapper format "matcher": "Write" ``` -**Multiple tools:** +**Multiple tools (regex OR):** ```json "matcher": "Read|Write|Edit" ``` -**Wildcard (all tools):** +**Regex patterns:** ```json -"matcher": "*" +"matcher": "mcp__.*__delete.*" ``` -**Regex patterns:** +**Common patterns:** ```json -"matcher": "mcp__.*__delete.*" // All MCP delete tools +"matcher": "mcp__.*" // All MCP tools +"matcher": "mcp__plugin_asana_.*" // Specific plugin's MCP tools +"matcher": "Read|Write|Edit" // All file operations +"matcher": "Bash" // Bash commands only ``` -**Note:** Matchers are case-sensitive. +**Note:** Matchers are case-sensitive. Regex is full regex, not glob. -### Common Patterns +### Source Matching (SessionStart, SessionEnd, PreCompact, PostCompact, ConfigChange, StopFailure) -```json -// All MCP tools -"matcher": "mcp__.*" +These events match on a `source` or category value, not tool names. See each event's documentation for valid matcher values. -// Specific plugin's MCP tools -"matcher": "mcp__plugin_asana_.*" +### Agent Type Matching (SubagentStart, SubagentStop) -// All file operations -"matcher": "Read|Write|Edit" +Match on agent type names: built-in types (`Bash`, `Explore`, `Plan`) or custom agent names from plugins. -// Bash commands only -"matcher": "Bash" -``` +### MCP Server Matching (Elicitation, ElicitationResult) + +Match on MCP server name. + +### Events Without Matcher Support + +These events ignore the `matcher` field: UserPromptSubmit, Stop, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove. + +## Hook Type Support by Event + +Not all events support all four hook types: + +| Event | Command | HTTP | Prompt | Agent | +| ------------------ | ------- | ---- | ------ | ----- | +| SessionStart | Yes | -- | -- | -- | +| InstructionsLoaded | Yes | Yes | Yes | Yes | +| SessionEnd | Yes | Yes | Yes | Yes | +| UserPromptSubmit | Yes | Yes | Yes | Yes | +| PreToolUse | Yes | Yes | Yes | Yes | +| PermissionRequest | Yes | Yes | Yes | Yes | +| PostToolUse | Yes | Yes | Yes | Yes | +| PostToolUseFailure | Yes | Yes | Yes | Yes | +| Stop | Yes | Yes | Yes | Yes | +| StopFailure | Yes | Yes | Yes | Yes | +| SubagentStart | Yes | Yes | Yes | Yes | +| SubagentStop | Yes | Yes | Yes | Yes | +| TeammateIdle | Yes | Yes | Yes | Yes | +| TaskCompleted | Yes | Yes | Yes | Yes | +| PreCompact | Yes | Yes | Yes | Yes | +| PostCompact | Yes | Yes | Yes | Yes | +| ConfigChange | Yes | Yes | Yes | Yes | +| WorktreeCreate | Yes | -- | -- | -- | +| WorktreeRemove | Yes | -- | -- | -- | +| Elicitation | Yes | Yes | Yes | Yes | +| ElicitationResult | Yes | Yes | Yes | Yes | +| Notification | Yes | Yes | Yes | Yes | + +## Hook Configuration Locations + +| Location | Scope | Shareable | +| ------------------------------- | -------------- | --------------------- | +| `~/.claude/settings.json` | All projects | No | +| `.claude/settings.json` | Single project | Yes (commit to repo) | +| `.claude/settings.local.json` | Single project | No | +| Managed policy settings | Organization | Yes (admin-managed) | +| Plugin `hooks/hooks.json` | Plugin-scoped | Yes (with plugin) | + +Plugin hooks merge with user hooks. All matching hooks run in parallel. Duplicate hooks are deduplicated (command hooks by command string, HTTP hooks by URL). + +**`disableAllHooks` in settings cannot disable managed policy hooks.** ## Security Best Practices @@ -617,7 +910,7 @@ cd $CLAUDE_PROJECT_DIR } ``` -**Defaults:** Command hooks (60s), Prompt hooks (30s) +**Defaults:** Command (60s), Prompt (30s), HTTP (30s), Agent (60s) ## Performance Considerations @@ -631,9 +924,9 @@ All matching hooks run **in parallel**: { "matcher": "Write", "hooks": [ - { "type": "command", "command": "check1.sh" }, // Parallel - { "type": "command", "command": "check2.sh" }, // Parallel - { "type": "prompt", "prompt": "Validate..." } // Parallel + { "type": "command", "command": "check1.sh" }, + { "type": "command", "command": "check2.sh" }, + { "type": "prompt", "prompt": "Validate..." } ] } ] @@ -652,6 +945,8 @@ All matching hooks run **in parallel**: 2. Use prompt hooks for complex reasoning 3. Cache validation results in temp files 4. Minimize I/O in hot paths +5. Use `async: true` for logging hooks that don't need to block +6. Use `once: true` for one-time setup hooks ## Hook Lifecycle and Limitations @@ -661,9 +956,8 @@ All matching hooks run **in parallel**: **Cannot hot-swap hooks:** -- Editing `hooks/hooks.json` won't affect current session +- Editing `hooks/hooks.json` won't affect the current session - Adding new hook scripts won't be recognized -- Changing hook commands/prompts won't update - Must restart Claude Code: exit and run `claude` again **To test hook changes:** @@ -682,7 +976,7 @@ Hooks are validated when Claude Code starts: - Missing scripts cause warnings - Syntax errors reported in debug mode -Use `/hooks` command to review loaded hooks in current session. +Use `/hooks` command to review loaded hooks in the current session. ## Debugging Hooks @@ -716,44 +1010,45 @@ echo "$output" | jq . ## Quick Reference -### Hook Events Summary - -| 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 | -| PostToolUseFailure | After tool fails | Error handling | -| UserPromptSubmit | User input | Context, validation | -| Stop | Agent stopping | Completeness check | -| SubagentStart | Subagent begins | Subagent setup | -| SubagentStop | Subagent done | Task validation | -| SessionStart | Session begins | Context loading | -| SessionEnd | Session ends | Cleanup, logging | -| PreCompact | Before compact | Preserve context | -| Notification | User notified | Logging, reactions | - -### Best Practices - -**DO:** - -- ✅ Use prompt-based hooks for complex logic -- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability -- ✅ Validate all inputs in command hooks -- ✅ Quote all bash variables -- ✅ Set appropriate timeouts -- ✅ Return structured JSON output -- ✅ Test hooks thoroughly - -**DON'T:** - -- ❌ Use hardcoded paths -- ❌ Trust user input without validation -- ❌ Create long-running hooks -- ❌ Rely on hook execution order -- ❌ Modify global state unpredictably -- ❌ Log sensitive information +### All 22 Hook Events + +| Event | Category | Matchers | Decision Control | +| ------------------ | ------------- | --------------------------- | ----------------------------- | +| SessionStart | Lifecycle | startup, resume, clear, compact | continue, env vars | +| InstructionsLoaded | Lifecycle | session_start, nested_traversal, path_glob_match, include, compact | None (observability) | +| SessionEnd | Lifecycle | clear, logout, prompt_input_exit, bypass_permissions_disabled, other | None (observability) | +| UserPromptSubmit | Input | None | Block prompt | +| PreToolUse | Tool | Tool names (regex) | Allow/deny/ask, modify input | +| PermissionRequest | Tool | Tool names (regex) | Allow/deny, modify input | +| PostToolUse | Tool | Tool names (regex) | Block, modify MCP output | +| PostToolUseFailure | Tool | Tool names (regex) | Context injection | +| Stop | Turn | None | Block stop | +| StopFailure | Turn | Error types | None (observability) | +| SubagentStart | Subagent | Agent type names | Context injection | +| SubagentStop | Subagent | Agent type names | Block stop | +| TeammateIdle | Teams | None | Reject idle (exit 2), stop | +| TaskCompleted | Teams | None | Reject completion (exit 2) | +| PreCompact | Context | manual, auto | None (observability) | +| PostCompact | Context | manual, auto | None (observability) | +| ConfigChange | Config | Settings sources | Block (except policy) | +| WorktreeCreate | Worktree | None | Stdout = path, exit code | +| WorktreeRemove | Worktree | None | None (cleanup) | +| Elicitation | MCP | MCP server name | Accept/decline/cancel | +| ElicitationResult | MCP | MCP server name | Override response | +| Notification | Notification | Notification types | None (observability) | + +### Critical Gotchas + +1. **No "Setup" event.** Use `SessionStart` with matcher `startup` for initialization. +2. **Shell profile noise breaks JSON parsing.** If `.bashrc`/`.zshrc` prints text, it contaminates stdout. +3. **SessionEnd has a 1.5s timeout.** Set `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` for longer cleanup. +4. **Duplicate hooks are deduplicated.** Command hooks by command string, HTTP hooks by URL. +5. **PreToolUse deprecated fields.** Old `decision: "approve|block"` replaced by `hookSpecificOutput.permissionDecision`. +6. **Policy settings cannot be blocked.** ConfigChange hooks for `policy_settings` silently ignore block decisions. +7. **Async hooks cannot block.** Exit code 2 is ignored for `async: true` hooks. +8. **Subagent Stop hooks auto-convert.** Stop hooks in subagent context become SubagentStop. +9. **HTTP hooks need 2xx for decisions.** Non-2xx status codes are treated as non-blocking errors. +10. **`disableAllHooks` cannot disable managed hooks.** Policy-managed hooks always run. ## Additional Resources @@ -761,9 +1056,10 @@ echo "$output" | jq . For detailed patterns and advanced techniques, consult: -- **`references/patterns.md`** - 10 proven patterns including temporarily active and configuration-driven hooks -- **`references/migration.md`** - Migrating from basic to advanced hooks -- **`references/advanced.md`** - Advanced use cases and techniques +- **`references/event-schemas.md`** -- Complete input/output JSON schemas for all 22 events +- **`references/patterns.md`** -- Proven patterns including temporarily active and configuration-driven hooks +- **`references/migration.md`** -- Migrating from basic to advanced hooks +- **`references/advanced.md`** -- Advanced use cases and techniques ### Example Hook Scripts @@ -771,9 +1067,9 @@ Working examples in `examples/`: > **Note:** After copying example scripts, make them executable: `chmod +x script.sh` -- **`validate-write.sh`** - File write validation example -- **`validate-bash.sh`** - Bash command validation example -- **`load-context.sh`** - SessionStart context loading example +- **`validate-write.sh`** -- File write validation example +- **`validate-bash.sh`** -- Bash command validation example +- **`load-context.sh`** -- SessionStart context loading example ### Utility Scripts @@ -781,14 +1077,13 @@ Working examples in `examples/`: Development tools in `scripts/`: -- **`validate-hook-schema.sh`** - Validate hooks.json structure and syntax -- **`test-hook.sh`** - Test hooks with sample input before deployment -- **`hook-linter.sh`** - Check hook scripts for common issues and best practices +- **`validate-hook-schema.sh`** -- Validate hooks.json structure and syntax +- **`test-hook.sh`** -- Test hooks with sample input before deployment +- **`hook-linter.sh`** -- Check hook scripts for common issues and best practices ### External Resources -- **Official Docs**: -- **Examples**: See security-guidance plugin in marketplace +- **Official Docs**: - **Testing**: Use `claude --debug` for detailed logs - **Validation**: Use `jq` to validate hook JSON output @@ -796,14 +1091,12 @@ Development tools in `scripts/`: To implement hooks in a plugin: -1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.) -2. Decide between prompt-based (flexible) or command (deterministic) hooks +1. Identify events to hook into (see [Quick Reference](#all-22-hook-events)) +2. Decide hook type: prompt (flexible), agent (multi-step), command (deterministic), or HTTP (external) 3. Write hook configuration in `hooks/hooks.json` 4. For command hooks, create hook scripts -5. Use ${CLAUDE_PLUGIN_ROOT} for all file references +5. Use `${CLAUDE_PLUGIN_ROOT}` for all file references 6. Validate configuration with `scripts/validate-hook-schema.sh hooks/hooks.json` 7. Test hooks with `scripts/test-hook.sh` before deployment 8. Test in Claude Code with `claude --debug` 9. Document hooks in plugin README - -Focus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks. diff --git a/plugins/plugin-dev/skills/hook-development/references/event-schemas.md b/plugins/plugin-dev/skills/hook-development/references/event-schemas.md new file mode 100644 index 0000000..039eec7 --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/references/event-schemas.md @@ -0,0 +1,892 @@ +# Hook Event Schemas Reference + +Complete input and output JSON schemas for all 22 Claude Code hook events. + +**Last verified:** 2026-03-20 against official docs, Python SDK (`claude-agent-sdk`), and TypeScript SDK. + +## Common Fields + +### Base Input (all events) + +```json +{ + "session_id": "string", + "transcript_path": "string (path to transcript JSONL)", + "cwd": "string (current working directory)", + "hook_event_name": "string (event discriminant)", + "permission_mode": "default|plan|acceptEdits|dontAsk|bypassPermissions" +} +``` + +`permission_mode` is present on most events but not all (notably absent from SessionStart and InstructionsLoaded). + +When running inside a subagent, these additional fields are present: + +```json +{ + "agent_id": "string", + "agent_type": "string" +} +``` + +### Base Output (all events) + +All fields are optional. Omitted fields use defaults. + +```json +{ + "continue": true, + "stopReason": "string (shown when continue is false)", + "suppressOutput": false, + "decision": "block", + "reason": "string (feedback to Claude when decision is block)", + "systemMessage": "string (warning displayed to user)", + "hookSpecificOutput": { + "hookEventName": "string", + "additionalContext": "string (injected into Claude's context)" + } +} +``` + +### Exit Code Semantics + +| Code | Behavior | +| ----- | -------------------------------------------------------- | +| 0 | Success. stdout parsed as JSON if present | +| 2 | Blocking error. stderr content fed to Claude or user | +| Other | Non-blocking error. Shown in verbose/debug mode only | + +--- + +## Session Lifecycle + +### SessionStart + +**When:** New session, resume (`--resume`/`--continue`/`/resume`), `/clear`, or after compaction. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "SessionStart", + "source": "startup|resume|clear|compact", + "model": "string (model ID)", + "agent_type": "string (optional, present with --agent)" +} +``` + +Note: `permission_mode` is not present on SessionStart. + +**Output:** + +```json +{ + "continue": true, + "stopReason": "string (optional)", + "suppressOutput": false, + "systemMessage": "string (optional)", + "hookSpecificOutput": { + "hookEventName": "SessionStart", + "additionalContext": "string (optional)" + } +} +``` + +**Special behavior:** The `CLAUDE_ENV_FILE` environment variable points to a file where you can write `export VAR=value` lines. These persist as environment variables for subsequent Bash tool calls in the session. + +**Matchers:** `startup`, `resume`, `clear`, `compact` +**Hook types:** Command only + +--- + +### InstructionsLoaded + +**When:** CLAUDE.md or `.claude/rules/*.md` files are loaded into context (at session start or lazily during traversal). + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "InstructionsLoaded", + "file_path": "string (path to the loaded file)", + "memory_type": "User|Project|Local|Managed", + "load_reason": "session_start|nested_traversal|path_glob_match|include|compact", + "globs": ["string (optional, glob patterns that triggered the load)"], + "trigger_file_path": "string (optional, file whose access triggered glob match)", + "parent_file_path": "string (optional, file that included this one)" +} +``` + +**Output:** Observability only. No decision control. Runs asynchronously. + +**Matchers:** `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### SessionEnd + +**When:** Session terminates. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "SessionEnd", + "reason": "clear|logout|prompt_input_exit|bypass_permissions_disabled|resume|other" +} +``` + +**Output:** Observability only. No decision control. + +**Default timeout:** 1.5 seconds. Override with `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` environment variable (set in milliseconds). + +**Matchers:** `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `resume`, `other` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## User Input + +### UserPromptSubmit + +**When:** User submits a prompt, before Claude processes it. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "UserPromptSubmit", + "prompt": "string (the user's input)" +} +``` + +**Output:** + +```json +{ + "decision": "block", + "reason": "string (shown to user when blocking)", + "continue": true, + "stopReason": "string (optional)", + "hookSpecificOutput": { + "hookEventName": "UserPromptSubmit", + "additionalContext": "string (optional)" + } +} +``` + +**Matchers:** Not supported (matcher field is silently ignored). +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Tool Lifecycle + +### PreToolUse + +**When:** After Claude creates tool parameters, before execution. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "PreToolUse", + "tool_name": "string", + "tool_input": { + "command": "string (Bash)", + "file_path": "string (Write/Edit/Read)", + "old_string": "string (Edit)", + "new_string": "string (Edit)", + "content": "string (Write)", + "pattern": "string (Glob/Grep)", + "url": "string (WebFetch)", + "query": "string (WebSearch)", + "prompt": "string (Agent)" + }, + "tool_use_id": "string" +} +``` + +`tool_input` fields vary by tool. The above shows common fields; MCP tools have server-defined inputs. + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow|deny|ask", + "permissionDecisionReason": "string (optional)", + "updatedInput": { + "command": "string (modified tool input)" + }, + "additionalContext": "string (optional)" + } +} +``` + +- `permissionDecision`: `"allow"` approves without prompting, `"deny"` blocks execution, `"ask"` shows permission dialog +- `permissionDecisionReason`: Explanation logged for the decision +- `updatedInput`: Replace specific tool_input fields (merged, not replaced wholesale) +- `additionalContext`: Injected into Claude's context for this tool call + +**Deprecated fields:** Top-level `decision: "approve|block"` still works but `hookSpecificOutput.permissionDecision` takes precedence. + +**Matchers:** Tool names. Supports regex: `"Write|Edit"`, `"mcp__.*__delete.*"` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### PermissionRequest + +**When:** A permission dialog is about to be shown to the user. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "PermissionRequest", + "tool_name": "string", + "tool_input": {}, + "permission_suggestions": [ + { + "type": "addRules|replaceRules|removeRules|setMode|addDirectories|removeDirectories", + "rules": [], + "behavior": "allow|deny|ask", + "destination": "session|localSettings|projectSettings|userSettings", + "mode": "string (optional)" + } + ] +} +``` + +- `permission_suggestions`: The "always allow" options that would normally be shown to the user in the permission dialog + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionRequest", + "decision": { + "behavior": "allow|deny", + "updatedInput": {}, + "updatedPermissions": [ + { + "type": "addRules|replaceRules", + "rules": [], + "destination": "session|localSettings|projectSettings|userSettings" + } + ], + "message": "string (deny only)", + "interrupt": false + } + } +} +``` + +- `behavior`: `"allow"` approves, `"deny"` rejects +- `updatedInput`: Modify tool parameters (allow only) +- `updatedPermissions`: Apply permission changes so user isn't prompted again (allow only) +- `message`: Reason for denial, shown to user (deny only) +- `interrupt`: If true, stops Claude entirely (deny only) + +**Known issue:** `additionalContext` is parsed but silently dropped ([anthropics/claude-code#28035](https://github.com/anthropics/claude-code/issues/28035)). + +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### PostToolUse + +**When:** After tool execution succeeds. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "PostToolUse", + "tool_name": "string", + "tool_input": {}, + "tool_response": "any (tool's return value)", + "tool_use_id": "string" +} +``` + +**Output:** + +```json +{ + "decision": "block", + "reason": "string (when blocking)", + "hookSpecificOutput": { + "hookEventName": "PostToolUse", + "additionalContext": "string (optional)", + "updatedMCPToolOutput": "any (MCP tools only)" + } +} +``` + +- `updatedMCPToolOutput`: For MCP tools, replaces the tool's response before Claude sees it + +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### PostToolUseFailure + +**When:** After tool execution fails. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "PostToolUseFailure", + "tool_name": "string", + "tool_input": {}, + "tool_use_id": "string", + "error": "string (error message)", + "is_interrupt": false +} +``` + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PostToolUseFailure", + "additionalContext": "string (optional)" + } +} +``` + +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Turn Control + +### Stop + +**When:** Main agent finishes responding (not fired on user interrupt). + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "Stop", + "stop_hook_active": true, + "last_assistant_message": "string" +} +``` + +- `stop_hook_active`: Whether a Stop hook is currently processing (prevents infinite recursion) + +**Output:** + +```json +{ + "decision": "block", + "reason": "string (required when blocking -- fed back to Claude as instructions)" +} +``` + +When `decision` is `"block"`, Claude receives `reason` as feedback and attempts another turn. + +**Matchers:** Not supported. +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### StopFailure + +**When:** Turn ends due to an API error (rate limit, auth failure, billing, server error). + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "StopFailure", + "error": "string (error category)", + "error_details": "string (optional, detailed error message)", + "last_assistant_message": "string" +} +``` + +**Output:** Ignored. This is an observability-only event. Output and exit codes have no effect. + +**Matchers:** `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, `unknown` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Subagents + +### SubagentStart + +**When:** A subagent is spawned via the Agent tool. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "SubagentStart", + "agent_id": "string", + "agent_type": "string" +} +``` + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "SubagentStart", + "additionalContext": "string (optional, injected into subagent context)" + } +} +``` + +**Matchers:** Agent type names (`Bash`, `Explore`, `Plan`, or custom agent names from plugins) +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### SubagentStop + +**When:** A subagent finishes responding. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "SubagentStop", + "stop_hook_active": true, + "agent_id": "string", + "agent_type": "string", + "agent_transcript_path": "string (path to subagent's transcript)", + "last_assistant_message": "string" +} +``` + +**Output:** + +```json +{ + "decision": "block", + "reason": "string (required when blocking -- fed back to subagent)" +} +``` + +Same semantics as Stop: blocking causes the subagent to continue working with `reason` as feedback. + +**Note:** Stop hooks defined in a subagent context automatically convert to SubagentStop events. + +**Matchers:** Agent type names (same as SubagentStart) +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Teams + +### TeammateIdle + +**When:** An agent team teammate is about to go idle. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "TeammateIdle", + "teammate_name": "string", + "team_name": "string" +} +``` + +**Output:** Two feedback mechanisms: + +1. **Exit code 2:** Teammate receives stderr as feedback and continues working (does not go idle) +2. **JSON `{"continue": false, "stopReason": "..."}`:** Teammate stops entirely + +Normal exit (code 0) with no blocking output allows the teammate to go idle. + +**Matchers:** Not supported. +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### TaskCompleted + +**When:** A task is marked as completed (explicitly or at end-of-turn). + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "TaskCompleted", + "task_id": "string", + "task_subject": "string", + "task_description": "string (optional)", + "teammate_name": "string (optional)", + "team_name": "string (optional)" +} +``` + +**Output:** Two feedback mechanisms (same as TeammateIdle): + +1. **Exit code 2:** Task NOT marked complete. stderr fed back as feedback; agent continues working +2. **JSON `{"continue": false, "stopReason": "..."}`:** Teammate stops entirely + +Normal exit allows the task completion to proceed. + +**Matchers:** Not supported. +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Context Management + +### PreCompact + +**When:** Before context compaction starts. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "PreCompact", + "trigger": "manual|auto", + "custom_instructions": "string (user-provided compaction instructions, if any)" +} +``` + +**Output:** Observability only. No decision control. + +Use `additionalContext` to inject information that should be considered during compaction. + +**Matchers:** `manual`, `auto` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### PostCompact + +**When:** After context compaction completes. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "PostCompact", + "trigger": "manual|auto", + "compact_summary": "string (the compaction result summary)" +} +``` + +**Output:** Observability only. No decision control. + +Use to verify what survived compaction, log compaction results, or send alerts if critical context was lost. + +**Matchers:** `manual`, `auto` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Configuration + +### ConfigChange + +**When:** A configuration file changes during a session. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "ConfigChange", + "source": "user_settings|project_settings|local_settings|policy_settings|skills", + "file_path": "string (optional, path to the changed file)" +} +``` + +**Output:** + +```json +{ + "decision": "block", + "reason": "string (when blocking)" +} +``` + +**Important:** Block decisions for `policy_settings` source are silently ignored. Policy changes cannot be blocked. + +**Matchers:** `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Worktrees + +### WorktreeCreate + +**When:** A git worktree is created via `--worktree` flag or subagent with `isolation: "worktree"`. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "WorktreeCreate", + "name": "string (worktree identifier)" +} +``` + +**Output:** This event is unique -- stdout is the return value, not JSON. + +- **stdout:** Must print the **absolute path** to the created worktree directory +- **Exit code 0:** Worktree creation succeeds using the printed path +- **Non-zero exit code:** Worktree creation fails + +This is the only hook where the output is a plain path string rather than JSON. + +**Matchers:** Not supported. +**Hook types:** Command only. + +--- + +### WorktreeRemove + +**When:** A worktree is being removed (session exit or subagent finish). + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "WorktreeRemove", + "worktree_path": "string (absolute path to worktree being removed)" +} +``` + +**Output:** Cleanup only. Output and exit code are ignored. + +**Matchers:** Not supported. +**Hook types:** Command only. + +--- + +## MCP Elicitation + +### Elicitation + +**When:** An MCP server requests user input mid-task via the elicitation protocol. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "Elicitation", + "mcp_server_name": "string", + "message": "string (prompt from the MCP server)", + "mode": "form|url (optional)", + "url": "string (optional, for URL-mode elicitations)", + "elicitation_id": "string (optional)", + "requested_schema": { + "type": "object", + "properties": {}, + "required": [] + } +} +``` + +- `mode`: `"form"` for structured input, `"url"` for URL-based authentication flows +- `requested_schema`: JSON Schema describing what the MCP server expects back + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "Elicitation", + "action": "accept|decline|cancel", + "content": { + "field_name": "value" + } + } +} +``` + +- `accept`: Provide response matching `requested_schema` via `content` +- `decline`: Reject the elicitation request +- `cancel`: Cancel the entire MCP operation + +**Matchers:** MCP server name +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +### ElicitationResult + +**When:** After a user responds to an MCP elicitation, before the response is sent back to the MCP server. + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "ElicitationResult", + "mcp_server_name": "string", + "elicitation_id": "string", + "user_response": { + "field_name": "value" + } +} +``` + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "ElicitationResult", + "action": "accept|decline|cancel", + "content": { + "field_name": "overridden value" + } + } +} +``` + +- `accept` with `content`: Override the user's response +- `accept` without `content`: Pass through user's response unchanged +- `decline` or `cancel`: Reject or cancel the operation + +**Matchers:** MCP server name +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## Notifications + +### Notification + +**When:** Claude Code sends a notification (permission prompt, idle prompt, auth event, elicitation dialog). + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "hook_event_name": "Notification", + "message": "string", + "title": "string (optional)", + "notification_type": "string" +} +``` + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "Notification", + "additionalContext": "string (optional)" + } +} +``` + +Observability only. No decision control. + +**Matchers:** `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` +**Hook types:** Command, HTTP, Prompt, Agent + +--- + +## SDK Parity Notes + +Not all events are typed in both SDKs. As of March 2026: + +**Python SDK** (`claude-agent-sdk`) types 10 of 22 events: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification, SubagentStart, PermissionRequest. + +**TypeScript SDK** (`@anthropic-ai/claude-agent-sdk`) is closer to parity with the CLI. Events added over time: TeammateIdle and TaskCompleted (v2.1.34), ConfigChange (v0.2.49), Elicitation and ElicitationResult (v0.2.76). + +**CLI** supports all 22 events. + +Events only available in CLI (not yet in either SDK): WorktreeCreate, WorktreeRemove, PostCompact, InstructionsLoaded, StopFailure. diff --git a/plugins/plugin-dev/skills/hook-development/references/patterns.md b/plugins/plugin-dev/skills/hook-development/references/patterns.md index fe4580b..1c79e49 100644 --- a/plugins/plugin-dev/skills/hook-development/references/patterns.md +++ b/plugins/plugin-dev/skills/hook-development/references/patterns.md @@ -350,3 +350,368 @@ fi - Per-project settings - Team-specific rules - Dynamic validation criteria + +## Pattern 11: API Error Alerting (StopFailure) + +Send alerts when Claude encounters API errors: + +```json +{ + "StopFailure": [ + { + "matcher": "rate_limit|authentication_failed|billing_error", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/alert-api-error.sh" + } + ] + } + ] +} +``` + +**Example script (alert-api-error.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +input=$(cat) +error=$(echo "$input" | jq -r '.error') +details=$(echo "$input" | jq -r '.error_details // "none"') +session_id=$(echo "$input" | jq -r '.session_id') + +# Log to file +echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] ERROR=$error DETAILS=$details SESSION=$session_id" \ + >> "$CLAUDE_PROJECT_DIR/.claude/api-errors.log" + +# Send notification (adapt to your alerting system) +if command -v osascript &>/dev/null; then + osascript -e "display notification \"$error: $details\" with title \"Claude Code API Error\"" +fi +``` + +**Use for:** Monitoring rate limits, detecting auth expiry, tracking billing issues. + +## Pattern 12: Task Completion Validation (TaskCompleted) + +Verify task deliverables before marking complete: + +```json +{ + "TaskCompleted": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-task.sh" + } + ] + } + ] +} +``` + +**Example script (validate-task.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +input=$(cat) +task_subject=$(echo "$input" | jq -r '.task_subject') +task_description=$(echo "$input" | jq -r '.task_description // ""') + +# Check if tests pass for code-related tasks +if echo "$task_subject" | grep -qiE 'implement|fix|refactor|add|create'; then + if ! make test 2>/dev/null && ! npm test 2>/dev/null; then + echo "Tests must pass before completing task: $task_subject" >&2 + exit 2 # Reject completion, agent continues + fi +fi +``` + +**Use for:** Enforcing quality gates on agent team output, requiring tests before task completion. + +## Pattern 13: Teammate Quality Gate (TeammateIdle) + +Prevent teammates from going idle until their work meets standards: + +```json +{ + "TeammateIdle": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "A teammate is about to go idle. Review their last message to verify work was completed to a high standard. If there are obvious gaps (missing tests, incomplete implementation, TODOs left), reject with specific feedback." + } + ] + } + ] +} +``` + +**Use for:** Quality assurance in multi-agent workflows, preventing premature completion. + +## Pattern 14: Custom Worktree Management (WorktreeCreate/Remove) + +Manage worktrees with custom setup and cleanup: + +```json +{ + "WorktreeCreate": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/create-worktree.sh" + } + ] + } + ], + "WorktreeRemove": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-worktree.sh" + } + ] + } + ] +} +``` + +**Example script (create-worktree.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +input=$(cat) +name=$(echo "$input" | jq -r '.name') + +# Create worktree in a custom location +worktree_dir="/tmp/claude-worktrees/$name" +git worktree add "$worktree_dir" -b "worktree/$name" HEAD + +# Install dependencies in the new worktree +cd "$worktree_dir" +if [ -f "package.json" ]; then + npm ci --silent 2>/dev/null || true +fi + +# Print the path -- this is the return value +echo "$worktree_dir" +``` + +**Example script (cleanup-worktree.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +input=$(cat) +worktree_path=$(echo "$input" | jq -r '.worktree_path') + +# Custom cleanup before removal +if [ -d "$worktree_path/node_modules" ]; then + rm -rf "$worktree_path/node_modules" +fi + +# Remove the git worktree +git worktree remove "$worktree_path" --force 2>/dev/null || true +``` + +**Use for:** Custom worktree locations, dependency installation, cleanup of build artifacts. + +## Pattern 15: Config Change Monitoring (ConfigChange) + +Monitor and validate configuration changes for security: + +```json +{ + "ConfigChange": [ + { + "matcher": "project_settings|local_settings", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/audit-config-change.sh" + } + ] + } + ] +} +``` + +**Example script (audit-config-change.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +input=$(cat) +source=$(echo "$input" | jq -r '.source') +file_path=$(echo "$input" | jq -r '.file_path // "unknown"') + +# Log the change +echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] CONFIG_CHANGE source=$source file=$file_path" \ + >> "$CLAUDE_PROJECT_DIR/.claude/config-audit.log" + +# Block permission escalations in project settings +if [ "$source" = "project_settings" ] && [ -f "$file_path" ]; then + if jq -e '.permissions' "$file_path" >/dev/null 2>&1; then + echo "Permission changes in project settings require manual review" >&2 + exit 2 + fi +fi +``` + +**Use for:** Security auditing, preventing unauthorized permission changes, change tracking. + +## Pattern 16: MCP Elicitation Auto-Response (Elicitation) + +Auto-respond to known MCP server prompts: + +```json +{ + "Elicitation": [ + { + "matcher": "my-auth-server", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/handle-auth-elicitation.sh" + } + ] + } + ] +} +``` + +**Example script (handle-auth-elicitation.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +input=$(cat) +message=$(echo "$input" | jq -r '.message') +mode=$(echo "$input" | jq -r '.mode // "form"') + +# Auto-handle URL-based auth flows +if [ "$mode" = "url" ]; then + url=$(echo "$input" | jq -r '.url // ""') + if [ -n "$url" ]; then + # Open in browser for the user + open "$url" 2>/dev/null || xdg-open "$url" 2>/dev/null || true + fi + # Decline -- user will complete auth in browser + echo '{"hookSpecificOutput": {"hookEventName": "Elicitation", "action": "decline"}}' + exit 0 +fi + +# Auto-respond to known form prompts +if echo "$message" | grep -qi "confirm"; then + echo '{"hookSpecificOutput": {"hookEventName": "Elicitation", "action": "accept", "content": {"confirmed": true}}}' + exit 0 +fi + +# Unknown prompt -- let user handle it +exit 0 +``` + +**Use for:** Automating auth flows, auto-confirming known prompts, filtering elicitation requests. + +## Pattern 17: Compaction Monitoring (PreCompact/PostCompact) + +Track what happens during context compaction: + +```json +{ + "PreCompact": [ + { + "matcher": "auto", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-compact.sh pre" + } + ] + } + ], + "PostCompact": [ + { + "matcher": "auto", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-compact.sh post" + } + ] + } + ] +} +``` + +**Example script (log-compact.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +phase="$1" # "pre" or "post" +input=$(cat) +trigger=$(echo "$input" | jq -r '.trigger') + +log_file="$CLAUDE_PROJECT_DIR/.claude/compaction.log" + +if [ "$phase" = "pre" ]; then + echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] COMPACT_START trigger=$trigger" >> "$log_file" +elif [ "$phase" = "post" ]; then + summary_length=$(echo "$input" | jq -r '.compact_summary | length') + echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] COMPACT_END trigger=$trigger summary_chars=$summary_length" >> "$log_file" +fi +``` + +**Use for:** Debugging context loss, monitoring compaction frequency, auditing what information survives. + +## Pattern 18: Instruction Loading Audit (InstructionsLoaded) + +Track which instruction files Claude loads and when: + +```json +{ + "InstructionsLoaded": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-instructions.sh", + "async": true + } + ] + } + ] +} +``` + +**Example script (log-instructions.sh):** + +```bash +#!/bin/bash +set -euo pipefail + +input=$(cat) +file_path=$(echo "$input" | jq -r '.file_path') +memory_type=$(echo "$input" | jq -r '.memory_type') +load_reason=$(echo "$input" | jq -r '.load_reason') + +echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] LOADED type=$memory_type reason=$load_reason path=$file_path" \ + >> "$CLAUDE_PROJECT_DIR/.claude/instructions-audit.log" +``` + +**Use for:** Understanding which instructions Claude sees, debugging instruction loading order, verifying that rules files are picked up correctly. diff --git a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh index e05e713..9c77e78 100755 --- a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh +++ b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh @@ -38,7 +38,7 @@ echo "✅ Valid JSON" # Check 2: Root structure echo "" echo "Checking root structure..." -VALID_EVENTS=("PreToolUse" "PermissionRequest" "PostToolUse" "UserPromptSubmit" "Stop" "SubagentStop" "SessionStart" "SessionEnd" "PreCompact" "Notification") +VALID_EVENTS=("SessionStart" "InstructionsLoaded" "SessionEnd" "UserPromptSubmit" "PreToolUse" "PermissionRequest" "PostToolUse" "PostToolUseFailure" "Stop" "StopFailure" "SubagentStart" "SubagentStop" "TeammateIdle" "TaskCompleted" "PreCompact" "PostCompact" "ConfigChange" "WorktreeCreate" "WorktreeRemove" "Elicitation" "ElicitationResult" "Notification") for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do found=false @@ -65,7 +65,7 @@ warning_count=0 for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do hook_count=$(jq -r ".\"$event\" | length" "$HOOKS_FILE") - for ((i=0; i Date: Fri, 20 Mar 2026 12:07:07 +1300 Subject: [PATCH 04/33] chore: sync plugin structure with official conventions - Add version field to all 9 skill frontmatters - Use YAML block scalars (|) for multi-line agent descriptions to fix YAML parsing errors (matches official repo fix) - Add commands/ deprecation notice to command-development and plugin-structure skills, pointing to skills//SKILL.md format - Update command-development overview wording for consistency --- plugins/plugin-dev/agents/agent-creator.md | 77 +++++++++---------- plugins/plugin-dev/agents/plugin-validator.md | 75 +++++++++--------- plugins/plugin-dev/agents/skill-reviewer.md | 75 +++++++++--------- .../skills/agent-development/SKILL.md | 1 + .../skills/command-development/SKILL.md | 5 +- .../skills/lsp-integration/SKILL.md | 1 + .../skills/marketplace-structure/SKILL.md | 1 + .../skills/mcp-integration/SKILL.md | 1 + .../skills/plugin-settings/SKILL.md | 1 + .../skills/plugin-structure/SKILL.md | 5 +- .../skills/skill-development/SKILL.md | 1 + 11 files changed, 128 insertions(+), 115 deletions(-) diff --git a/plugins/plugin-dev/agents/agent-creator.md b/plugins/plugin-dev/agents/agent-creator.md index df43b88..a90a7d6 100644 --- a/plugins/plugin-dev/agents/agent-creator.md +++ b/plugins/plugin-dev/agents/agent-creator.md @@ -1,44 +1,43 @@ --- name: agent-creator -description: Use this agent when the user asks to "create an agent", "generate an agent", "build a new agent", "make me an agent that...", or describes agent functionality they need. Trigger when user wants to create autonomous agents for plugins. Examples: - - -Context: User wants to create a code review agent -user: "Create an agent that reviews code for quality issues" -assistant: "I'll use the agent-creator agent to generate the agent configuration." - -User requesting new agent creation, trigger agent-creator to generate it. - - - - -Context: User describes needed functionality -user: "I need an agent that generates unit tests for my code" -assistant: "I'll use the agent-creator agent to create a test generation agent." - -User describes agent need, trigger agent-creator to build it. - - - - -Context: User wants to add agent to plugin -user: "Add an agent to my plugin that validates configurations" -assistant: "I'll use the agent-creator agent to generate a configuration validator agent." - -Plugin development with agent addition, trigger agent-creator. - - - - -Context: User describes needing autonomous functionality while discussing plugin development -user: "My plugin needs something to automatically review code after I write it" -assistant: "I'll use the agent-creator agent to generate a code review agent for your plugin." - -User describes agent-like functionality need without explicitly requesting agent creation, proactively trigger agent-creator. - - - -# Explicit sonnet for complex agent generation reasoning +description: | + Use this agent when the user asks to "create an agent", "generate an agent", "build a new agent", "make me an agent that...", or describes agent functionality they need. Trigger when user wants to create autonomous agents for plugins. Examples: + + + Context: User wants to create a code review agent + user: "Create an agent that reviews code for quality issues" + assistant: "I'll use the agent-creator agent to generate the agent configuration." + + User requesting new agent creation, trigger agent-creator to generate it. + + + + + Context: User describes needed functionality + user: "I need an agent that generates unit tests for my code" + assistant: "I'll use the agent-creator agent to create a test generation agent." + + User describes agent need, trigger agent-creator to build it. + + + + + Context: User wants to add agent to plugin + user: "Add an agent to my plugin that validates configurations" + assistant: "I'll use the agent-creator agent to generate a configuration validator agent." + + Plugin development with agent addition, trigger agent-creator. + + + + + Context: User describes needing autonomous functionality while discussing plugin development + user: "My plugin needs something to automatically review code after I write it" + assistant: "I'll use the agent-creator agent to generate a code review agent for your plugin." + + User describes agent-like functionality need without explicitly requesting agent creation, proactively trigger agent-creator. + + model: sonnet color: magenta tools: Write, Read, Glob diff --git a/plugins/plugin-dev/agents/plugin-validator.md b/plugins/plugin-dev/agents/plugin-validator.md index 9b50a11..a8efa1e 100644 --- a/plugins/plugin-dev/agents/plugin-validator.md +++ b/plugins/plugin-dev/agents/plugin-validator.md @@ -1,42 +1,43 @@ --- name: plugin-validator -description: Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", "validate marketplace", "check marketplace.json", "verify marketplace structure", or mentions plugin or marketplace validation. Also trigger proactively after user creates or modifies plugin or marketplace components. Examples: - - -Context: User finished creating a new plugin -user: "I've created my first plugin with commands and hooks" -assistant: "I'll use the plugin-validator agent to validate the plugin structure." - -Plugin created, proactively validate to catch issues early. - - - - -Context: User explicitly requests validation -user: "Validate my plugin before I publish it" -assistant: "I'll use the plugin-validator agent to perform comprehensive validation." - -Explicit validation request triggers the agent. - - - - -Context: User modified plugin.json -user: "I've updated the plugin manifest" -assistant: "I'll use the plugin-validator agent to validate the manifest changes." - -Manifest modified, validate to ensure correctness. - - - - -Context: User created or modified a marketplace -user: "I've set up a marketplace.json for my plugins" -assistant: "I'll use the plugin-validator agent to validate the marketplace structure." - -Marketplace created, validate schema and plugin entries. - - +description: | + Use this agent when the user asks to "validate my plugin", "check plugin structure", "verify plugin is correct", "validate plugin.json", "check plugin files", "validate marketplace", "check marketplace.json", "verify marketplace structure", or mentions plugin or marketplace validation. Also trigger proactively after user creates or modifies plugin or marketplace components. Examples: + + + Context: User finished creating a new plugin + user: "I've created my first plugin with commands and hooks" + assistant: "I'll use the plugin-validator agent to validate the plugin structure." + + Plugin created, proactively validate to catch issues early. + + + + + Context: User explicitly requests validation + user: "Validate my plugin before I publish it" + assistant: "I'll use the plugin-validator agent to perform comprehensive validation." + + Explicit validation request triggers the agent. + + + + + Context: User modified plugin.json + user: "I've updated the plugin manifest" + assistant: "I'll use the plugin-validator agent to validate the manifest changes." + + Manifest modified, validate to ensure correctness. + + + + + Context: User created or modified a marketplace + user: "I've set up a marketplace.json for my plugins" + assistant: "I'll use the plugin-validator agent to validate the marketplace structure." + + Marketplace created, validate schema and plugin entries. + + model: inherit color: yellow diff --git a/plugins/plugin-dev/agents/skill-reviewer.md b/plugins/plugin-dev/agents/skill-reviewer.md index fc81775..a89e6ec 100644 --- a/plugins/plugin-dev/agents/skill-reviewer.md +++ b/plugins/plugin-dev/agents/skill-reviewer.md @@ -1,42 +1,43 @@ --- name: skill-reviewer -description: Use this agent when the user has created or modified a skill and needs quality review, asks to "review my skill", "check skill quality", "improve skill description", or wants to ensure skill follows best practices. Trigger proactively after skill creation. Examples: - - -Context: User just created a new skill -user: "I've created a PDF processing skill" -assistant: "I'll use the skill-reviewer agent to review the skill quality." - -Skill created, proactively trigger skill-reviewer to ensure it follows best practices. - - - - -Context: User requests skill review -user: "Review my skill and tell me how to improve it" -assistant: "I'll use the skill-reviewer agent to analyze the skill quality." - -Explicit skill review request triggers the agent. - - - - -Context: User modified skill description -user: "I updated the skill description, does it look good?" -assistant: "I'll use the skill-reviewer agent to review the changes." - -Skill description modified, review for triggering effectiveness. - - - - -Context: User is having trouble with skill triggering -user: "My skill isn't being loaded when I ask about PDF processing" -assistant: "I'll use the skill-reviewer agent to analyze why the skill isn't triggering." - -Skill triggering issue reported, trigger skill-reviewer to diagnose description and trigger phrase quality. - - +description: | + Use this agent when the user has created or modified a skill and needs quality review, asks to "review my skill", "check skill quality", "improve skill description", or wants to ensure skill follows best practices. Trigger proactively after skill creation. Examples: + + + Context: User just created a new skill + user: "I've created a PDF processing skill" + assistant: "I'll use the skill-reviewer agent to review the skill quality." + + Skill created, proactively trigger skill-reviewer to ensure it follows best practices. + + + + + Context: User requests skill review + user: "Review my skill and tell me how to improve it" + assistant: "I'll use the skill-reviewer agent to analyze the skill quality." + + Explicit skill review request triggers the agent. + + + + + Context: User modified skill description + user: "I updated the skill description, does it look good?" + assistant: "I'll use the skill-reviewer agent to review the changes." + + Skill description modified, review for triggering effectiveness. + + + + + Context: User is having trouble with skill triggering + user: "My skill isn't being loaded when I ask about PDF processing" + assistant: "I'll use the skill-reviewer agent to analyze why the skill isn't triggering." + + Skill triggering issue reported, trigger skill-reviewer to diagnose description and trigger phrase quality. + + model: inherit color: cyan diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index f3af0bb..3c1322c 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -1,5 +1,6 @@ --- name: agent-development +version: 0.2.0 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. --- diff --git a/plugins/plugin-dev/skills/command-development/SKILL.md b/plugins/plugin-dev/skills/command-development/SKILL.md index ce3ed69..f74d883 100644 --- a/plugins/plugin-dev/skills/command-development/SKILL.md +++ b/plugins/plugin-dev/skills/command-development/SKILL.md @@ -1,13 +1,16 @@ --- name: command-development +version: 0.2.0 description: This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", "Skill tool", "programmatic command invocation", "disable-model-invocation", "prevent Claude from running command", "debug command", "command debugging", "troubleshoot command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, programmatic invocation control, debugging commands, or command development best practices for Claude Code. --- # Command Development for Claude Code +> **Note:** The `.claude/commands/` directory is a legacy format. For new plugins, prefer the `skills//SKILL.md` directory format. Both are loaded identically by Claude Code -- the only difference is file layout. The skills format supports progressive disclosure via `references/` and `examples/` subdirectories. See the `skill-development` skill for the preferred format. + ## Overview -Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Master command structure, frontmatter options, and dynamic features to create powerful, reusable workflows. +Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows. **Key concepts:** diff --git a/plugins/plugin-dev/skills/lsp-integration/SKILL.md b/plugins/plugin-dev/skills/lsp-integration/SKILL.md index 4f35db4..308e9d7 100644 --- a/plugins/plugin-dev/skills/lsp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/lsp-integration/SKILL.md @@ -1,5 +1,6 @@ --- name: lsp-integration +version: 0.1.0 description: This skill should be used when the user asks to "add LSP server", "configure language server", "set up LSP in plugin", "add code intelligence", "integrate language server protocol", "use pyright-lsp", "use typescript-lsp", "use rust-lsp", mentions LSP servers, or discusses extensionToLanguage mappings. Provides guidance for integrating Language Server Protocol servers into Claude Code plugins for enhanced code intelligence. --- diff --git a/plugins/plugin-dev/skills/marketplace-structure/SKILL.md b/plugins/plugin-dev/skills/marketplace-structure/SKILL.md index ad66c8d..6dedf21 100644 --- a/plugins/plugin-dev/skills/marketplace-structure/SKILL.md +++ b/plugins/plugin-dev/skills/marketplace-structure/SKILL.md @@ -1,5 +1,6 @@ --- name: marketplace-structure +version: 0.1.0 description: This skill should be used when the user asks to "create a marketplace", "set up marketplace.json", "organize multiple plugins", "distribute plugins", "host plugins", "marketplace schema", "plugin marketplace structure", "multi-plugin organization", or needs guidance on plugin marketplace creation, marketplace manifest configuration, or plugin distribution strategies. --- diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index c1966ac..1e6ca6b 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -1,5 +1,6 @@ --- name: mcp-integration +version: 0.2.0 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. --- diff --git a/plugins/plugin-dev/skills/plugin-settings/SKILL.md b/plugins/plugin-dev/skills/plugin-settings/SKILL.md index 9e1e9ab..eb16800 100644 --- a/plugins/plugin-dev/skills/plugin-settings/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-settings/SKILL.md @@ -1,5 +1,6 @@ --- name: plugin-settings +version: 0.1.0 description: This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content. --- diff --git a/plugins/plugin-dev/skills/plugin-structure/SKILL.md b/plugins/plugin-dev/skills/plugin-structure/SKILL.md index 6e7837c..51d6b5d 100644 --- a/plugins/plugin-dev/skills/plugin-structure/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-structure/SKILL.md @@ -1,5 +1,6 @@ --- name: plugin-structure +version: 0.2.0 description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "add lspServers", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices. --- @@ -109,7 +110,9 @@ Specify custom paths for components (supplements default directories): ## Component Organization -### Commands +### Commands (Legacy) + +> **Note:** The `commands/` directory is a legacy format. For new plugins, prefer `skills//SKILL.md` which supports progressive disclosure via `references/` and `examples/` subdirectories. Both formats are loaded identically by Claude Code. **Location**: `commands/` directory **Format**: Markdown files with YAML frontmatter diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index e65289d..1f9903d 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -1,5 +1,6 @@ --- name: skill-development +version: 0.2.0 description: This skill should be used when the user asks to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", "SKILL.md format", "skill frontmatter", "skill triggers", "trigger phrases for skills", "progressive disclosure", "skill references folder", "skill examples folder", "validate skill", or needs guidance on skill structure, file organization, writing style, or skill development best practices for Claude Code plugins. --- From a54fd04b17005dbf74b65591bd929bda6e1af99a Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Fri, 20 Mar 2026 12:08:50 +1300 Subject: [PATCH 05/33] feat: add example scripts for all new hook events - stop-failure-alert.sh: StopFailure API error alerting with desktop notifications - validate-task.sh: TaskCompleted test verification gate - teammate-quality-gate.sh: TeammateIdle quality checks - create-worktree.sh: WorktreeCreate custom setup with dependency install (demonstrates stdout-as-return-value pattern) - cleanup-worktree.sh: WorktreeRemove resource cleanup - audit-config-change.sh: ConfigChange security monitoring - handle-elicitation.sh: Elicitation auto-response for MCP servers - log-observability.sh: Unified logging for InstructionsLoaded, PreCompact, PostCompact, and Notification events - Update SKILL.md examples section to list all 11 scripts --- .../skills/hook-development/SKILL.md | 14 ++- .../examples/audit-config-change.sh | 41 ++++++++ .../examples/cleanup-worktree.sh | 41 ++++++++ .../examples/create-worktree.sh | 45 +++++++++ .../examples/handle-elicitation.sh | 54 +++++++++++ .../examples/log-observability.sh | 95 +++++++++++++++++++ .../examples/stop-failure-alert.sh | 43 +++++++++ .../examples/teammate-quality-gate.sh | 43 +++++++++ .../examples/validate-task.sh | 48 ++++++++++ 9 files changed, 421 insertions(+), 3 deletions(-) create mode 100644 plugins/plugin-dev/skills/hook-development/examples/audit-config-change.sh create mode 100644 plugins/plugin-dev/skills/hook-development/examples/cleanup-worktree.sh create mode 100644 plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh create mode 100644 plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh create mode 100644 plugins/plugin-dev/skills/hook-development/examples/log-observability.sh create mode 100644 plugins/plugin-dev/skills/hook-development/examples/stop-failure-alert.sh create mode 100644 plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh create mode 100644 plugins/plugin-dev/skills/hook-development/examples/validate-task.sh diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index b3a5e30..916e839 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/plugins/plugin-dev/skills/hook-development/SKILL.md @@ -1067,9 +1067,17 @@ Working examples in `examples/`: > **Note:** After copying example scripts, make them executable: `chmod +x script.sh` -- **`validate-write.sh`** -- File write validation example -- **`validate-bash.sh`** -- Bash command validation example -- **`load-context.sh`** -- SessionStart context loading example +- **`validate-write.sh`** -- PreToolUse file write validation +- **`validate-bash.sh`** -- PreToolUse bash command validation +- **`load-context.sh`** -- SessionStart context loading +- **`stop-failure-alert.sh`** -- StopFailure API error alerting +- **`validate-task.sh`** -- TaskCompleted deliverable verification +- **`teammate-quality-gate.sh`** -- TeammateIdle quality gate +- **`create-worktree.sh`** -- WorktreeCreate custom worktree setup +- **`cleanup-worktree.sh`** -- WorktreeRemove resource cleanup +- **`audit-config-change.sh`** -- ConfigChange security monitoring +- **`handle-elicitation.sh`** -- Elicitation auto-response +- **`log-observability.sh`** -- Unified logging for InstructionsLoaded, PreCompact, PostCompact, Notification ### Utility Scripts diff --git a/plugins/plugin-dev/skills/hook-development/examples/audit-config-change.sh b/plugins/plugin-dev/skills/hook-development/examples/audit-config-change.sh new file mode 100644 index 0000000..2ea6a0a --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/audit-config-change.sh @@ -0,0 +1,41 @@ +#!/bin/bash +# ConfigChange hook example: audit and optionally block config changes +# +# Hook config: +# { +# "ConfigChange": [ +# { +# "matcher": "project_settings|local_settings", +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/audit-config-change.sh" +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +source_type=$(echo "$input" | jq -r '.source') +file_path=$(echo "$input" | jq -r '.file_path // "unknown"') +timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ) + +# Log the change +log_dir="${CLAUDE_PROJECT_DIR:-.}/.claude" +mkdir -p "$log_dir" +echo "[$timestamp] CONFIG_CHANGE source=$source_type file=$file_path" \ + >> "$log_dir/config-audit.log" + +# Block permission changes in project settings (security measure) +if [ "$source_type" = "project_settings" ] && [ -f "$file_path" ]; then + if jq -e '.permissions' "$file_path" >/dev/null 2>&1; then + echo "Permission changes in project settings require manual review." >&2 + exit 2 + fi +fi + +# Note: policy_settings changes cannot be blocked even if you try. +# The block decision is silently ignored for policy sources. diff --git a/plugins/plugin-dev/skills/hook-development/examples/cleanup-worktree.sh b/plugins/plugin-dev/skills/hook-development/examples/cleanup-worktree.sh new file mode 100644 index 0000000..97ef502 --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/cleanup-worktree.sh @@ -0,0 +1,41 @@ +#!/bin/bash +# WorktreeRemove hook example: clean up worktree resources +# +# Output and exit code are ignored for WorktreeRemove -- this is cleanup only. +# +# Hook config: +# { +# "WorktreeRemove": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/cleanup-worktree.sh" +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +worktree_path=$(echo "$input" | jq -r '.worktree_path') + +if [ -z "$worktree_path" ] || [ ! -d "$worktree_path" ]; then + exit 0 +fi + +# Clean up heavy directories before git worktree removal +for dir in node_modules .venv __pycache__ target dist build; do + if [ -d "$worktree_path/$dir" ]; then + rm -rf "${worktree_path:?}/$dir" + fi +done + +# Remove the git worktree +git worktree remove "$worktree_path" --force 2>/dev/null || true + +# Clean up the branch if it exists +branch_name=$(basename "$worktree_path") +git branch -D "worktree/$branch_name" 2>/dev/null || true diff --git a/plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh b/plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh new file mode 100644 index 0000000..159aeb8 --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh @@ -0,0 +1,45 @@ +#!/bin/bash +# WorktreeCreate hook example: custom worktree creation with dependency install +# +# This is the only hook where stdout is the return value (an absolute path), +# not JSON. The path printed to stdout becomes the worktree directory. +# +# Hook config: +# { +# "WorktreeCreate": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/create-worktree.sh" +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +name=$(echo "$input" | jq -r '.name') + +# Create worktree in a designated directory +worktree_base="/tmp/claude-worktrees" +mkdir -p "$worktree_base" +worktree_dir="$worktree_base/$name" + +# Create the git worktree +git worktree add "$worktree_dir" -b "worktree/$name" HEAD 2>/dev/null + +# Install dependencies in the new worktree +cd "$worktree_dir" +if [ -f "package.json" ]; then + npm ci --silent 2>/dev/null || npm install --silent 2>/dev/null || true +elif [ -f "Gemfile" ]; then + bundle install --quiet 2>/dev/null || true +elif [ -f "requirements.txt" ]; then + pip install -q -r requirements.txt 2>/dev/null || true +fi + +# Print the absolute path -- this IS the return value +echo "$worktree_dir" diff --git a/plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh b/plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh new file mode 100644 index 0000000..c0b30a8 --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh @@ -0,0 +1,54 @@ +#!/bin/bash +# Elicitation hook example: auto-respond to MCP server prompts +# +# Hook config: +# { +# "Elicitation": [ +# { +# "matcher": "my-auth-server", +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/handle-elicitation.sh" +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +message=$(echo "$input" | jq -r '.message') +mode=$(echo "$input" | jq -r '.mode // "form"') + +# Handle URL-based auth flows (open browser for user) +if [ "$mode" = "url" ]; then + url=$(echo "$input" | jq -r '.url // ""') + if [ -n "$url" ]; then + # Open in browser + if command -v open &>/dev/null; then + open "$url" 2>/dev/null || true + elif command -v xdg-open &>/dev/null; then + xdg-open "$url" 2>/dev/null || true + fi + fi + # Decline -- user will complete auth in browser + echo '{"hookSpecificOutput": {"hookEventName": "Elicitation", "action": "decline"}}' + exit 0 +fi + +# Auto-accept known confirmation prompts +if echo "$message" | grep -qi "confirm"; then + jq -n '{ + hookSpecificOutput: { + hookEventName: "Elicitation", + action: "accept", + content: { confirmed: true } + } + }' + exit 0 +fi + +# Unknown prompt -- let user handle it (no output = pass through) +exit 0 diff --git a/plugins/plugin-dev/skills/hook-development/examples/log-observability.sh b/plugins/plugin-dev/skills/hook-development/examples/log-observability.sh new file mode 100644 index 0000000..4094a30 --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/log-observability.sh @@ -0,0 +1,95 @@ +#!/bin/bash +# Observability hook example: unified logging for multiple event types +# +# A single script that handles InstructionsLoaded, PreCompact, PostCompact, +# and Notification events. Use the hook_event_name field to distinguish. +# +# Hook config (add entries for each event): +# { +# "InstructionsLoaded": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/log-observability.sh", +# "async": true +# } +# ] +# } +# ], +# "PreCompact": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/log-observability.sh", +# "async": true +# } +# ] +# } +# ], +# "PostCompact": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/log-observability.sh", +# "async": true +# } +# ] +# } +# ], +# "Notification": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/log-observability.sh", +# "async": true +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +event=$(echo "$input" | jq -r '.hook_event_name') +timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ) + +log_dir="${CLAUDE_PROJECT_DIR:-.}/.claude" +mkdir -p "$log_dir" +log_file="$log_dir/session-events.log" + +case "$event" in + InstructionsLoaded) + file_path=$(echo "$input" | jq -r '.file_path') + memory_type=$(echo "$input" | jq -r '.memory_type') + load_reason=$(echo "$input" | jq -r '.load_reason') + echo "[$timestamp] INSTRUCTIONS type=$memory_type reason=$load_reason path=$file_path" >> "$log_file" + ;; + + PreCompact) + trigger=$(echo "$input" | jq -r '.trigger') + echo "[$timestamp] COMPACT_START trigger=$trigger" >> "$log_file" + ;; + + PostCompact) + trigger=$(echo "$input" | jq -r '.trigger') + summary_len=$(echo "$input" | jq -r '.compact_summary | length') + echo "[$timestamp] COMPACT_END trigger=$trigger summary_chars=$summary_len" >> "$log_file" + ;; + + Notification) + notification_type=$(echo "$input" | jq -r '.notification_type') + message=$(echo "$input" | jq -r '.message' | head -c 200) + echo "[$timestamp] NOTIFICATION type=$notification_type msg=$message" >> "$log_file" + ;; + + *) + echo "[$timestamp] UNKNOWN event=$event" >> "$log_file" + ;; +esac + +# All observability events: no decision control, output is ignored diff --git a/plugins/plugin-dev/skills/hook-development/examples/stop-failure-alert.sh b/plugins/plugin-dev/skills/hook-development/examples/stop-failure-alert.sh new file mode 100644 index 0000000..a081e94 --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/stop-failure-alert.sh @@ -0,0 +1,43 @@ +#!/bin/bash +# StopFailure hook example: alert on API errors +# +# Hook config: +# { +# "StopFailure": [ +# { +# "matcher": "rate_limit|authentication_failed|billing_error", +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/stop-failure-alert.sh" +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +error=$(echo "$input" | jq -r '.error') +details=$(echo "$input" | jq -r '.error_details // "none"') +session_id=$(echo "$input" | jq -r '.session_id') +timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ) + +# Log to file +log_dir="${CLAUDE_PROJECT_DIR:-.}/.claude" +mkdir -p "$log_dir" +echo "[$timestamp] ERROR=$error DETAILS=$details SESSION=$session_id" \ + >> "$log_dir/api-errors.log" + +# Desktop notification (macOS) +if command -v osascript &>/dev/null; then + osascript -e "display notification \"$error: $details\" with title \"Claude Code API Error\"" 2>/dev/null || true +fi + +# Desktop notification (Linux) +if command -v notify-send &>/dev/null; then + notify-send "Claude Code API Error" "$error: $details" 2>/dev/null || true +fi + +# StopFailure output is ignored -- this is observability only diff --git a/plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh b/plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh new file mode 100644 index 0000000..356228f --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh @@ -0,0 +1,43 @@ +#!/bin/bash +# TeammateIdle hook example: prevent idle until work meets standards +# +# Hook config: +# { +# "TeammateIdle": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/teammate-quality-gate.sh" +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +teammate_name=$(echo "$input" | jq -r '.teammate_name') +# team_name available via: echo "$input" | jq -r '.team_name' + +# Check for uncommitted changes that suggest incomplete work +if git diff --quiet 2>/dev/null && git diff --cached --quiet 2>/dev/null; then + # No uncommitted changes, allow idle + exit 0 +fi + +# Check for common incomplete-work indicators +staged_files=$(git diff --cached --name-only 2>/dev/null || true) + +# Reject if TODO/FIXME added in staged files +if [ -n "$staged_files" ]; then + # shellcheck disable=SC2086 + if git diff --cached -- $staged_files 2>/dev/null | grep -qE '^\+.*\b(TODO|FIXME|HACK|XXX)\b'; then + echo "Teammate $teammate_name has TODO/FIXME markers in staged changes. Address these before going idle." >&2 + exit 2 # Reject idle, teammate keeps working + fi +fi + +# Allow idle +exit 0 diff --git a/plugins/plugin-dev/skills/hook-development/examples/validate-task.sh b/plugins/plugin-dev/skills/hook-development/examples/validate-task.sh new file mode 100644 index 0000000..f2ff51c --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/examples/validate-task.sh @@ -0,0 +1,48 @@ +#!/bin/bash +# TaskCompleted hook example: verify task deliverables before marking complete +# +# Hook config: +# { +# "TaskCompleted": [ +# { +# "hooks": [ +# { +# "type": "command", +# "command": "bash ${CLAUDE_PLUGIN_ROOT}/examples/validate-task.sh" +# } +# ] +# } +# ] +# } + +set -euo pipefail + +input=$(cat) +task_subject=$(echo "$input" | jq -r '.task_subject') +# task_description available via: echo "$input" | jq -r '.task_description // ""' + +# Check if this is a code-related task +if ! echo "$task_subject" | grep -qiE 'implement|fix|refactor|add|create|update|remove|delete'; then + # Non-code task, allow completion + exit 0 +fi + +# Verify tests pass (try common test runners) +test_passed=false +if [ -f "Makefile" ] && grep -q '^test:' Makefile; then + make test >/dev/null 2>&1 && test_passed=true +elif [ -f "package.json" ] && jq -e '.scripts.test' package.json >/dev/null 2>&1; then + npm test >/dev/null 2>&1 && test_passed=true +elif [ -f "Cargo.toml" ]; then + cargo test >/dev/null 2>&1 && test_passed=true +elif [ -f "go.mod" ]; then + go test ./... >/dev/null 2>&1 && test_passed=true +else + # No recognizable test runner, allow completion + exit 0 +fi + +if [ "$test_passed" = false ]; then + echo "Tests must pass before completing task: $task_subject" >&2 + exit 2 # Reject completion, agent continues working +fi From 9fa93d292e65886577c8ffe48e5f9df8c3d2d5e5 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Fri, 20 Mar 2026 12:29:44 +1300 Subject: [PATCH 06/33] fix: address adversarial review findings in hook scripts - validate-hook-schema.sh: don't reject configs missing matcher for events that don't support matchers (UserPromptSubmit, Stop, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove). Downgrade from error to warning for other events. - validate-hook-schema.sh: replace ${hook_type^} bash 4+ syntax with awk for macOS stock bash compatibility - create-worktree.sh: sanitize name input to prevent path traversal, surface git and dependency install errors instead of swallowing them - teammate-quality-gate.sh: case-insensitive TODO/FIXME matching - handle-elicitation.sh: only open https:// URLs to prevent file://, javascript:, or other dangerous schemes from MCP servers - log-observability.sh: flatten newlines in notification messages to prevent breaking single-line log format --- .../examples/create-worktree.sh | 19 +++++++++++++----- .../examples/handle-elicitation.sh | 4 ++-- .../examples/log-observability.sh | 3 ++- .../examples/teammate-quality-gate.sh | 2 +- .../scripts/validate-hook-schema.sh | 20 ++++++++++++++----- 5 files changed, 34 insertions(+), 14 deletions(-) diff --git a/plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh b/plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh index 159aeb8..d4d8048 100644 --- a/plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh +++ b/plugins/plugin-dev/skills/hook-development/examples/create-worktree.sh @@ -23,22 +23,31 @@ set -euo pipefail input=$(cat) name=$(echo "$input" | jq -r '.name') +# Sanitize name: reject path traversal and restrict to safe characters +if [[ "$name" == *".."* ]] || [[ "$name" == /* ]] || [[ ! "$name" =~ ^[a-zA-Z0-9._-]+$ ]]; then + echo "Invalid worktree name: $name" >&2 + exit 1 +fi + # Create worktree in a designated directory worktree_base="/tmp/claude-worktrees" mkdir -p "$worktree_base" worktree_dir="$worktree_base/$name" # Create the git worktree -git worktree add "$worktree_dir" -b "worktree/$name" HEAD 2>/dev/null +if ! git worktree add "$worktree_dir" -b "worktree/$name" HEAD 2>&1; then + echo "Failed to create worktree: $worktree_dir" >&2 + exit 1 +fi -# Install dependencies in the new worktree +# Install dependencies in the new worktree (best-effort, log failures) cd "$worktree_dir" if [ -f "package.json" ]; then - npm ci --silent 2>/dev/null || npm install --silent 2>/dev/null || true + npm ci --silent 2>&1 || npm install --silent 2>&1 || echo "Warning: npm install failed" >&2 elif [ -f "Gemfile" ]; then - bundle install --quiet 2>/dev/null || true + bundle install --quiet 2>&1 || echo "Warning: bundle install failed" >&2 elif [ -f "requirements.txt" ]; then - pip install -q -r requirements.txt 2>/dev/null || true + pip install -q -r requirements.txt 2>&1 || echo "Warning: pip install failed" >&2 fi # Print the absolute path -- this IS the return value diff --git a/plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh b/plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh index c0b30a8..2279901 100644 --- a/plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh +++ b/plugins/plugin-dev/skills/hook-development/examples/handle-elicitation.sh @@ -25,8 +25,8 @@ mode=$(echo "$input" | jq -r '.mode // "form"') # Handle URL-based auth flows (open browser for user) if [ "$mode" = "url" ]; then url=$(echo "$input" | jq -r '.url // ""') - if [ -n "$url" ]; then - # Open in browser + # Only open https URLs to prevent file://, javascript:, or other dangerous schemes + if [[ "$url" == https://* ]]; then if command -v open &>/dev/null; then open "$url" 2>/dev/null || true elif command -v xdg-open &>/dev/null; then diff --git a/plugins/plugin-dev/skills/hook-development/examples/log-observability.sh b/plugins/plugin-dev/skills/hook-development/examples/log-observability.sh index 4094a30..959547e 100644 --- a/plugins/plugin-dev/skills/hook-development/examples/log-observability.sh +++ b/plugins/plugin-dev/skills/hook-development/examples/log-observability.sh @@ -83,7 +83,8 @@ case "$event" in Notification) notification_type=$(echo "$input" | jq -r '.notification_type') - message=$(echo "$input" | jq -r '.message' | head -c 200) + # Truncate and flatten to single line for log parsing + message=$(echo "$input" | jq -r '.message' | tr '\n' ' ' | head -c 200) echo "[$timestamp] NOTIFICATION type=$notification_type msg=$message" >> "$log_file" ;; diff --git a/plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh b/plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh index 356228f..9451b91 100644 --- a/plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh +++ b/plugins/plugin-dev/skills/hook-development/examples/teammate-quality-gate.sh @@ -33,7 +33,7 @@ staged_files=$(git diff --cached --name-only 2>/dev/null || true) # Reject if TODO/FIXME added in staged files if [ -n "$staged_files" ]; then # shellcheck disable=SC2086 - if git diff --cached -- $staged_files 2>/dev/null | grep -qE '^\+.*\b(TODO|FIXME|HACK|XXX)\b'; then + if git diff --cached -- $staged_files 2>/dev/null | grep -qiE '^\+.*\b(TODO|FIXME|HACK|XXX)\b'; then echo "Teammate $teammate_name has TODO/FIXME markers in staged changes. Address these before going idle." >&2 exit 2 # Reject idle, teammate keeps working fi diff --git a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh index 9c77e78..8f387a2 100755 --- a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh +++ b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh @@ -66,12 +66,21 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do hook_count=$(jq -r ".\"$event\" | length" "$HOOKS_FILE") for ((i = 0; i < hook_count; i++)); do - # Check matcher exists + # Check matcher (optional -- some events don't support matchers) matcher=$(jq -r ".\"$event\"[$i].matcher // empty" "$HOOKS_FILE") + NO_MATCHER_EVENTS=("UserPromptSubmit" "Stop" "TeammateIdle" "TaskCompleted" "WorktreeCreate" "WorktreeRemove") if [ -z "$matcher" ]; then - echo "❌ ${event}[$i]: Missing 'matcher' field" - ((error_count++)) - continue + is_no_matcher=false + for nm_event in "${NO_MATCHER_EVENTS[@]}"; do + if [ "$event" = "$nm_event" ]; then + is_no_matcher=true + break + fi + done + if [ "$is_no_matcher" = false ]; then + echo "⚠️ ${event}[$i]: No 'matcher' field (will match all occurrences)" + ((warning_count++)) + fi fi # Check hooks array exists @@ -123,7 +132,8 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do prompt | agent) prompt=$(jq -r ".\"$event\"[$i].hooks[$j].prompt // empty" "$HOOKS_FILE") if [ -z "$prompt" ]; then - echo "❌ ${event}[$i].hooks[$j]: ${hook_type^} hooks must have 'prompt' field" + ht_label=$(echo "$hook_type" | awk '{print toupper(substr($0,1,1)) substr($0,2)}') + echo "❌ ${event}[$i].hooks[$j]: $ht_label hooks must have 'prompt' field" ((error_count++)) fi ;; From 76739ba272cbcd0bfd629f2c560b4919c47eb2e3 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Tue, 24 Mar 2026 11:32:17 +1300 Subject: [PATCH 07/33] chore: update marketplace ownership and simplify plugin-dev-guide skill - Point marketplace.json at kylesnowschwartz fork - Merge commands section into skill quick reference table - Remove redundant decision tree and command file - Use explicit Skill tool invocation language throughout --- .claude-plugin/marketplace.json | 12 +-- .../plugin-dev/commands/plugin-dev-guide.md | 12 --- .../skills/plugin-dev-guide/SKILL.md | 92 +++++++------------ 3 files changed, 41 insertions(+), 75 deletions(-) delete mode 100644 plugins/plugin-dev/commands/plugin-dev-guide.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2137a34..58fef2f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,11 +1,11 @@ { "name": "plugin-dev-marketplace", "owner": { - "name": "Steve Nims", - "url": "https://github.com/sjnims" + "name": "Kyle Snow Schwartz", + "url": "https://github.com/kylesnowschwartz" }, "metadata": { - "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, now maintained by Steve Nims.", + "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", "version": "0.3.3" }, "plugins": [ @@ -14,10 +14,10 @@ "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "version": "0.3.3", "author": { - "name": "Steve Nims", - "url": "https://github.com/sjnims" + "name": "Kyle Snow Schwartz", + "url": "https://github.com/kylesnowschwartz" }, - "homepage": "https://github.com/sjnims/plugin-dev", + "homepage": "https://github.com/kylesnowschwartz/plugin-dev", "tags": [ "ai-tools", "claude", diff --git a/plugins/plugin-dev/commands/plugin-dev-guide.md b/plugins/plugin-dev/commands/plugin-dev-guide.md deleted file mode 100644 index d393236..0000000 --- a/plugins/plugin-dev/commands/plugin-dev-guide.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Get an overview of plugin development capabilities and skill routing -argument-hint: [question or task] -allowed-tools: Skill, AskUserQuestion -model: sonnet ---- - -Invoke the plugin-dev:plugin-dev-guide skill to load plugin development guidance. - -Then help with: $ARGUMENTS - -If no arguments provided, summarize what plugin development capabilities are available and ask the user what they want to build or learn about. diff --git a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md index 33ab28b..31a0d2e 100644 --- a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md @@ -7,23 +7,28 @@ description: This skill should be used when the user asks about "Claude Code plu This meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand. +Your goal is to match the user request (or recent conversation context) to the appropriate skill below, then invoke it using the Skill tool. + ## Plugin Development Skills Overview -The plugin-dev toolkit provides 9 specialized skills for building Claude Code plugins, plus this guide. Each skill handles a specific domain of plugin development. +The plugin-dev toolkit provides 9 specialized skills and 3 slash commands for building Claude Code plugins, plus this guide. Each handles a specific domain of plugin development. ### Skill Quick Reference -| Skill | Purpose | -| ------- | --------- | -| **plugin-structure** | Directory layout, manifest, component organization | -| **command-development** | Slash commands with frontmatter | -| **agent-development** | Autonomous subagents | -| **skill-development** | Creating skills with progressive disclosure | -| **hook-development** | Event-driven automation | -| **mcp-integration** | Model Context Protocol servers | -| **lsp-integration** | Language Server Protocol for code intelligence | -| **plugin-settings** | User configuration via .local.md | -| **marketplace-structure** | Plugin marketplace creation | +| Skill | Purpose | +| ------- | --------- | +| /plugin-structure | Directory layout, manifest, component organization | +| /command-development | Slash commands with frontmatter | +| /agent-development | Autonomous subagents | +| /skill-development | Creating skills with progressive disclosure | +| /hook-development | Event-driven automation | +| /mcp-integration | Model Context Protocol servers | +| /lsp-integration | Language Server Protocol for code intelligence | +| /plugin-settings | User configuration via .local.md | +| /marketplace-structure | Plugin marketplace creation | +| /plugin-dev:start | Entry point — choose plugin or marketplace creation | +| /plugin-dev:create-plugin | 8-phase guided plugin creation workflow | +| /plugin-dev:create-marketplace | 8-phase guided marketplace creation workflow | ## When to Use Each Skill @@ -135,49 +140,34 @@ Use when the user needs to: - Distribute plugins to teams - Organize plugin collections -## Decision Tree for Skill Selection - -``` -User wants to... -├── Create/organize a plugin structure? → plugin-structure -├── Add a slash command? → command-development -├── Create an autonomous agent? → agent-development -├── Add domain expertise/knowledge? → skill-development -├── React to Claude Code events? → hook-development -├── Integrate external service/API? → mcp-integration -├── Add code intelligence/LSP? → lsp-integration -├── Make plugin configurable? → plugin-settings -└── Distribute multiple plugins? → marketplace-structure -``` - ## Common Multi-Skill Workflows ### Building a Complete Plugin -1. **Start**: Load `plugin-structure` skill to create directory layout -2. **Add features**: Load `command-development` for user-facing commands -3. **Automation**: Load `hook-development` for event-driven behavior -4. **Configuration**: Load `plugin-settings` if user configuration needed -5. **Validation**: Use plugin-validator agent to validate structure +1. Invoke `plugin-structure` to create directory layout +2. Invoke `command-development` for user-facing commands +3. Invoke `hook-development` for event-driven behavior +4. Invoke `plugin-settings` if user configuration needed +5. Use plugin-validator agent to validate structure ### Creating an MCP-Powered Plugin -1. **Start**: Load `plugin-structure` for basic structure -2. **Integration**: Load `mcp-integration` to configure MCP servers -3. **Commands**: Load `command-development` to create commands that use MCP tools -4. **Agents**: Load `agent-development` for autonomous MCP workflows +1. Invoke `plugin-structure` for basic structure +2. Invoke `mcp-integration` to configure MCP servers +3. Invoke `command-development` to create commands that use MCP tools +4. Invoke `agent-development` for autonomous MCP workflows ### Building a Code Intelligence Plugin -1. **Start**: Load `plugin-structure` for basic structure -2. **LSP**: Load `lsp-integration` to configure language servers -3. **Commands**: Load `command-development` for commands using LSP features +1. Invoke `plugin-structure` for basic structure +2. Invoke `lsp-integration` to configure language servers +3. Invoke `command-development` for commands using LSP features ### Building a Skill-Focused Plugin -1. **Start**: Load `plugin-structure` for basic structure -2. **Skills**: Load `skill-development` to create specialized skills -3. **Validation**: Use skill-reviewer agent to validate skill quality +1. Invoke `plugin-structure` for basic structure +2. Invoke `skill-development` to create specialized skills +3. Use skill-reviewer agent to validate skill quality ## Available Agents @@ -191,24 +181,12 @@ The plugin-dev plugin also provides 3 agents: Use agents proactively after creating components to ensure quality. -## Available Commands - -| Command | Purpose | -|---------|---------| -| `/plugin-dev:start` | Entry point - choose plugin or marketplace creation | -| `/plugin-dev:create-plugin` | 8-phase guided plugin creation workflow | -| `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow | - --- ## User Request -$ARGUMENTS - -If the user provided a request above, analyze it and either: +Match the user request below to a skill from the table above, then invoke it with the Skill tool. If no single skill matches, answer directly using this guide. If the request is ambiguous, ask for clarification. -1. **Route to a specific skill** if the request clearly matches one domain -2. **Answer directly** using this guide's overview information -3. **Ask for clarification** if the request is ambiguous +If no request was provided, summarize the available capabilities and ask what the user wants to build or learn about. -If no request was provided, summarize the available plugin development capabilities and ask what the user wants to build or learn about. +$ARGUMENTS From 352b522ac32a08209f076b9e42091c80b10e7fc1 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Tue, 24 Mar 2026 11:32:48 +1300 Subject: [PATCH 08/33] chore: bump version to 0.4.0 and update plugin ownership to fork --- .claude-plugin/marketplace.json | 4 ++-- CLAUDE.md | 4 ++-- plugins/plugin-dev/.claude-plugin/plugin.json | 10 +++++----- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 58fef2f..6b27225 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.3.3" + "version": "0.4.0" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.3.3", + "version": "0.4.0", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CLAUDE.md b/CLAUDE.md index 882fcb4..df2c334 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,9 +4,9 @@ Guidance for Claude Code working in this repository. ## What This Is -Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 3 agents, 4 slash commands. +Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 3 agents, 3 slash commands. -**Version**: v0.3.3 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.4.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 6821991..508d44d 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,13 +1,13 @@ { "name": "plugin-dev", - "version": "0.3.3", + "version": "0.4.0", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { - "name": "Steve Nims", - "url": "https://github.com/sjnims" + "name": "Kyle Snow Schwartz", + "url": "https://github.com/kylesnowschwartz" }, - "homepage": "https://github.com/sjnims/plugin-dev", - "repository": "https://github.com/sjnims/plugin-dev", + "homepage": "https://github.com/kylesnowschwartz/plugin-dev", + "repository": "https://github.com/kylesnowschwartz/plugin-dev", "license": "MIT", "keywords": [ "ai-tools", From 9c8bf91e5718e2b27a809590567d8b0c0ba17041 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Tue, 24 Mar 2026 12:26:07 +1300 Subject: [PATCH 09/33] docs: audit skills against official Claude Code docs and release v0.4.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Incorporate upstream documentation audit across all 10 skills. Add 10 new reference files covering agent fields, permission modes, hook input schemas, memory/rules system, headless CI, GitHub Actions, output styles, advanced topics, and frontmatter. Expand existing references for hooks, marketplace, MCP, and plugin structure. Fix critical prompt hook support claim (4 events → 19), add missing SessionEnd "resume" matcher, and update project docs with lint command corrections and component-patterns agent fields. Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 28 +- CLAUDE.md | 2 +- CONTRIBUTING.md | 27 +- README.md | 6 +- SECURITY.md | 1 + docs/component-patterns.md | 24 +- docs/release-procedure.md | 2 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../skills/agent-development/SKILL.md | 136 ++++++- .../references/advanced-agent-fields.md | 246 +++++++++++ .../references/permission-modes-rules.md | 226 ++++++++++ .../skills/command-development/SKILL.md | 24 +- .../references/skill-tool.md | 2 + .../skills/hook-development/SKILL.md | 53 ++- .../hook-development/references/advanced.md | 385 ++++++++++++++++++ .../references/hook-input-schemas.md | 145 +++++++ .../scripts/validate-hook-schema.sh | 6 + .../skills/lsp-integration/SKILL.md | 45 +- .../skills/marketplace-structure/SKILL.md | 61 ++- .../references/distribution-patterns.md | 47 ++- .../references/schema-reference.md | 64 ++- .../skills/mcp-integration/SKILL.md | 84 +++- .../references/authentication.md | 33 +- .../mcp-integration/references/tool-usage.md | 36 ++ .../skills/plugin-dev-guide/SKILL.md | 24 ++ .../skills/plugin-settings/SKILL.md | 13 +- .../references/memory-rules-system.md | 217 ++++++++++ .../skills/plugin-structure/SKILL.md | 59 ++- .../references/advanced-topics.md | 289 +++++++++++++ .../references/github-actions.md | 233 +++++++++++ .../references/headless-ci-mode.md | 193 +++++++++ .../references/manifest-reference.md | 34 ++ .../references/output-styles.md | 116 ++++++ .../skills/skill-development/SKILL.md | 57 ++- .../references/advanced-frontmatter.md | 225 ++++++++++ .../references/commands-vs-skills.md | 39 ++ 37 files changed, 3094 insertions(+), 94 deletions(-) create mode 100644 plugins/plugin-dev/skills/agent-development/references/advanced-agent-fields.md create mode 100644 plugins/plugin-dev/skills/agent-development/references/permission-modes-rules.md create mode 100644 plugins/plugin-dev/skills/hook-development/references/hook-input-schemas.md create mode 100644 plugins/plugin-dev/skills/plugin-settings/references/memory-rules-system.md create mode 100644 plugins/plugin-dev/skills/plugin-structure/references/advanced-topics.md create mode 100644 plugins/plugin-dev/skills/plugin-structure/references/github-actions.md create mode 100644 plugins/plugin-dev/skills/plugin-structure/references/headless-ci-mode.md create mode 100644 plugins/plugin-dev/skills/plugin-structure/references/output-styles.md create mode 100644 plugins/plugin-dev/skills/skill-development/references/advanced-frontmatter.md create mode 100644 plugins/plugin-dev/skills/skill-development/references/commands-vs-skills.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6b27225..08df420 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.4.0" + "version": "0.4.1" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.4.0", + "version": "0.4.1", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d2a7d1..4ea1217 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.4.1] - 2026-03-24 + +### Documentation + +- **Audit skills against official Claude Code docs** - Incorporated upstream documentation audit covering all 10 skills with new sections for agent teams, execution modes, MCP scope system, CLI commands, plugin validation, enterprise features, visibility budgets, and context management +- **Add 10 new reference files** - Advanced agent fields, permission modes/rules, hook input schemas, memory/rules system, headless CI mode, GitHub Actions integration, output styles, advanced topics, advanced frontmatter, commands-vs-skills +- **Expand existing references** - Hook advanced patterns, marketplace distribution/schema, MCP authentication/tool-usage, manifest reference, command skill-tool +- **Fix prompt hook support claim** - Corrected false claim that prompt hooks only support 4 events (actually supports 19) +- **Fix SessionEnd Quick Reference** - Added missing "resume" matcher +- **Update project docs** - Lint command updates (markdownlint-cli2), component-patterns agent fields, SECURITY supported versions + +## [0.4.0] - 2026-03-20 + +### Added + +- **Plugin-dev-guide meta-skill** - Navigation skill that routes users to the correct specialized skill +- **All 22 hook event documentation** - Comprehensive schemas, examples, and gotchas for every Claude Code hook event +- **Hook example scripts** - Working examples for StopFailure, TaskCompleted, TeammateIdle, WorktreeCreate/Remove, ConfigChange, Elicitation, and observability logging + +### Changed + +- **Fork ownership** - Updated plugin and marketplace ownership to kylesnowschwartz +- **Synced plugin structure** - Aligned with official Claude Code plugin conventions + ## [0.3.2] - 2026-01-24 ### Fixed @@ -232,7 +256,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.2...HEAD +[Unreleased]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.4.1...HEAD +[0.4.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.4.0...v0.4.1 +[0.4.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.3.2...v0.4.0 [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 [0.3.0]: https://github.com/sjnims/plugin-dev/compare/v0.2.1...v0.3.0 diff --git a/CLAUDE.md b/CLAUDE.md index df2c334..62f7b15 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 3 agents, 3 slash commands. -**Version**: v0.4.0 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.4.1 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2f09f1..5be1579 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,9 +32,11 @@ Before contributing, ensure you have: gh auth login ``` - **Git**: For version control -- **Node.js**: For markdownlint (optional but recommended) +- **markdownlint-cli2** and **prettier**: For linting (should be available globally) ```bash - npm install -g markdownlint-cli + # Verify they're installed + markdownlint-cli2 --version + prettier --version ``` ### Understanding the Project @@ -48,15 +50,15 @@ Before contributing, ensure you have: ``` plugins/plugin-dev/ - ├── commands/ # 3 slash commands - ├── skills/ # 9 skills + ├── commands/ # 4 slash commands + ├── skills/ # 10 skills └── agents/ # 3 specialized agents ``` 3. **Understand the plugin components**: - - 9 skills for different plugin development aspects + - 10 skills for different plugin development aspects - 3 agents for validation and generation - - 3 slash commands: `/plugin-dev:start` (entry point), `/plugin-dev:create-plugin`, `/plugin-dev:create-marketplace` + - 4 slash commands: `/plugin-dev:start`, `/plugin-dev:create-plugin`, `/plugin-dev:create-marketplace`, `/plugin-dev:plugin-dev-guide` ## Development Setup @@ -137,10 +139,11 @@ All markdown files must follow the repository's style: ```bash # Lint before committing -markdownlint '**/*.md' --ignore node_modules +markdownlint-cli2 '**/*.md' -# Auto-fix issues -markdownlint '**/*.md' --ignore node_modules --fix +# Format with prettier +prettier --check '**/*.md' +prettier --write '**/*.md' # fix formatting issues ``` ### YAML Linting @@ -382,10 +385,10 @@ gh repo delete test-plugin-repo --yes ```bash # Lint all markdown -markdownlint '**/*.md' --ignore node_modules --fix +markdownlint-cli2 '**/*.md' -# Check specific files -markdownlint plugins/plugin-dev/commands/your-command.md +# Format with prettier +prettier --write '**/*.md' ``` ### 3. Commit Your Changes diff --git a/README.md b/README.md index d80e545..ddef08f 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ A comprehensive toolkit for developing Claude Code plugins with expert guidance ## Overview -The plugin-dev toolkit provides **9 specialized skills**, **3 validation agents**, and **3 slash commands** to help you build high-quality Claude Code plugins: +The plugin-dev toolkit provides **10 specialized skills**, **3 validation agents**, and **4 slash commands** to help you build high-quality Claude Code plugins: - **Skills** provide domain expertise loaded on-demand via trigger phrases - **Agents** automate validation and generation tasks @@ -130,7 +130,7 @@ Skills load automatically when you ask relevant questions. Each skill includes c Each skill provides: -- **Core SKILL.md** (~1,000-2,200 words) - Essential API reference +- **Core SKILL.md** (~1,500-2,500 words) - Essential API reference - **references/** - Detailed guides and patterns - **examples/** - Complete working code for copy-paste - **scripts/** - Validation and testing utilities @@ -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 index f47a6e9..1db39d4 100644 --- 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: | diff --git a/docs/component-patterns.md b/docs/component-patterns.md index 0570aba..d8d95a9 100644 --- a/docs/component-patterns.md +++ b/docs/component-patterns.md @@ -10,8 +10,14 @@ Agents require YAML frontmatter with: - `description`: Starts with "Use this agent when...", includes `` blocks - `model`: inherit/sonnet/opus/haiku - `color`: blue/cyan/green/yellow/magenta/red -- `tools`: Comma-separated list of allowed tools (optional) +- `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`: 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) +- `hooks`: Lifecycle hooks scoped to agent (optional) ## Skills @@ -43,20 +49,28 @@ Commands are markdown files with frontmatter: ## Skills/Agents Optional Frontmatter -Both skills and agents support `allowed-tools` to restrict tool access: +**Skills** use `allowed-tools`: ```yaml allowed-tools: Read, Grep, Glob # Read-only skill ``` -Use for read-only workflows, security-sensitive tasks, or limited-scope operations. +**Agents** use `tools` (allowlist) or `disallowedTools` (denylist): + +```yaml +tools: Read, Grep, Glob # Allowlist +# OR +disallowedTools: Bash, Write # Denylist +``` + +> **Note:** Field names differ — skills use `allowed-tools`, agents use `tools`/`disallowedTools`. ## Hooks Hooks defined in `hooks/hooks.json`: -- Events: PreToolUse, PermissionRequest, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification -- Types: `prompt` (LLM-driven) or `command` (bash scripts) +- 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", "\*") ### Plugin hooks.json Format diff --git a/docs/release-procedure.md b/docs/release-procedure.md index d3a907e..0908d52 100644 --- 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/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 508d44d..a5e834c 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.4.0", + "version": "0.4.1", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 3c1322c..fa7626a 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -1,7 +1,6 @@ --- name: agent-development -version: 0.2.0 -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", "maxTurns", "agent memory", "mcpServers in agent", "agent hooks", "background agent", "resume agent", "agent teams", "permission rules", "permission mode", "delegate mode", "agent team", "team lead", "teammate", "multi-agent", 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 @@ -252,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: @@ -281,15 +301,73 @@ permissionMode: acceptEdits **Values:** -- `acceptEdits` - Auto-accept file edit operations (Write, Edit) +- `default` - Standard permission model, prompts user for each action (implicit when omitted) +- `acceptEdits` - Auto-accept file edit operations (Write, Edit, NotebookEdit) - `dontAsk` - Skip permission dialogs for all operations - `bypassPermissions` - Full bypass (requires trust) - `plan` - Planning mode, propose changes without executing +- `delegate` - Coordination-only, restricted to team management tools (spawn, message, manage tasks) **Default:** Standard permission model (asks user) **Security note:** Use restrictive modes (`plan`, `acceptEdits`) for untrusted agents. `bypassPermissions` should only be used for fully trusted agents. +See `references/permission-modes-rules.md` for complete permission mode details and rule syntax. + +### maxTurns (optional) + +Limit the maximum number of agentic turns before the agent stops: + +```yaml +maxTurns: 50 +``` + +**Use cases:** + +- Prevent runaway agents from consuming excessive resources +- Set reasonable bounds for task complexity +- Higher values (50-100) for complex multi-file tasks; lower values (10-20) for focused checks + +If omitted, the agent runs until it completes or the user interrupts. + +### memory (optional) + +Enable persistent memory across sessions: + +```yaml +memory: user +``` + +**Scopes:** `user` (~/.claude/agent-memory/), `project` (.claude/agent-memory/), `local` (.claude/agent-memory-local/) + +When enabled, the agent's first 200 lines of `MEMORY.md` are auto-injected into its system prompt. The agent can read/write its memory directory to learn across sessions. See `references/advanced-agent-fields.md` for details. + +### mcpServers (optional) + +Scope MCP servers to this agent: + +```yaml +mcpServers: + slack: +``` + +Reference an already-configured server by name, or provide inline config. Restricts which MCP servers the agent can access. See `references/advanced-agent-fields.md` for configuration examples. + +### hooks (optional) + +Define lifecycle hooks scoped to this agent: + +```yaml +hooks: + PreToolUse: + - matcher: Bash + hooks: + - type: command + command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bash.sh" +``` + +Supports all hook events. Note: `Stop` hooks in agent frontmatter are auto-converted to `SubagentStop` at runtime. Hooks activate when the agent starts and deactivate when it finishes. See `references/advanced-agent-fields.md` for full details. + ### Fields NOT Available for Agents Some frontmatter fields are specific to skills and do not apply to agents: @@ -411,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: @@ -471,15 +551,20 @@ Ensure system prompt is complete: ### Frontmatter Fields Summary -| Field | Required | Format | Example | -| -------------- | -------- | -------------------------- | ------------------------ | -| name | Yes | lowercase-hyphens | code-reviewer | -| description | Yes | Text + examples | Use when... ... | -| 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... ... | +| 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 | +| maxTurns | No | Integer | 50 | +| memory | No | Scope string | user | +| mcpServers | No | Server name map | slack: | +| hooks | No | Hook event map | PreToolUse: [...] | > **Note:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. The field names differ between component types. @@ -503,6 +588,31 @@ Ensure system prompt is complete: - ❌ Write vague system prompts - ❌ Skip testing +## Execution Modes + +Agents can run in foreground (blocking) or background (concurrent) mode: + +- **Foreground** (default): Blocks the main conversation until the agent completes +- **Background**: Runs concurrently; permissions must be pre-approved at spawn time since the user can't be prompted + +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. + +**Built-in agent types:** Explore (read-only, Haiku), Plan (read-only research), general-purpose (all tools), Bash (terminal commands), statusline-setup (Haiku), Claude Code Guide (Haiku). + +## Agent Teams (Experimental) + +Agent teams enable multi-agent coordination where a team lead spawns and manages multiple independent Claude Code sessions as teammates. Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. + +Teams provide shared task lists, inter-agent messaging, and parallel execution. Use `permissionMode: delegate` to restrict a lead to coordination-only tools. + +This is an advanced feature — see the [official agent teams documentation](https://code.claude.com/docs/en/agent-teams) for details. + ## Additional Resources ### Reference Files @@ -512,6 +622,8 @@ For detailed guidance, consult: - **`references/system-prompt-design.md`** - Four system prompt patterns (Analysis, Generation, Validation, Orchestration) with complete templates and common pitfalls - **`references/triggering-examples.md`** - Example block anatomy, four example types, template library, and debugging guide - **`references/agent-creation-system-prompt.md`** - The exact prompt used by Claude Code's agent generation feature with usage patterns +- **`references/advanced-agent-fields.md`** - Detailed docs for maxTurns, memory, mcpServers, hooks, execution modes, and agent teams +- **`references/permission-modes-rules.md`** - Complete permission mode details and permission rule syntax for fine-grained access control ### Example Files 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 new file mode 100644 index 0000000..447314d --- /dev/null +++ b/plugins/plugin-dev/skills/agent-development/references/advanced-agent-fields.md @@ -0,0 +1,246 @@ +# Advanced Agent Fields + +This reference covers agent frontmatter fields beyond the core fields (name, description, model, color, tools, disallowedTools, skills, permissionMode). These enable turn limits, persistent memory, scoped MCP access, lifecycle hooks, and advanced execution patterns. + +## maxTurns + +Limit the maximum number of agentic turns (API round-trips) before the agent stops. + +```yaml +maxTurns: 50 +``` + +### Choosing Values + +| Task Type | Suggested Range | Rationale | +| ----------------------------- | --------------- | ------------------------------- | +| Quick checks, linting | 5-15 | Focused, fast completion | +| Code review, analysis | 20-40 | Needs to read multiple files | +| Complex refactoring, creation | 50-100 | Multi-file changes with testing | + +If omitted, the agent runs until it completes or is interrupted. Set `maxTurns` to prevent runaway agents from consuming excessive resources, especially for background agents where there's no user to interrupt. + +## memory + +Enable persistent memory that survives across sessions. + +```yaml +memory: user +``` + +### Scopes + +| Scope | Directory | Use When | +| --------- | ------------------------------------------ | -------------------------------- | +| `user` | `~/.claude/agent-memory//` | Personal preferences, defaults | +| `project` | `.claude/agent-memory//` | Codebase-specific knowledge | +| `local` | `.claude/agent-memory-local//` | Gitignored project-specific data | + +### How It Works + +When `memory` is set: + +1. System prompt includes instructions for reading/writing the memory directory +2. First 200 lines of `MEMORY.md` are auto-injected into the agent's system prompt +3. Read, Write, and Edit tools are automatically enabled (even if not in `tools` list) +4. Agent should curate `MEMORY.md` if it exceeds 200 lines + +### Best Practices + +- Use `user` scope as the default for most agents +- Use `project` or `local` for codebase-specific learning +- Include memory management instructions in the agent's system prompt (e.g., "After completing a task, update your MEMORY.md with key learnings") + +## mcpServers + +Scope MCP servers to the agent, controlling which external services it can access. + +### Reference by Name + +Reference an already-configured MCP server: + +```yaml +mcpServers: + slack: +``` + +The agent inherits the full configuration of the named server from the project/user MCP settings. + +### Inline Configuration + +Provide full server config scoped to the agent: + +```yaml +mcpServers: + custom-api: + command: "${CLAUDE_PLUGIN_ROOT}/servers/api-server" + args: ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"] + env: + API_KEY: "${API_KEY}" +``` + +### Use Cases + +- Restrict a code review agent to only read-only MCP tools +- Give a deployment agent access to CI/CD servers but not database servers +- Provide agent-specific server configuration + +## hooks + +Define lifecycle hooks scoped to the agent. These hooks activate when the agent starts and deactivate when it finishes. + +### Format + +```yaml +hooks: + PreToolUse: + - matcher: Write + hooks: + - type: command + command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh" + timeout: 10 + Stop: + - hooks: + - type: prompt + prompt: "Verify all tasks are complete before stopping." +``` + +### Supported Events + +All hook events are supported in agent frontmatter. Key behavior difference: + +- **`Stop`** hooks are automatically converted to **`SubagentStop`** at runtime, since agents are subprocesses +- Hooks only run while the agent is active and are cleaned up when the agent finishes + +### Comparison with hooks.json + +| Aspect | `hooks.json` | Agent frontmatter `hooks` | +| -------- | ------------------------------------------ | ----------------------------------------------- | +| Scope | Global (always active when plugin enabled) | Agent-specific (active only during agent run) | +| Events | All hook events | All events (Stop auto-converts to SubagentStop) | +| Location | `hooks/hooks.json` file | YAML frontmatter in agent .md file | +| Use case | Plugin-wide validation | Agent-specific safety checks | + +## Execution Modes + +### Background vs Foreground + +- **Foreground** (default): Blocks the main conversation until the agent completes. User can interact if the agent requests permission. +- **Background**: Runs concurrently with the main conversation. All permissions must be pre-approved at spawn time since the user cannot be prompted. + +Background agents that encounter an unapproved permission request will fail. Design tool restrictions (`tools`, `permissionMode`) accordingly when agents may run in background. + +### Resuming Agents + +Each Task tool invocation creates a new agent instance with a fresh context. To continue with the full prior context preserved, ask Claude to "resume that agent" or "continue that subagent" — it will restore the previous transcript. + +Agent transcripts are stored at `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl`. + +### Restricting Spawnable Agent Types + +Use `Task(agent_type1, agent_type2)` syntax in settings.json allow rules to control which agent types can be spawned: + +```json +{ + "permissions": { + "allow": ["Task(code-reviewer, test-runner)"] + } +} +``` + +- `Task(type1, type2)` — only these agent types can be spawned +- `Task` (no parentheses) — allow any subagent +- Omitting `Task` entirely — cannot spawn any subagents + +## Built-in Agent Types + +Claude Code includes several built-in agent types that can be referenced in the `agent` field of skills or used as targets for `Task()` restrictions: + +| Agent Type | Model | Tools | Purpose | +| ------------------- | ------- | --------- | ----------------------------------- | +| `Explore` | Haiku | Read-only | Fast codebase exploration/search | +| `Plan` | Inherit | Read-only | Codebase research during planning | +| `general-purpose` | Inherit | All | Complex multi-step tasks | +| `Bash` | Inherit | Bash | Terminal commands in isolation | +| `statusline-setup` | Haiku | Read/Edit | Status line configuration | +| `Claude Code Guide` | Haiku | Read-only | Documentation and feature questions | + +## Agent Teams (Experimental) + +Agent teams enable multi-agent coordination where a team lead spawns and manages multiple independent Claude Code sessions as teammates. This is an experimental feature requiring `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. + +### Key Concepts + +- **Team lead**: Main session that creates the team, spawns teammates, and coordinates work +- **Teammates**: Independent Claude Code instances with their own context windows +- **Shared task list**: Coordinated work items that teammates claim and complete +- **Messaging**: Direct messages and broadcasts between team members + +### Designing Team Lead Agents + +Team leads coordinate work across multiple teammates. Key design considerations: + +- **Use `permissionMode: delegate`** to restrict the lead to coordination-only tools (spawn, message, shut down teammates, manage tasks). This prevents the lead from implementing tasks directly. +- **System prompt focus**: Task decomposition, work assignment, progress monitoring, quality review +- **Tools**: Team leads automatically get access to `TeamCreate`, `TaskCreate`, `TaskUpdate`, `TaskList`, `SendMessage`, and `Task` (for spawning) + +```yaml +# Example team lead agent +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: + +- **Self-contained context**: Each teammate has its own context window; don't assume shared state +- **Task-focused prompts**: System prompt should focus on a specific type of work (e.g., "you are a test writer") +- **Tool restrictions**: Use `tools` to limit what each teammate can do based on their role +- **Plan mode for review**: Use `permissionMode: plan` for teammates that should propose changes for lead approval + +### Display Modes + +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 + +Use hook events to enforce quality standards in team workflows: + +| Event | Fires When | Use Case | +| --------------- | ---------------------------- | --------------------------------------------- | +| `TeammateIdle` | A teammate finishes its turn | Trigger code review, run tests on changes | +| `TaskCompleted` | A task is marked complete | Validate deliverables, update documentation | +| `SubagentStart` | A teammate spawns | Log team activity, enforce naming conventions | +| `SubagentStop` | A teammate finishes | Clean up resources, collect metrics | + +### Plan Approval Mode + +Teammates can be configured to require plan approval from the team lead before implementing: + +1. Teammate uses `permissionMode: plan` +2. Teammate explores codebase and creates a plan +3. Teammate calls `ExitPlanMode`, which sends plan to team lead +4. Team lead reviews and approves/rejects via `SendMessage` with `plan_approval_response` +5. On approval, teammate exits plan mode and proceeds with implementation + +This pattern is useful for complex tasks where the lead wants to review approach before execution. + +For complete documentation, see the [official agent teams guide](https://code.claude.com/docs/en/agent-teams). 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 new file mode 100644 index 0000000..8e44eae --- /dev/null +++ b/plugins/plugin-dev/skills/agent-development/references/permission-modes-rules.md @@ -0,0 +1,226 @@ +# Permission Modes & Rules Reference + +This reference covers the complete permission system for Claude Code agents, including all permission modes and the permission rule syntax for fine-grained access control. + +## Permission Modes + +Agents can specify a `permissionMode` in frontmatter to control how permission requests are handled: + +```yaml +permissionMode: acceptEdits +``` + +### All Permission Modes + +| Mode | Behavior | Use Case | +| ------------------- | ------------------------------------------------------------ | --------------------------------------------------- | +| `default` | Standard permission model — prompts user for each action | General-purpose agents, untrusted contexts | +| `acceptEdits` | Auto-accept file edit operations (Write, Edit, NotebookEdit) | Code generation agents that need to write files | +| `dontAsk` | Skip all permission dialogs | Trusted automation agents, CI/CD agents | +| `bypassPermissions` | Full bypass of all permission checks | Fully trusted agents only | +| `plan` | Planning mode — propose changes without executing | Architecture/design agents, review agents | +| `delegate` | Coordination-only — restricted to team management tools | Team lead agents that should not implement directly | + +### Mode Details + +#### default + +The standard interactive permission model. Claude asks the user before performing actions that require permission. This is the implicit mode when `permissionMode` is not specified. + +**When to use:** General-purpose agents, agents handling sensitive operations, agents in untrusted contexts. + +#### acceptEdits + +Auto-accepts file writing operations (Write, Edit, NotebookEdit) without prompting. Other operations (Bash, etc.) still require user permission. + +**When to use:** Code generation agents, refactoring agents, documentation generators. + +#### dontAsk + +Skips all permission dialogs. The agent proceeds without user confirmation for any action. + +**When to use:** Trusted automation, background agents, CI/CD pipelines where no user is present. + +#### bypassPermissions + +Full permission bypass with no restrictions. More permissive than `dontAsk` as it bypasses even system-level restrictions. + +**When to use:** Only for fully trusted agents in controlled environments. Never for plugins distributed to unknown users. + +#### plan + +Planning mode restricts the agent to read-only operations. The agent can explore the codebase and propose changes but cannot execute them. Requires user approval before any modifications. + +**When to use:** Architecture planning, design review, impact analysis agents. + +#### delegate + +Restricts the agent to team coordination tools only: spawning teammates, sending messages, managing tasks, and shutting down teammates. The agent cannot use implementation tools (Edit, Write, Bash, etc.) directly. + +**When to use:** Team lead agents that should coordinate work across teammates without implementing tasks themselves. + +```yaml +# Team lead agent that only coordinates +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. + +### Rule Syntax + +Rules are specified in `settings.json` under `permissions`: + +```json +{ + "permissions": { + "allow": ["Read", "Bash(npm test)", "Edit(src/**)"], + "deny": ["Bash(rm *)", "Bash(git push --force*)"] + } +} +``` + +### Tool Specifiers + +| Pattern | Matches | Example | +| -------------------- | ------------------------------- | ------------------------------------ | +| `ToolName` | Any use of that tool | `Read` — all file reads | +| `ToolName(argument)` | Tool with specific argument | `Bash(npm test)` — only this command | +| `ToolName(pattern*)` | Tool with wildcard argument | `Bash(npm *)` — any npm command | +| `Edit(path)` | Edit with gitignore-style path | `Edit(src/**)` — edits in src/ | +| `Write(path)` | Write with gitignore-style path | `Write(tests/**)` — writes in tests/ | + +### MCP Tool Patterns + +```json +{ + "permissions": { + "allow": ["mcp__servername__toolname", "mcp__servername__*"] + } +} +``` + +- `mcp__server__tool` — specific MCP tool +- `mcp__server__*` — all tools from a server +- `mcp__*` — all MCP tools (use sparingly) + +### Task (Agent) Patterns + +Control which agent types can be spawned: + +```json +{ + "permissions": { + "allow": ["Task(code-reviewer, test-runner)"] + } +} +``` + +- `Task(type1, type2)` — only listed agent types +- `Task` — allow any subagent +- Omitting `Task` — no subagent spawning + +### Rule Precedence + +When multiple rules match: + +1. **deny** rules always take precedence over **allow** rules +2. More specific rules take precedence over general ones +3. Explicit rules override `permissionMode` settings + +### Plugin Developer Guidance + +**Document required permissions:** If your plugin's agents need specific tool access, document the minimum required permissions in your README: + +```markdown +## Required Permissions + +This plugin's agents need: + +- `Edit(src/**)` — to modify source files +- `Bash(npm test)` — to run tests +- `mcp__plugin_myserver__*` — for MCP tool access +``` + +**Configure agent permissions:** Use `permissionMode` in agent frontmatter for broad access control. For fine-grained restrictions, document the settings users should configure. + +**Principle of least privilege:** Request only the permissions your agent actually needs. Use `acceptEdits` over `dontAsk` when only file writes are needed. diff --git a/plugins/plugin-dev/skills/command-development/SKILL.md b/plugins/plugin-dev/skills/command-development/SKILL.md index f74d883..610860d 100644 --- a/plugins/plugin-dev/skills/command-development/SKILL.md +++ b/plugins/plugin-dev/skills/command-development/SKILL.md @@ -1,7 +1,7 @@ --- name: command-development version: 0.2.0 -description: This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", "Skill tool", "programmatic command invocation", "disable-model-invocation", "prevent Claude from running command", "debug command", "command debugging", "troubleshoot command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, programmatic invocation control, debugging commands, or command development best practices for Claude Code. +description: This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", "Skill tool", "programmatic command invocation", "disable-model-invocation", "prevent Claude from running command", "debug command", "command debugging", "troubleshoot command", "commands vs skills", "Skill tool mechanism", "load-time injection", "runtime execution", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, programmatic invocation control, debugging commands, or command development best practices for Claude Code. --- # Command Development for Claude Code @@ -394,6 +394,28 @@ This is intentional. When skill content loads into Claude's context, `[BANG]` fo **Implementation details:** For advanced patterns, environment-specific configurations, and plugin integration, see `references/plugin-features-reference.md` +### 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. + +### Commands and Skills: Same Mechanism, Different Complexity + +Commands and skills are both invoked via the same **Skill tool**. The difference is organizational complexity: + +| Aspect | Commands | Skills | +| --------- | ------------------------------- | --------------------------------- | +| Location | `commands/` | `skills/name/` | +| Format | Single `.md` file | `SKILL.md` + optional resources | +| Resources | None | scripts/, references/, examples/ | +| Best for | Quick prompts, simple workflows | Complex knowledge, bundled assets | + +**Invocation control** (works for both): + +- `disable-model-invocation: true` → User-only (for side effects: deploy, commit) +- Default → Both Claude and user can invoke + +**When to graduate a command to a skill**: If you need scripts, reference files, or progressive disclosure, convert the command to a skill. See the `skill-development` skill for guidance. + ## Command Organization ### Flat Structure diff --git a/plugins/plugin-dev/skills/command-development/references/skill-tool.md b/plugins/plugin-dev/skills/command-development/references/skill-tool.md index c4b2571..a255a41 100644 --- a/plugins/plugin-dev/skills/command-development/references/skill-tool.md +++ b/plugins/plugin-dev/skills/command-development/references/skill-tool.md @@ -6,6 +6,8 @@ How Claude programmatically invokes slash commands and skills during conversatio The Skill tool enables Claude to programmatically execute both slash commands and Agent Skills without user typing. This allows Claude to autonomously invoke these capabilities as part of complex workflows, chain them together, or use them in response to user requests. +> **Key Insight:** Commands and skills are the same mechanism. Both are invoked via the Skill tool. Commands are simple (single `.md` file); skills are complex (directory with bundled resources). +> > **Note:** In earlier versions of Claude Code, slash command invocation was provided by a separate `SlashCommand` tool. This has been merged into the `Skill` tool. **Key concepts:** diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index 916e839..41050c4 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/plugins/plugin-dev/skills/hook-development/SKILL.md @@ -1,7 +1,6 @@ --- name: hook-development -version: 0.2.0 -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, StopFailure, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, Notification, ConfigChange, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove, InstructionsLoaded, Elicitation, ElicitationResult). 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", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, Notification, ConfigChange, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove, InstructionsLoaded, Elicitation, ElicitationResult). 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 @@ -90,6 +89,10 @@ Send event data to an HTTP endpoint: **Use for:** External service integration, centralized logging, webhook-driven workflows. +**Prompt hooks** work on most events (see [Hook Type Support by Event](#hook-type-support-by-event) for the full matrix). The only events restricted to command hooks are SessionStart, WorktreeCreate, and WorktreeRemove. + +**Response format:** Prompt hooks return the standard hook output JSON (`decision`, `reason`, `systemMessage`). For events with event-specific behavior (PreToolUse, PermissionRequest, Elicitation), include `hookSpecificOutput` with event-appropriate fields — see each event's documentation below and `references/event-schemas.md`. + ## Hook Configuration Formats ### Plugin hooks.json Format @@ -153,6 +156,49 @@ Each hook entry in a matcher group supports these fields: **Important:** The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{"hooks": {...}}`. +### Plugin Hook Configuration + +Define hooks in `hooks/hooks.json` using the plugin wrapper format: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bash.sh" + } + ] + } + ] + } +} +``` + +Plugin hooks merge with user hooks and run in parallel. + +### Scoped Hooks in Skill/Agent Frontmatter + +Hooks can be defined directly in YAML frontmatter of skills and agents: + +```yaml +hooks: + PreToolUse: + - matcher: Write + hooks: + - type: command + command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh" +``` + +**Supported events in frontmatter:** `PreToolUse`, `PostToolUse`, `Stop` + +These hooks are lifecycle-bound -- they activate when the skill/agent loads and deactivate when it finishes. Use for skill-specific validation that shouldn't apply globally. + +See `references/advanced.md` for details. + ## Hook Events ### Session Lifecycle @@ -1016,7 +1062,7 @@ echo "$output" | jq . | ------------------ | ------------- | --------------------------- | ----------------------------- | | SessionStart | Lifecycle | startup, resume, clear, compact | continue, env vars | | InstructionsLoaded | Lifecycle | session_start, nested_traversal, path_glob_match, include, compact | None (observability) | -| SessionEnd | Lifecycle | clear, logout, prompt_input_exit, bypass_permissions_disabled, other | None (observability) | +| SessionEnd | Lifecycle | clear, logout, prompt_input_exit, bypass_permissions_disabled, resume, other | None (observability) | | UserPromptSubmit | Input | None | Block prompt | | PreToolUse | Tool | Tool names (regex) | Allow/deny/ask, modify input | | PermissionRequest | Tool | Tool names (regex) | Allow/deny, modify input | @@ -1060,6 +1106,7 @@ For detailed patterns and advanced techniques, consult: - **`references/patterns.md`** -- Proven patterns including temporarily active and configuration-driven hooks - **`references/migration.md`** -- Migrating from basic to advanced hooks - **`references/advanced.md`** -- Advanced use cases and techniques +- **`references/hook-input-schemas.md`** -- Per-event and per-tool input field documentation ### Example Hook Scripts diff --git a/plugins/plugin-dev/skills/hook-development/references/advanced.md b/plugins/plugin-dev/skills/hook-development/references/advanced.md index 01f5cfe..b44049c 100644 --- a/plugins/plugin-dev/skills/hook-development/references/advanced.md +++ b/plugins/plugin-dev/skills/hook-development/references/advanced.md @@ -169,6 +169,14 @@ Use transcript and session context for intelligent decisions: The LLM can read the transcript file and make context-aware decisions. +**Response format:** Agent hooks use the same response schema as prompt hooks: + +```json +{ "ok": true, "reason": "Explanation of decision" } +``` + +Agent hooks can also use tool access for multi-turn verification (up to 50 turns). Default timeout: 60 seconds. + ## Performance Optimization ### Caching Validation Results @@ -481,6 +489,383 @@ 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. + +## Handler Configuration Fields + +Beyond `type`, `command`/`prompt`, and `timeout`, hook handlers support additional fields: + +### once + +```json +{ + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/init.sh", + "once": true +} +``` + +When `true`, the hook runs only once per session and is then auto-removed. Useful for one-time initialization hooks in scoped contexts (skills/agents). + +### statusMessage + +```json +{ + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh", + "statusMessage": "Validating file write..." +} +``` + +Display text shown in the UI while the hook is executing. Helps users understand what's happening during longer hook operations. + +## Event-Specific Matchers + +Some hook events support matcher values beyond tool names: + +| Event | Matcher Values | +| ------------- | ------------------------------------------------------------------------------ | +| SessionStart | `startup`, `resume`, `clear`, `compact` | +| SessionEnd | `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` | +| Notification | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` | +| PreCompact | `manual`, `auto` | +| SubagentStart | Agent type name (e.g., `Bash`, `Explore`, `Plan`, or custom agent names) | +| SubagentStop | Agent type name (same as SubagentStart) | +| PreToolUse | Tool name (exact, regex, or `*` wildcard) | + +## Decision Control Output Schemas + +Different hook events support different output formats for controlling Claude's behavior. + +### PreToolUse Decision Control + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow|deny|ask", + "permissionDecisionReason": "Explanation", + "updatedInput": { "field": "modified_value" }, + "additionalContext": "Extra context for Claude" + } +} +``` + +- `permissionDecision`: `allow` (proceed), `deny` (block), `ask` (prompt user) +- `updatedInput`: Optionally modify tool parameters before execution +- `additionalContext`: Injected into Claude's context + +### PermissionRequest Decision Control + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionRequest", + "decision": { + "behavior": "allow|deny", + "updatedInput": {}, + "updatedPermissions": {}, + "message": "Reason for denial", + "interrupt": false + } + } +} +``` + +- `behavior`: `allow` or `deny` +- `updatedInput`: Modified tool parameters (only with `allow`) +- `updatedPermissions`: Permission changes (only with `allow`) +- `message`: Shown to user (only with `deny`) +- `interrupt`: If true with `deny`, stops the current operation + +### PostToolUse / Stop / UserPromptSubmit Decision Control + +These events share a simpler top-level schema: + +```json +{ + "decision": "block", + "reason": "Explanation of why the action is blocked" +} +``` + +- `decision`: Set to `"block"` to prevent the action (stopping, prompt processing, etc.) +- `reason`: Required when blocking; fed back to Claude or shown to user + +PostToolUse specifically supports an additional field for replacing MCP tool output: + +```json +{ + "updatedMCPToolOutput": "Replacement output for MCP tool response" +} +``` + +This allows hooks to replace what Claude sees as the MCP tool response before processing. Only applies to MCP tools in PostToolUse events. + +### PostToolUseFailure Decision Control + +PostToolUseFailure supports providing additional context to help Claude handle the failure: + +```json +{ + "additionalContext": "Extra context to help Claude handle the failure" +} +``` + +### TeammateIdle and TaskCompleted + +These events use **exit codes only** for decision control (no JSON output): + +- Exit code `0`: Allow (teammate goes idle / task marked complete) +- Exit code `2`: Block — stderr is fed back to the teammate/model as feedback + +### Common Output Fields (All Hooks) + +These fields can be included in any hook's JSON output: + +```json +{ + "continue": true, + "stopReason": "Critical error, halting all processing", + "suppressOutput": false, + "systemMessage": "Warning message for the user" +} +``` + +- `continue`: If `false`, halts all processing (default: `true`) +- `stopReason`: Message when `continue` is `false` +- `suppressOutput`: Hide hook output from transcript (default: `false`) +- `systemMessage`: Warning/info message shown to the user + +## TeammateIdle and TaskCompleted Events + +These events support quality gates in agent team workflows. + +### TeammateIdle + +Fires when a teammate is about to go idle (stop processing). Use to keep teammates working or validate their output. + +**Input schema:** + +```json +{ + "session_id": "...", + "teammate_name": "researcher", + "team_name": "my-project" +} +``` + +**Example hook:** + +```json +{ + "TeammateIdle": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-teammate.sh" + } + ] + } + ] +} +``` + +### TaskCompleted + +Fires when a task is marked complete. Use to verify task quality before accepting completion. + +**Input schema:** + +```json +{ + "session_id": "...", + "task_id": "123", + "task_subject": "Implement feature X", + "task_description": "...", + "teammate_name": "implementer", + "team_name": "my-project" +} +``` + +**Example hook:** + +```json +{ + "TaskCompleted": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/verify-task.sh" + } + ] + } + ] +} +``` + +## Async Hooks + +Command hooks can run asynchronously in the background without blocking the main flow: + +```json +{ + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-event.sh", + "async": true +} +``` + +**Key constraints:** + +- Only available on `type: "command"` hooks (not prompt or agent) +- Cannot block or control behavior — the action proceeds immediately +- Response fields (`decision`, `hookSpecificOutput`) have no effect +- Useful for logging, metrics collection, and fire-and-forget notifications +- Uses the same `timeout` field (default: 600 seconds) + ## 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. 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 new file mode 100644 index 0000000..0aaf27b --- /dev/null +++ b/plugins/plugin-dev/skills/hook-development/references/hook-input-schemas.md @@ -0,0 +1,145 @@ +# Hook Input Schemas + +Comprehensive reference for all hook input schemas. Every hook receives JSON via stdin containing common fields plus event-specific fields. + +## Common Fields (All Hooks) + +Every hook receives these fields: + +| Field | Type | Description | +| ----------------- | ------ | ------------------------------ | +| `session_id` | string | Unique session identifier | +| `transcript_path` | string | Path to conversation JSON | +| `cwd` | string | Current working directory | +| `permission_mode` | string | Current permission mode | +| `hook_event_name` | string | Event that triggered this hook | + +## Event-Specific Input Fields + +### PreToolUse / PostToolUse / PostToolUseFailure / PermissionRequest + +| Field | Type | Events | Description | +| ------------------------ | ------- | ------------------ | --------------------------------------------- | +| `tool_name` | string | All four | Name of the tool | +| `tool_input` | object | All four | Arguments sent to the tool (see tool schemas) | +| `tool_result` | string | PostToolUse | Tool execution result | +| `tool_use_id` | string | PostToolUse | Unique tool use identifier | +| `error` | string | PostToolUseFailure | Error message from the failed tool | +| `is_interrupt` | boolean | PostToolUseFailure | Whether failure was caused by user interrupt | +| `permission_suggestions` | array | PermissionRequest | Suggested permission decisions | + +### UserPromptSubmit + +| Field | Type | Description | +| -------- | ------ | ------------------------------ | +| `prompt` | string | The user-submitted prompt text | + +### Stop / SubagentStop + +| Field | Type | Events | Description | +| ----------------------- | ------- | ------------ | ----------------------------------------------- | +| `stop_hook_active` | boolean | Both | Whether hook is already continuing (loop guard) | +| `agent_id` | string | SubagentStop | Unique subagent identifier | +| `agent_type` | string | SubagentStop | Agent name | +| `agent_transcript_path` | string | SubagentStop | Path to subagent transcript | + +### SubagentStart + +| Field | Type | Description | +| ------------ | ------ | -------------------------- | +| `agent_id` | string | Unique subagent identifier | +| `agent_type` | string | Agent name | + +### SessionStart + +| Field | Type | Description | +| ------------ | ------ | ------------------------------------------------ | +| `source` | string | Matcher: `startup`, `resume`, `clear`, `compact` | +| `model` | string | Model identifier | +| `agent_type` | string | If running as an agent (optional) | + +### SessionEnd + +| Field | Type | Description | +| -------- | ------ | -------------------------------------------------------------------------------------- | +| `source` | string | Values: `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` | + +### PreCompact + +| Field | Type | Description | +| --------------------- | ------ | ------------------------------------------ | +| `trigger` | string | `manual` or `auto` | +| `custom_instructions` | string | User instructions (manual) or empty (auto) | + +### Notification + +| Field | Type | Description | +| ------------------- | ------ | ------------------------------------------------------------------------ | +| `message` | string | Notification text | +| `title` | string | Notification title (optional) | +| `notification_type` | string | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` | + +### TeammateIdle + +| Field | Type | Description | +| --------------- | ------ | ------------- | +| `teammate_name` | string | Teammate name | +| `team_name` | string | Team name | + +### TaskCompleted + +| Field | Type | Description | +| ------------------ | ------ | --------------------------- | +| `task_id` | string | Task identifier | +| `task_subject` | string | Task subject line | +| `task_description` | string | Task description (optional) | +| `teammate_name` | string | Teammate name (optional) | +| `team_name` | string | Team name (optional) | + +## Tool Input Schemas (for PreToolUse/PostToolUse) + +The `tool_input` object varies by tool. Common tool schemas: + +| Tool | `tool_input` Fields | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bash | `command` (string), `description` (string, optional), `timeout` (number, optional), `run_in_background` (boolean, optional) | +| Write | `file_path` (string), `content` (string) | +| Edit | `file_path` (string), `old_string` (string), `new_string` (string), `replace_all` (boolean, optional) | +| Read | `file_path` (string), `offset` (number, optional), `limit` (number, optional) | +| Glob | `pattern` (string), `path` (string, optional) | +| Grep | `pattern` (string), `path` (string, optional), `glob` (string, optional), `output_mode` (string, optional), `-i` (boolean, optional), `multiline` (boolean, optional) | +| WebFetch | `url` (string), `prompt` (string) | +| WebSearch | `query` (string), `allowed_domains` (array, optional), `blocked_domains` (array, optional) | +| Task | `prompt` (string), `description` (string), `subagent_type` (string), `model` (string, optional) | +| Skill | `skill` (string), `args` (string, optional) | +| NotebookEdit | `notebook_path` (string), `new_source` (string), `cell_type` (string, optional), `edit_mode` (string, optional) | + +## Practical Example + +Extracting fields in a bash hook script using `jq`: + +```bash +#!/bin/bash +set -euo pipefail + +# Read full input from stdin +input=$(cat) + +# Extract common fields +session_id=$(echo "$input" | jq -r '.session_id') +hook_event=$(echo "$input" | jq -r '.hook_event_name') + +# Extract tool-specific fields (PreToolUse/PostToolUse) +tool_name=$(echo "$input" | jq -r '.tool_name // empty') +file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty') +command=$(echo "$input" | jq -r '.tool_input.command // empty') + +# Example: block writes to sensitive paths +if [[ "$tool_name" == "Write" && "$file_path" == *".env"* ]]; then + echo '{"decision": "deny", "reason": "Cannot write to .env files"}' >&2 + exit 2 +fi + +# Allow by default +exit 0 +``` diff --git a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh index 8f387a2..f865adb 100755 --- a/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh +++ b/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh @@ -136,6 +136,12 @@ for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do echo "❌ ${event}[$i].hooks[$j]: $ht_label hooks must have 'prompt' field" ((error_count++)) fi + + # Check if prompt-based hooks are used on supported events + if [ "$hook_type" = "prompt" ] && [ "$event" != "Stop" ] && [ "$event" != "SubagentStop" ] && [ "$event" != "UserPromptSubmit" ] && [ "$event" != "PreToolUse" ]; then + echo "⚠️ ${event}[$i].hooks[$j]: Prompt hooks may not be fully supported on $event (best on Stop, SubagentStop, UserPromptSubmit, PreToolUse)" + ((warning_count++)) + fi ;; http) url=$(jq -r ".\"$event\"[$i].hooks[$j].url // empty" "$HOOKS_FILE") diff --git a/plugins/plugin-dev/skills/lsp-integration/SKILL.md b/plugins/plugin-dev/skills/lsp-integration/SKILL.md index 308e9d7..8158208 100644 --- a/plugins/plugin-dev/skills/lsp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/lsp-integration/SKILL.md @@ -1,7 +1,7 @@ --- name: lsp-integration version: 0.1.0 -description: This skill should be used when the user asks to "add LSP server", "configure language server", "set up LSP in plugin", "add code intelligence", "integrate language server protocol", "use pyright-lsp", "use typescript-lsp", "use rust-lsp", mentions LSP servers, or discusses extensionToLanguage mappings. Provides guidance for integrating Language Server Protocol servers into Claude Code plugins for enhanced code intelligence. +description: This skill should be used when the user asks to "add LSP server", "configure language server", "set up LSP in plugin", "add code intelligence", "integrate language server protocol", "use pyright-lsp", "use typescript-lsp", "use rust-lsp", "socket transport", "initializationOptions", mentions LSP servers, or discusses extensionToLanguage mappings. Provides guidance for integrating Language Server Protocol servers into Claude Code plugins for enhanced code intelligence. --- # LSP Integration for Claude Code Plugins @@ -92,9 +92,34 @@ Reference this file in `plugin.json`: } ``` -**transport** (optional): Communication transport - `stdio` (default) or `socket` +**transport** (optional): Communication transport - `stdio` (default) or `socket`. Socket transport connects to the server via TCP port instead of stdin/stdout: -**initializationOptions** (optional): Options passed to the server during LSP initialization +```json +{ + "lspServers": { + "dart": { + "transport": "socket", + "command": "dart", + "args": ["language-server", "--port", "8123"], + "extensionToLanguage": { ".dart": "dart" } + } + } +} +``` + +**initializationOptions** (optional): Options passed to the server during LSP initialization. Use this to configure server-specific behavior at startup: + +```json +{ + "initializationOptions": { + "typescript": { + "tsdk": "./node_modules/typescript/lib" + }, + "diagnostics": true, + "formatting": { "tabSize": 2 } + } +} +``` **settings** (optional): Settings passed via `workspace/didChangeConfiguration` @@ -366,13 +391,25 @@ Look for: "language": { "command": "${CLAUDE_PLUGIN_ROOT}/servers/lsp-server", "args": ["--stdio", "--log-level", "warn"], + "transport": "stdio", "extensionToLanguage": { ".ext1": "language", ".ext2": "language" }, "env": { "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config" - } + }, + "initializationOptions": { + "diagnostics": true + }, + "settings": { + "language": { "lint": { "enabled": true } } + }, + "workspaceFolder": "${workspaceFolder}", + "startupTimeout": 30000, + "shutdownTimeout": 5000, + "restartOnCrash": true, + "maxRestarts": 3 } } } diff --git a/plugins/plugin-dev/skills/marketplace-structure/SKILL.md b/plugins/plugin-dev/skills/marketplace-structure/SKILL.md index 6dedf21..72ceef0 100644 --- a/plugins/plugin-dev/skills/marketplace-structure/SKILL.md +++ b/plugins/plugin-dev/skills/marketplace-structure/SKILL.md @@ -1,7 +1,7 @@ --- name: marketplace-structure version: 0.1.0 -description: This skill should be used when the user asks to "create a marketplace", "set up marketplace.json", "organize multiple plugins", "distribute plugins", "host plugins", "marketplace schema", "plugin marketplace structure", "multi-plugin organization", or needs guidance on plugin marketplace creation, marketplace manifest configuration, or plugin distribution strategies. +description: This skill should be used when the user asks to "create a marketplace", "set up marketplace.json", "organize multiple plugins", "distribute plugins", "host plugins", "marketplace schema", "plugin marketplace structure", "multi-plugin organization", "strictKnownMarketplaces", "private marketplace", "marketplace auth", "pin plugin version", "hostPattern", or needs guidance on plugin marketplace creation, marketplace manifest configuration, or plugin distribution strategies. --- # Marketplace Structure @@ -153,6 +153,38 @@ For GitLab, Bitbucket, or self-hosted git: } ``` +### Pinning to Specific Versions + +Lock plugins to exact versions for reproducibility: + +```json +{ + "name": "github-plugin", + "source": { + "source": "github", + "repo": "owner/plugin-repo", + "ref": "v1.2.0", + "sha": "abc123def456..." + } +} +``` + +- `ref` — Branch, tag, or commit reference +- `sha` — Exact commit SHA for integrity verification + +### Host Pattern Sources + +Match any repository from a specific host: + +```json +{ + "name": "internal-plugin", + "source": { + "hostPattern": "https://git.company.com/*" + } +} +``` + ## Strict vs. Non-Strict Mode The `strict` field controls whether plugins must have their own `plugin.json`: @@ -181,6 +213,33 @@ Use `strict: false` when: } ``` +## Enterprise Features + +### Managed Marketplace Restrictions + +Organizations can restrict plugin sources via managed settings: + +- `strictKnownMarketplaces: true` — Only allow plugins from known/approved marketplaces +- `extraKnownMarketplaces` — Add organization-approved marketplace URLs in managed settings + +### Private Repository Authentication + +For private marketplace repositories, set authentication tokens: + +- `GITHUB_TOKEN` — GitHub private repos +- `GITLAB_TOKEN` — GitLab private repos +- `BITBUCKET_TOKEN` — Bitbucket private repos + +See `references/distribution-patterns.md` for detailed authentication setup. + +### Reserved Marketplace Names + +Anthropic reserves certain marketplace names. Avoid using names that could conflict with official marketplaces. + +### URL-Based Marketplace Limitations + +Relative paths in plugin source configurations may not resolve correctly in URL-based marketplaces. Use absolute paths or repository-based sources for reliable resolution. + ## Best Practices ### Organization diff --git a/plugins/plugin-dev/skills/marketplace-structure/references/distribution-patterns.md b/plugins/plugin-dev/skills/marketplace-structure/references/distribution-patterns.md index 76cc6e8..0a23469 100644 --- a/plugins/plugin-dev/skills/marketplace-structure/references/distribution-patterns.md +++ b/plugins/plugin-dev/skills/marketplace-structure/references/distribution-patterns.md @@ -223,12 +223,57 @@ Use git branches for experimental plugins: /plugin marketplace add owner/repo#feature-branch ``` +## Private Repository Authentication + +For marketplaces and plugins hosted in private repositories, Claude Code uses environment variables for authentication: + +| Service | Environment Variable | Format | +| --------- | -------------------- | ---------------------------- | +| GitHub | `GITHUB_TOKEN` | Personal access token or PAT | +| GitLab | `GITLAB_TOKEN` | Personal or project token | +| Bitbucket | `BITBUCKET_TOKEN` | App password or token | + +### Configuration + +Set the appropriate token before adding private marketplaces: + +```bash +# GitHub private repository +export GITHUB_TOKEN="ghp_xxxxxxxxxxxx" +/plugin marketplace add company/private-plugins + +# GitLab private repository +export GITLAB_TOKEN="glpat-xxxxxxxxxxxx" +/plugin marketplace add https://gitlab.company.com/team/plugins.git +``` + +Tokens are used for cloning and updating marketplace content. Ensure tokens have read access to the repository. + +### Team Distribution with Private Repos + +For teams, add the marketplace in project settings and document required environment variables: + +```json +{ + "extraKnownMarketplaces": { + "team-tools": { + "source": { + "source": "github", + "repo": "company/claude-plugins" + } + } + } +} +``` + +Team members must have `GITHUB_TOKEN` set with access to the private repository. + ## Security Considerations ### Access Control - **Public marketplaces**: Anyone can install plugins -- **Private repositories**: Only authorized users can access +- **Private repositories**: Only authorized users can access (via env tokens) - **Team settings**: Control which marketplaces are auto-installed ### Plugin Verification diff --git a/plugins/plugin-dev/skills/marketplace-structure/references/schema-reference.md b/plugins/plugin-dev/skills/marketplace-structure/references/schema-reference.md index 99d4d34..55bc289 100644 --- a/plugins/plugin-dev/skills/marketplace-structure/references/schema-reference.md +++ b/plugins/plugin-dev/skills/marketplace-structure/references/schema-reference.md @@ -120,7 +120,9 @@ Paths are relative to: { "source": { "source": "github", - "repo": "owner/repo-name" + "repo": "owner/repo-name", + "ref": "v1.0", + "sha": "abc123..." } } ``` @@ -129,6 +131,8 @@ Paths are relative to: | -------- | ------ | -------- | ---------------------------------------- | | `source` | string | Yes | Must be `"github"` | | `repo` | string | Yes | GitHub repository in `owner/repo` format | +| `ref` | string | No | Branch, tag, or commit reference | +| `sha` | string | No | Exact commit SHA for integrity pinning | ### Git URL (Object) @@ -138,15 +142,34 @@ For GitLab, Bitbucket, or self-hosted git repositories: { "source": { "source": "url", - "url": "https://gitlab.com/team/plugin.git" + "url": "https://gitlab.com/team/plugin.git", + "ref": "main" } } ``` -| Field | Type | Required | Description | -| -------- | ------ | -------- | ------------------ | -| `source` | string | Yes | Must be `"url"` | -| `url` | string | Yes | Full git clone URL | +| Field | Type | Required | Description | +| -------- | ------ | -------- | ------------------------------ | +| `source` | string | Yes | Must be `"url"` | +| `url` | string | Yes | Full git clone URL | +| `ref` | string | No | Branch or tag reference | +| `sha` | string | No | Exact commit SHA for integrity | + +### Host Pattern (Object) + +Match plugins by URL pattern for internal registries: + +```json +{ + "source": { + "hostPattern": "https://git.company.com/*" + } +} +``` + +| Field | Type | Required | Description | +| ------------- | ------ | -------- | ------------------------------ | +| `hostPattern` | string | Yes | URL pattern with `*` wildcards | ## Complete Plugin Entry Example @@ -256,3 +279,32 @@ plugin.json schema (all fields optional in marketplace entry) ``` This means any field valid in `plugin.json` can also be used in a marketplace entry. + +## Enterprise Settings + +Organizations can control marketplace behavior through managed settings: + +| Setting | Type | Description | +| ------------------------- | ------- | ----------------------------------------------------- | +| `strictKnownMarketplaces` | boolean | Only allow plugins from approved marketplaces | +| `enabledPlugins` | array | Pre-configured list of enabled plugins | +| `extraKnownMarketplaces` | object | Additional approved marketplaces beyond built-in ones | + +### Example Managed Settings + +```json +{ + "strictKnownMarketplaces": true, + "enabledPlugins": ["security-scanner@company-tools"], + "extraKnownMarketplaces": { + "company-tools": { + "source": { + "source": "github", + "repo": "company/claude-plugins" + } + } + } +} +``` + +These settings are configured by administrators and cannot be overridden by individual users. diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index 1e6ca6b..f4f0a65 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -1,7 +1,7 @@ --- name: mcp-integration version: 0.2.0 -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", "claude mcp serve", "allowedMcpServers", "deniedMcpServers", "managed MCP", "MCP scope", "MCP output limits", "MCP CLI commands". 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 @@ -17,6 +17,18 @@ Model Context Protocol (MCP) enables Claude Code plugins to integrate with exter - Handle OAuth and complex authentication flows - Bundle MCP servers with plugins for automatic setup +## MCP Scope System + +MCP server configurations follow scope precedence: Local > Project > User. + +| Scope | File | Shared in repo | +| ------- | --------------------------------- | -------------- | +| Local | `.claude/.mcp.local.json` | No | +| Project | `.claude/.mcp.json` or `.mcp.json`| Yes | +| User | `~/.claude/.mcp.json` | No | + +Plugin-bundled MCP servers auto-start and interact with user/project MCP configs. + ## MCP Server Configuration Methods Plugins can bundle MCP servers in two ways: @@ -213,6 +225,8 @@ All MCP configurations support environment variable substitution: } ``` +Env vars support fallback values: `${VAR:-default_value}`. Supported in `command`, `args`, `env`, `url`, and `headers` fields. + **Best practice:** Document all required environment variables in plugin README. ## MCP Tool Naming @@ -280,6 +294,12 @@ For MCP servers with many tools, use Tool Search to find relevant tools: This feature is automatic - just ask Claude about available tools or describe what you want to do. +### Tool Search Auto-Enable + +When MCP servers provide more tools than fit in context (default threshold: 10%), Claude Code activates tool search automatically. Control with `ENABLE_TOOL_SEARCH=auto:5` (custom percentage) or `ENABLE_TOOL_SEARCH=false` (disable). + +For plugins bundling many-tool MCP servers, document which tools are most commonly needed so users can pre-allow them. + ### Using MCP Tools in Commands Pre-allow specific MCP tools in command frontmatter: @@ -458,30 +478,24 @@ Pre-allow only necessary MCP tools: ❌ allowed-tools: mcp__plugin_api_server__* ``` -### Managed MCP Controls (Enterprise) - -Organizations can control MCP server access through managed settings: +### Managed MCP Controls -**Restrict allowed servers:** +Organizations can restrict MCP server usage via managed settings: ```json { - "mcpServers": { - "allowedServers": ["github", "internal-api"], - "blockedServers": ["*"] - } + "allowedMcpServers": [ + { "serverName": "github" }, + { "serverCommand": ["npx", "-y", "@company/mcp-server"] }, + { "serverUrl": "https://mcp.company.com/*" } + ], + "deniedMcpServers": [ + { "serverName": "untrusted-server" } + ] } ``` -**Disable MCP entirely:** - -```json -{ - "mcpServers": { - "enabled": false - } -} -``` +Three matcher types: `serverName`, `serverCommand`, `serverUrl`. These settings are configured by administrators and cannot be overridden by users or plugins. @@ -632,6 +646,40 @@ Look for: - ❌ Skip error handling - ❌ Forget to document setup +### Claude Code as MCP Server + +```bash +claude mcp serve +``` + +Enables other MCP-compatible clients to use Claude Code's tools. + +### Dynamic Tool Updates + +MCP servers can notify Claude Code of tool changes at runtime via `list_changed`. When implementing a plugin's MCP server, send `list_changed` notifications when available tools change dynamically. + +### MCP Output Limits + +- Warning threshold: 10,000 tokens +- Default maximum: 25,000 tokens +- Configure with `MAX_MCP_OUTPUT_TOKENS` environment variable + +Design plugin MCP tools to return concise results. Paginate or summarize large outputs. + +## MCP CLI Commands + +```bash +claude mcp add --transport stdio -- [args...] +claude mcp list +claude mcp get +claude mcp remove +claude mcp add-json '' +claude mcp add-from-claude-desktop +claude mcp reset-project-choices +``` + +Key flags: `--scope` (user/project/local), `--env KEY=VALUE`, `--callback-port` (OAuth). + ## Additional Resources ### Reference Files diff --git a/plugins/plugin-dev/skills/mcp-integration/references/authentication.md b/plugins/plugin-dev/skills/mcp-integration/references/authentication.md index 3bfc557..c763541 100644 --- a/plugins/plugin-dev/skills/mcp-integration/references/authentication.md +++ b/plugins/plugin-dev/skills/mcp-integration/references/authentication.md @@ -10,14 +10,18 @@ MCP servers support multiple authentication methods depending on the server type ### How It Works -Claude Code automatically handles the complete OAuth 2.0 flow for SSE and HTTP servers: +Claude Code automatically handles the complete OAuth 2.0 flow (with PKCE) for SSE and HTTP servers: 1. User attempts to use MCP tool -2. Claude Code detects authentication needed -3. Opens browser for OAuth consent -4. User authorizes in browser -5. Tokens stored securely by Claude Code -6. Automatic token refresh +2. Claude Code detects authentication is needed +3. Initiates OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange) +4. Opens browser for OAuth consent +5. User authorizes in browser +6. Claude Code exchanges the authorization code for tokens +7. Tokens stored securely by Claude Code +8. Automatic token refresh using refresh tokens + +PKCE provides additional security for public clients by preventing authorization code interception attacks. Claude Code also supports pre-configured OAuth credentials for MCP servers that provide them. ### Configuration @@ -84,6 +88,23 @@ Tokens are stored securely by Claude Code: - Claude Code auto-refreshes - If refresh fails, prompts re-authentication +## CLI OAuth Setup + +For MCP servers requiring OAuth 2.0, use CLI flags to pre-configure credentials: + +```bash +claude mcp add --transport http my-service https://api.example.com/mcp \ + --client-id "your-client-id" \ + --client-secret \ + --callback-port 8080 +``` + +- `--client-id` — OAuth client ID +- `--client-secret` — prompts for secret (hidden input); or set `MCP_CLIENT_SECRET` env var +- `--callback-port` — local port for OAuth callback (default varies by server) + +For interactive OAuth setup, use the `/mcp` command within Claude Code to authenticate via browser. + ## Token-Based Authentication ### Bearer Tokens diff --git a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md b/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md index bd61bfe..ca0f0d3 100644 --- a/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md +++ b/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. diff --git a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md index 31a0d2e..2da95d0 100644 --- a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md @@ -140,6 +140,30 @@ Use when the user needs to: - Distribute plugins to teams - Organize plugin collections +## Decision Tree for Skill Selection + +``` +User wants to... +├── Create/organize a plugin structure? → plugin-structure +├── Add a simple slash command (no bundled resources)? → command-development +├── Create an autonomous agent? → agent-development +├── Add a complex skill with scripts/references? → skill-development +├── React to Claude Code events? → hook-development +├── Integrate external service/API? → mcp-integration +├── Add code intelligence/LSP? → lsp-integration +├── Make plugin configurable? → plugin-settings +└── Distribute multiple plugins? → marketplace-structure +``` + +## Available Commands + +| Command | Purpose | +| -------------------------------- | --------------------------------------------------- | +| `/plugin-dev:plugin-dev-guide` | Overview and skill routing | +| `/plugin-dev:start` | Entry point - choose plugin or marketplace creation | +| `/plugin-dev:create-plugin` | 8-phase guided plugin creation workflow | +| `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow | + ## Common Multi-Skill Workflows ### Building a Complete Plugin diff --git a/plugins/plugin-dev/skills/plugin-settings/SKILL.md b/plugins/plugin-dev/skills/plugin-settings/SKILL.md index eb16800..59286d1 100644 --- a/plugins/plugin-dev/skills/plugin-settings/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-settings/SKILL.md @@ -1,7 +1,7 @@ --- name: plugin-settings version: 0.1.0 -description: This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content. +description: This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", "CLAUDE.md imports", "rules system", "memory hierarchy", "memory priority", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content. --- # Plugin Settings Pattern for Claude Code Plugins @@ -526,6 +526,16 @@ if [[ ! -f ".claude/my-plugin.local.md" ]]; then fi ``` +## Memory & Rules Context + +### Settings Scope Precedence + +Settings follow precedence: Managed > CLI flags > Local (`.claude/settings.local.json`) > Project (`.claude/settings.json`) > User (`~/.claude/settings.json`). Plugin hooks and MCP servers are merged across scopes, not replaced. A plugin-settings `.local.md` file is separate from this system -- it's a custom per-project state file your plugin reads directly. + +Plugin settings files (`.local.md`) exist alongside Claude Code's broader memory and rules system. Understanding how CLAUDE.md imports, `.claude/rules/` path-specific rules, and the memory priority hierarchy interact with plugin content helps design plugins that complement rather than conflict with user configurations. + +See `references/memory-rules-system.md` for the full priority hierarchy, import syntax, and design implications. + ## Additional Resources ### Reference Files @@ -534,6 +544,7 @@ For detailed implementation patterns: - **`references/parsing-techniques.md`** - Complete guide to parsing YAML frontmatter and markdown bodies - **`references/real-world-examples.md`** - Deep dive into multi-agent-swarm and ralph-wiggum implementations +- **`references/memory-rules-system.md`** - How plugin content interacts with CLAUDE.md, rules, and the memory hierarchy ### Example Files diff --git a/plugins/plugin-dev/skills/plugin-settings/references/memory-rules-system.md b/plugins/plugin-dev/skills/plugin-settings/references/memory-rules-system.md new file mode 100644 index 0000000..4d38c1e --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-settings/references/memory-rules-system.md @@ -0,0 +1,217 @@ +# Memory & Rules System Interaction + +Claude Code has a layered memory and rules system that plugins interact with. Understanding this system helps plugin developers design components that complement (rather than conflict with) the user's existing configuration. + +## CLAUDE.md Memory Files + +### What They Are + +CLAUDE.md files provide persistent instructions that Claude reads at the start of every session. They contain project context, coding standards, and behavioral guidance. + +### File Locations and Priority + +Memory files are loaded in priority order (highest first): + +| Priority | Location | Scope | +| ----------- | ------------------------------------ | ----------------------------- | +| 1 (highest) | Managed policy (system paths) | Organization-wide | +| 2 | `.claude/CLAUDE.md` or `./CLAUDE.md` | Project (shared via git) | +| 3 | `.claude/rules/*.md` | Project rules (modular) | +| 4 | `~/.claude/CLAUDE.md` | User (personal, all projects) | +| 5 (lowest) | `.claude/CLAUDE.local.md` | Project local (gitignored) | + +Higher-priority instructions take precedence when there are conflicts. + +**Why local is lowest priority:** Unlike typical configuration systems where ".local" means "override", Claude Code's `.local.md` files are for personal, project-specific notes and preferences that shouldn't override team standards. The hierarchy ensures organizational policy (managed) > team standards (project) > personal preferences (user/local). + +### Import Syntax + +CLAUDE.md files can import other files: + +```markdown +# Project Instructions + +@docs/coding-standards.md +@docs/api-conventions.md +``` + +**Rules:** + +- Paths are relative to the importing file +- Absolute paths are also supported +- Maximum recursion depth: 5 hops +- Imports are NOT evaluated inside code blocks or inline code spans +- Circular imports are detected and handled + +### Creating CLAUDE.md + +The `/init` command generates a starter CLAUDE.md by analyzing the codebase. Alternatively, create one manually: + +```markdown +# Project Name + +## Code Style + +- Use TypeScript strict mode +- Follow Prettier defaults + +## Architecture + +- Components in src/components/ +- API routes in src/api/ + +## Testing + +- Write tests for all new features +- Use Jest with React Testing Library +``` + +### Auto-Memory (MEMORY.md) + +Claude Code can automatically persist learnings between sessions using memory files: + +- **`MEMORY.md`**: Auto-generated file where Claude stores session-to-session learnings +- **Topic files**: Claude may create topic-specific memory files (e.g., `MEMORY-debugging.md`) for organized knowledge + +**Plugin interaction:** + +- Plugins should not write to or modify the user's auto-memory files +- Plugin agents with `memory` frontmatter use a separate, agent-specific memory directory (see agent-development skill) +- If your plugin generates knowledge worth persisting, instruct users to save it to CLAUDE.md rather than relying on auto-memory + +**Import syntax note:** The `@path` import syntax works in all CLAUDE.md files (project, user, local), not just the root one. This enables modular configuration: + +```markdown +# My CLAUDE.md + +@docs/coding-standards.md +@.claude/plugin-config.md +``` + +## Rules System + +### What Rules Are + +Rules are modular instruction files in `.claude/rules/` that can optionally target specific file patterns. They provide focused guidance that loads contextually. + +### File Structure + +``` +.claude/ +└── rules/ + ├── testing.md # Applies globally + ├── api-patterns.md # Applies globally + └── typescript.md # Path-specific (see below) +``` + +### Path-Specific Rules + +Rules can target specific files using YAML frontmatter with glob patterns: + +```markdown +--- +paths: + - "src/**/*.ts" + - "lib/**/*.ts" +--- + +Use strict TypeScript patterns: + +- No `any` types +- Explicit return types on all public functions +- Use discriminated unions over type assertions +``` + +**Glob support:** + +- Standard patterns: `*`, `?`, `**` +- Brace expansion: `src/**/*.{ts,tsx}` +- Multiple patterns in the `paths` array +- Patterns match against relative paths from project root + +### When Rules Load + +Rules load automatically based on file context: + +- Global rules (no `paths` frontmatter): Always loaded +- Path-specific rules: Loaded when Claude accesses matching files +- Rules in subdirectories: Organized by topic, all discovered automatically + +### User-Level Rules + +Personal rules in `~/.claude/rules/` apply across all projects with lower priority than project rules. + +## How Plugin Content Fits + +### Plugin Content Priority + +Plugin content loads differently from the memory/rules hierarchy: + +| Content Type | How It Loads | Priority Context | +| --------------------- | -------------------------------------- | ----------------------------------- | +| Skill descriptions | As tool definitions (always available) | Independent of memory hierarchy | +| Skill body (SKILL.md) | When skill triggers | Independent of memory hierarchy | +| Agent definitions | As subagent configs | Independent of memory hierarchy | +| Hook configurations | Merge with user/project hooks | Parallel execution with other hooks | +| MCP servers | As tool providers | Independent of memory hierarchy | + +Plugin content doesn't directly compete with CLAUDE.md for priority — it operates through different mechanisms (tool definitions, hooks, MCP tools). + +### Where They Overlap + +Conflicts can arise when: + +1. **CLAUDE.md instructions contradict plugin skill guidance** — CLAUDE.md has implicit priority as it's always in context +2. **Project rules specify patterns that conflict with plugin hooks** — Both apply; hooks enforce, rules guide +3. **User settings restrict tools that plugins need** — User settings win; plugins should document requirements + +## Design Implications for Plugin Developers + +### Don't Duplicate CLAUDE.md Content + +If a project's CLAUDE.md already specifies coding standards, your plugin skills shouldn't re-specify them. Instead, reference them: + +```markdown +Follow the project's coding standards (see CLAUDE.md) while applying +the additional [domain-specific] patterns below... +``` + +### Use Rules for File-Type Guidance + +If your plugin needs file-type-specific behavior, consider whether it belongs as: + +- **A rule** (`.claude/rules/`): For guidance that should always apply to certain file types +- **A skill**: For knowledge that's invoked on demand +- **A hook**: For enforcement that must happen every time + +### Understand Override Behavior + +Users can override plugin behavior through: + +- CLAUDE.md instructions (higher priority context) +- Settings that restrict tools (`permissions.deny`) +- Disabling plugin hooks via settings + +Design plugins to be graceful when overridden. Document what settings affect plugin behavior. + +### Plugin Settings (.local.md) vs Rules + +Plugin settings (`.claude/plugin-name.local.md`) and rules (`.claude/rules/`) serve different purposes: + +| Aspect | Plugin .local.md | .claude/rules/ | +| ---------- | ----------------------------- | ------------------------------------- | +| Purpose | Plugin-specific configuration | Project-wide guidance | +| Format | YAML frontmatter + markdown | Optional paths frontmatter + markdown | +| Scope | Single plugin | All Claude interactions | +| Managed by | User configuring plugin | Project maintainers | +| In git | No (gitignored) | Yes (shared with team) | + +### Test with Various Configurations + +Test your plugin with: + +1. Empty CLAUDE.md (no project context) +2. Detailed CLAUDE.md (potential conflicts) +3. Path-specific rules (ensure hooks don't conflict) +4. User-level rules (personal preferences) +5. Managed settings (enterprise restrictions) diff --git a/plugins/plugin-dev/skills/plugin-structure/SKILL.md b/plugins/plugin-dev/skills/plugin-structure/SKILL.md index 51d6b5d..53768fc 100644 --- a/plugins/plugin-dev/skills/plugin-structure/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-structure/SKILL.md @@ -1,7 +1,7 @@ --- name: plugin-structure version: 0.2.0 -description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "add lspServers", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices. +description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "add lspServers", "configure auto-discovery", "headless mode", "CI mode", "plugin in CI", "github actions", "plugin caching", "plugin CLI", "install plugin", "installation scope", "auto-update", "validate plugin", "plugin validate", "debug plugin", "output styles", "outputStyles", "custom output format", "response formatting", "--verbose", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices. --- # Plugin Structure for Claude Code @@ -114,6 +114,8 @@ Specify custom paths for components (supplements default directories): > **Note:** The `commands/` directory is a legacy format. For new plugins, prefer `skills//SKILL.md` which supports progressive disclosure via `references/` and `examples/` subdirectories. Both formats are loaded identically by Claude Code. +Simple, user-invocable prompts stored as single `.md` files. Use when you don't need bundled resources. Both commands and skills are invoked via the Skill tool — commands are essentially simple skills. + **Location**: `commands/` directory **Format**: Markdown files with YAML frontmatter **Auto-discovery**: All `.md` files in `commands/` load automatically @@ -313,27 +315,27 @@ For detailed LSP configuration, see the `lsp-integration` skill. ### Output Styles -**Location**: Inline in `plugin.json` under `outputStyles` field -**Format**: JSON configuration for custom output formatting +**Location**: `plugin.json` under `outputStyles` field, pointing to style files +**Format**: Path or array of paths to markdown style files **Purpose**: Customize how Claude formats responses -**Example format**: +**Example format (directory)**: ```json { - "outputStyles": { - "code-blocks": { - "style": "fenced", - "language": "auto" - }, - "headers": { - "numbering": true - } - } + "outputStyles": "./styles/" } ``` -**Usage**: Plugins can define consistent output formatting for their domain +**Example format (array of paths)**: + +```json +{ + "outputStyles": ["./styles/concise.md", "./styles/detailed.md"] +} +``` + +**Usage**: Plugins can define consistent output formatting for their domain. See `references/output-styles.md` for detailed style file format. ## Portable Path References @@ -619,6 +621,31 @@ claude --plugin-dir /path/to/plugin - Document potential conflicts in plugin README - Consider command prefixes for related functionality +## Runtime Contexts + +Plugins behave differently in non-interactive environments: + +- **Headless/CI mode** (`claude -p`): See `references/headless-ci-mode.md` +- **GitHub Actions**: See `references/github-actions.md` +- **Advanced topics** (caching, auto-update, keybindings): See `references/advanced-topics.md` + +## Plugin Validation + +```bash +claude plugin validate # CLI validation +claude --debug # Detailed logging +claude --verbose # Additional debugging +``` + +Use `/plugins` in the TUI to view installed plugins and their status. + +### Additional Source Types + +```bash +claude plugin install npm-package-name +claude plugin install pip-package-name +``` + --- ## Additional Resources @@ -627,6 +654,10 @@ claude --plugin-dir /path/to/plugin - **`references/component-patterns.md`** - Detailed patterns for each component type - **`references/manifest-reference.md`** - Complete plugin.json field reference +- **`references/headless-ci-mode.md`** - Headless and CI mode behavior +- **`references/github-actions.md`** - GitHub Actions integration +- **`references/advanced-topics.md`** - Caching, auto-update, keybindings +- **`references/output-styles.md`** - Output style file format and examples ### Example Files diff --git a/plugins/plugin-dev/skills/plugin-structure/references/advanced-topics.md b/plugins/plugin-dev/skills/plugin-structure/references/advanced-topics.md new file mode 100644 index 0000000..fc2ab5d --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-structure/references/advanced-topics.md @@ -0,0 +1,289 @@ +# Advanced Plugin Topics + +This reference covers specialized topics that plugin developers may encounter in advanced use cases. Each section is self-contained. + +## Keybindings Plugin Context + +Claude Code's keybindings system (`~/.claude/keybindings.json`) includes a `plugin:` context with actions for plugin management: + +| Action | Description | +| ---------------- | ----------------------- | +| `plugin:toggle` | Enable/disable a plugin | +| `plugin:install` | Install a plugin | + +**Configuration:** + +```json +{ + "bindings": [ + { + "context": "Plugin", + "bindings": { + "ctrl+p": "plugin:toggle" + } + } + ] +} +``` + +**Plugin developer relevance:** Low. This is user-facing configuration. Plugins cannot define custom keybindings. If your plugin has frequently used commands, document keyboard shortcuts users can configure. + +## Status Line Integration + +Plugins can provide status line scripts that display contextual information in the Claude Code footer. + +### How It Works + +Users configure a status line command in `.claude/settings.json`: + +```json +{ + "statusLine": { + "type": "command", + "command": "~/.claude/statusline.sh", + "padding": 0 + } +} +``` + +The script receives JSON via stdin with session context (model, cost, tokens, workspace info) and outputs a single line of text (ANSI colors supported). + +### Available Data + +The JSON input includes: + +- `model.display_name` — Current model name +- `cost.total_cost_usd` — Session cost +- `cost.total_lines_added` / `total_lines_removed` — Code changes +- `context_window.used_percentage` — Context usage +- `context_window.total_input_tokens` / `total_output_tokens` — Token counts +- `workspace.current_dir` / `project_dir` — Directory info +- `version` — Claude Code version + +### Plugin Use Case + +A plugin could bundle a status line script that displays plugin-specific information: + +```bash +#!/bin/bash +input=$(cat) +model=$(echo "$input" | jq -r '.model.display_name') +cost=$(echo "$input" | jq -r '.cost.total_cost_usd') +echo "[$model] \$${cost}" +``` + +**Note:** Users must manually configure their status line to use the plugin's script. There is no auto-configuration mechanism. + +## Claude Code as MCP Server + +Claude Code can itself act as an MCP server, exposing its capabilities to other MCP clients: + +```bash +claude mcp serve +``` + +**Plugin developer relevance:** Edge case. This is useful when building toolchains where one Claude Code instance needs to communicate with another, or when integrating Claude Code into a larger MCP-based system. Plugin MCP servers are unaffected by this feature. + +## MCP `@` Resource Reference Syntax + +Users can reference MCP resources inline using the `@` syntax: + +``` +@server-name:protocol://resource/path +``` + +### Common Patterns + +| Syntax | Example | +| ------------- | ------------------------------------------- | +| File resource | `@filesystem:file:///path/to/file.txt` | +| Database | `@database:postgres://localhost/mydb/users` | +| GitHub | `@github:https://github.com/user/repo` | +| Custom | `@myserver:custom://resource/id` | + +### Discovery + +Type `@` in Claude Code to see available resources from connected MCP servers. + +### Plugin Design Note + +If your plugin's MCP server exposes resources, document the available resource URIs and protocols in your README. Users can then reference them with `@plugin-server:protocol://path`. + +## Hook Agent Type Details + +The `agent` hook type (covered briefly in the hook-development SKILL.md) spawns a full subagent for complex verification workflows. + +For comprehensive coverage including configuration, behavior, supported events, when to use agent hooks, and detailed examples, see the hook-development skill's `references/advanced.md` file. + +**Quick summary:** Agent hooks spawn a subagent with full tool access (Read, Bash, Grep, etc.) for multi-step verification. They're significantly slower (30-120 seconds) but more capable than command or prompt hooks. Only supported on `Stop` and `SubagentStop` events. + +## Auto-Update Behavior + +### Default Behavior + +- **Official marketplaces:** Auto-update enabled by default +- **Third-party/local marketplaces:** Auto-update disabled by default + +### Environment Variables + +| Variable | Effect | +| ------------------------------- | -------------------------------------- | +| `DISABLE_AUTOUPDATER=true` | Disable all auto-updates | +| `FORCE_AUTOUPDATE_PLUGINS=true` | Force auto-update for all marketplaces | + +### Plugin Versioning Implications + +- Use semantic versioning (`MAJOR.MINOR.PATCH`) +- Breaking changes should bump MAJOR version +- Users on auto-update receive MINOR/PATCH changes automatically +- Document breaking changes in CHANGELOG +- Consider pre-release versions (`2.0.0-beta.1`) for testing + +## Plugin Caching + +### How Caching Works + +When a plugin is installed, Claude Code copies plugin content to a cache directory. Plugins run from the cache, not from their source location. + +### Key Implications + +1. **No `../` paths:** Plugins cannot reference files outside their directory via `../` — the cache copy doesn't include parent directories +2. **`${CLAUDE_PLUGIN_ROOT}` resolves to cache:** The variable points to the cached copy, not the source +3. **Symlinks are followed:** Symlinks within the plugin directory are resolved during the copy, so the target content is included + +### Workarounds for External Files + +If your plugin needs content from outside its directory: + +- **Symlinks:** Create symlinks to external files within the plugin directory (followed during cache copy) +- **Restructure:** Move shared content into the plugin directory +- **Environment variables:** Reference external paths via environment variables, not file paths +- **MCP servers:** Use MCP tools to access external resources at runtime + +### Cache Management + +Users can clear the plugin cache: + +```bash +rm -rf ~/.claude/plugins/cache +``` + +This forces re-caching on next session start. + +## Plugin CLI Management Commands + +Users manage plugins through CLI commands (or the `/plugin` interactive interface): + +### Installation + +```bash +# Install from marketplace +claude plugin install plugin-name@marketplace-name + +# Installation scopes +claude plugin install plugin-name@marketplace --scope user # Personal (default) +claude plugin install plugin-name@marketplace --scope project # Team (in .claude/settings.json) +claude plugin install plugin-name@marketplace --scope local # Personal project (gitignored) +``` + +### Management + +```bash +# List installed plugins +claude plugin list + +# Enable/disable without uninstalling +claude plugin enable plugin-name@marketplace +claude plugin disable plugin-name@marketplace + +# Update to latest version +claude plugin update plugin-name@marketplace + +# Remove completely +claude plugin uninstall plugin-name@marketplace +``` + +### Marketplace Management + +```bash +# Add a marketplace +claude plugin marketplace add owner/repo # GitHub +claude plugin marketplace add https://gitlab.com/org/repo.git # Git URL +claude plugin marketplace add ./local-path # Local + +# List/update/remove +claude plugin marketplace list +claude plugin marketplace update marketplace-name +claude plugin marketplace remove marketplace-name +``` + +### Plugin Developer Note + +Document the exact install command in your README: + +```markdown +## Installation + +\`\`\`bash +claude plugin install my-plugin@my-marketplace +\`\`\` +``` + +## Installation Scopes + +Plugins can be installed at different scopes, affecting who has access: + +| Scope | Location | Shared | Gitignored | Use Case | +| --------- | ----------------------------- | --------- | ---------- | ------------------------ | +| `user` | `~/.claude/settings.json` | No | N/A | Personal tools (default) | +| `project` | `.claude/settings.json` | Yes (git) | No | Team standards | +| `local` | `.claude/settings.local.json` | No | Yes | Personal project tools | +| `managed` | System paths | Yes (MDM) | N/A | Enterprise enforcement | + +### Scope Precedence + +When the same plugin is configured at multiple scopes, local overrides project, which overrides user. + +### Team Plugin Distribution + +For team plugins, install at `project` scope and commit `.claude/settings.json`: + +```json +{ + "enabledPlugins": { + "my-plugin@my-marketplace": true + } +} +``` + +Team members get the plugin when they clone the repo. + +### Enterprise Plugin Control + +Organizations can use managed settings to: + +- **Allowlist marketplaces:** `strictKnownMarketplaces` restricts which marketplaces users can add +- **Force plugins:** Pre-configure required plugins via managed settings +- **Block plugins:** Prevent specific plugins from being installed + +### Enterprise Hook and Permission Control + +Managed settings can also restrict hook and permission rule sources: + +| Setting | Effect | +| --------------------------------- | --------------------------------------------------------------- | +| `allowManagedPermissionRulesOnly` | Only managed permission rules apply; user/project rules ignored | +| `allowManagedHooksOnly` | Only managed hooks execute; plugin/user hooks disabled | + +**Plugin developer implications:** + +- Test plugins with these settings enabled to verify graceful degradation +- Document which hooks are critical for plugin functionality +- Provide fallback behavior when hooks are disabled by enterprise policy + +### Plugin Developer Implications + +- Document recommended scope in README +- Test plugin at both user and project scopes +- For team plugins, provide `.claude/settings.json` snippets +- Note that managed settings can override plugin availability diff --git a/plugins/plugin-dev/skills/plugin-structure/references/github-actions.md b/plugins/plugin-dev/skills/plugin-structure/references/github-actions.md new file mode 100644 index 0000000..0c27a58 --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-structure/references/github-actions.md @@ -0,0 +1,233 @@ +# GitHub Actions Integration for Plugins + +Plugins interact with GitHub Actions through `claude-code-action`, Anthropic's official action for running Claude Code in CI workflows. Understanding this integration helps plugin developers ensure their plugins work seamlessly in automated pipelines. + +## Overview + +The `claude-code-action@v1` runs Claude Code inside GitHub Actions, enabling: + +- Automated code review on PRs +- Issue implementation from comments +- Custom automation triggered by @claude mentions +- Scheduled analysis and reporting + +## Setup + +### Quick Setup + +From inside Claude Code: + +```bash +/install-github-app +``` + +This guides through installing the Claude GitHub app and configuring workflows. + +### Manual Setup + +1. Install the Claude GitHub App: `https://github.com/apps/claude` +2. Add `ANTHROPIC_API_KEY` to repository secrets +3. Create workflow file at `.github/workflows/claude.yml` + +### Basic Workflow + +```yaml +name: Claude Code +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + +jobs: + claude: + runs-on: ubuntu-latest + steps: + - uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} +``` + +## How Plugins Work in Actions + +### CLAUDE.md Integration + +The most direct way plugins interact with CI is through CLAUDE.md. Project-level instructions (`.claude/CLAUDE.md`) load automatically in CI runs, providing: + +- Code style requirements +- Review criteria +- Project-specific rules +- Plugin references + +### Hooks in CI + +Plugin hooks execute in the CI environment: + +- **Command hooks:** Run normally (ensure scripts are executable and dependencies available) +- **Prompt hooks:** Work as expected +- **SessionStart hooks:** Fire at the beginning of each CI run +- **Environment:** `$CI=true` is set, use for conditional logic + +**CI-aware hook example:** + +```bash +#!/bin/bash +# Skip interactive checks in CI +if [ "$CI" = "true" ]; then + echo '{"continue": true}' + exit 0 +fi +# Full validation in local development +# ... +``` + +### Skills via prompt Parameter + +Reference plugin skills in the workflow's `prompt` parameter: + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + prompt: "Review this PR for security issues following our coding standards" + claude_args: "--max-turns 15" +``` + +Since slash commands don't work in headless mode, describe the task instead. If the skill has `user-invocable: false`, Claude will use it automatically based on context. + +## Configuration Options + +### Key Parameters + +| Parameter | Purpose | Example | +| ------------------- | ----------------------- | -------------------------------------- | +| `prompt` | Instructions for Claude | `"Review this PR"` | +| `claude_args` | CLI arguments | `"--max-turns 10 --model haiku"` | +| `anthropic_api_key` | API key secret | `${{ secrets.ANTHROPIC_API_KEY }}` | +| `github_token` | GitHub API access | `${{ secrets.GITHUB_TOKEN }}` | +| `trigger_phrase` | Custom trigger | `"@review-bot"` (default: `"@claude"`) | + +### claude_args for Plugin Control + +Pass CLI flags through `claude_args`: + +```yaml +claude_args: >- + --max-turns 20 + --model claude-sonnet-4-5-20250929 + --allowedTools "Read,Grep,Glob,Bash(npm:*)" +``` + +### Custom Trigger Phrases + +Change the default `@claude` trigger: + +```yaml +trigger_phrase: "@security-review" +``` + +Users then mention `@security-review` in PR comments to trigger the workflow. + +## Provider Configurations + +### AWS Bedrock + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + use_bedrock: "true" + claude_args: "--model us.anthropic.claude-sonnet-4-5-20250929-v1:0" + env: + AWS_ROLE_TO_ASSUME: ${{ secrets.AWS_ROLE_TO_ASSUME }} + AWS_REGION: us-east-1 +``` + +Requires AWS OIDC configuration with Bedrock permissions. + +### Google Vertex AI + +```yaml +- uses: anthropics/claude-code-action@v1 + with: + use_vertex: "true" + claude_args: "--model claude-sonnet-4@20250514" + env: + ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }} + CLOUD_ML_REGION: us-east5 +``` + +Requires GCP Workload Identity Federation. + +## Cost Management + +### Limit Turns + +```yaml +claude_args: "--max-turns 10" +``` + +Each tool call is one turn. Start low and increase as needed. + +### Use Cheaper Models + +```yaml +claude_args: "--model haiku" +``` + +Use Haiku for routine checks, Sonnet for standard reviews, Opus for complex analysis. + +### Set Workflow Timeouts + +```yaml +jobs: + claude: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: anthropics/claude-code-action@v1 + # ... +``` + +### Restrict Tool Access + +```yaml +claude_args: "--allowedTools 'Read,Grep,Glob'" +``` + +Read-only tools prevent expensive write/execute loops. + +## Plugin Design for CI + +### Document CI Workflows + +Include example workflow snippets in your plugin README: + +```markdown +## GitHub Actions Usage + +Add to `.github/workflows/claude.yml`: + +\`\`\`yaml + +- uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + prompt: "Analyze code using [your-plugin] standards" + claude_args: "--max-turns 15 --allowedTools 'Read,Grep,Glob'" + \`\`\` +``` + +### Ensure CI Compatibility + +- Test hooks with `CI=true` environment variable +- Ensure scripts don't require interactive input +- Handle missing dependencies gracefully (not all CI images have `jq`, etc.) +- Use `${CLAUDE_PLUGIN_ROOT}` for all paths (cache directories differ in CI) + +### MCP Servers in CI + +MCP servers bundled with plugins start in CI, but: + +- OAuth-based servers won't have tokens (configure environment variables instead) +- Local stdio servers need their dependencies installed in the CI image +- Document required CI setup in README diff --git a/plugins/plugin-dev/skills/plugin-structure/references/headless-ci-mode.md b/plugins/plugin-dev/skills/plugin-structure/references/headless-ci-mode.md new file mode 100644 index 0000000..3f2a382 --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-structure/references/headless-ci-mode.md @@ -0,0 +1,193 @@ +# Headless & CI Mode Plugin Compatibility + +Plugins behave differently in headless mode (`claude -p`) versus interactive sessions. Understanding these differences is critical for building plugins that work reliably across all runtime contexts. + +## Headless Mode Basics + +Headless mode executes Claude Code as a single-shot command-line tool: + +```bash +claude -p "Analyze this codebase for security issues" --allowedTools "Read,Grep,Glob" +``` + +### What Works in Headless Mode + +- **Hooks:** Command hooks execute normally. Prompt hooks work for supported events. +- **MCP servers:** Start and connect as usual. Tools are available. +- **CLAUDE.md:** Project and user memory files load normally. +- **Agents:** Can be spawned via Task tool during execution. +- **Skills (as context):** Skill content with `user-invocable: false` loads into context and is available for Claude to use. + +### What Does NOT Work in Headless Mode + +- **Slash commands:** `/skill-name` invocation requires an interactive session. Skills cannot be invoked via slash commands in `-p` mode. +- **Interactive prompts:** `AskUserQuestion` tool is not available — there's no user to answer. +- **Skill tool (manual):** Users can't type `/` to invoke skills. Instead, describe the task and let Claude use the skill content if loaded. + +### Workaround for Skills + +Instead of invoking `/review` in headless mode, describe the task: + +```bash +# Won't work: +claude -p "/review" + +# Works — describe what you want: +claude -p "Review the codebase for code quality issues" +``` + +If the skill has `user-invocable: false` and is loaded via plugin, Claude can still use its knowledge automatically. + +## Permission Control + +### --allowedTools + +Auto-approve specific tools without interactive prompts: + +```bash +claude -p "Fix the bug" --allowedTools "Read,Write,Edit,Bash(git *)" +``` + +**Permission rule syntax:** + +| Pattern | Matches | +| ---------------------- | ------------------------------------------------------------ | +| `Read` | All Read tool calls | +| `Bash(git *)` | Bash commands starting with "git " (prefix match with space) | +| `mcp__*` | All MCP tool calls | +| `mcp__plugin_myplug_*` | Tools from a specific plugin's MCP server | +| `Write,Edit` | Multiple tools (comma-separated) | + +**Plugin design tip:** Document recommended `--allowedTools` values in your plugin README for CI usage. + +### --max-turns + +Limit autonomous tool-use iterations to control cost and runtime: + +```bash +claude -p "Run tests and fix failures" --allowedTools "Read,Edit,Bash" --max-turns 10 +``` + +Each tool call counts as one turn. Without this limit, Claude may iterate indefinitely on complex tasks. + +## Structured Output + +### JSON Output + +Get machine-readable responses: + +```bash +claude -p "List all TODO comments" --output-format json +``` + +Returns: + +```json +{ + "result": "Found 5 TODO comments...", + "session_id": "abc123", + "metadata": { ... } +} +``` + +### JSON Schema Validation + +Enforce a specific output structure: + +```bash +claude -p "Extract function signatures from auth.py" \ + --output-format json \ + --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' +``` + +**Plugin design tip:** If your plugin provides analysis workflows, document example JSON schemas users can use for structured CI output. + +## System Prompt Interaction + +### --append-system-prompt + +Add instructions alongside the default system prompt (and any loaded plugin content): + +```bash +claude -p "Review code" --append-system-prompt "Focus on security vulnerabilities only" +``` + +Plugin skill content loads before system prompt overrides. The append adds to (not replaces) existing context. + +### --system-prompt + +Replace the default system prompt entirely: + +```bash +claude -p "Analyze" --system-prompt "You are a security auditor..." +``` + +**Caution:** This replaces the default prompt but plugin content still loads. The interaction between `--system-prompt` and plugin skills may produce unexpected behavior. + +## Session Management + +### Continue Last Session + +```bash +claude -p "What was the last change you made?" --continue +``` + +### Resume Specific Session + +```bash +claude -p "Continue fixing the auth bug" --resume "$SESSION_ID" +``` + +Plugin state (hooks, MCP servers, skill context) reloads when resuming a session. + +## Plugin Design Guidelines for CI Compatibility + +### 1. Test in Headless Mode + +```bash +# Test your plugin works in non-interactive mode +claude -p "Run the plugin's primary workflow" \ + --plugin-dir /path/to/plugin \ + --allowedTools "Read,Write,Edit,Bash" +``` + +### 2. Avoid Interactive-Only Patterns + +- Don't rely on `AskUserQuestion` for critical workflows +- Provide sensible defaults when user input is unavailable +- Design hooks that work without user confirmation + +### 3. Document CI Usage + +Include a CI section in your plugin README: + +```markdown +## CI/Headless Usage + +This plugin works in headless mode. Example: + +\`\`\`bash +claude -p "Run security audit" \ + --allowedTools "Read,Grep,Glob,Bash(npm:\*)" \ + --max-turns 20 \ + --output-format json +\`\`\` +``` + +### 4. Handle Missing Environment Gracefully + +In CI environments, some tools or context may be unavailable: + +- MCP servers may not have authentication tokens +- Git history may be shallow clones +- Environment variables may differ from local dev + +Design hooks and skills to handle these cases without failing hard. + +### 5. Cost-Conscious Design + +CI runs can accumulate significant API costs. Help users control spending: + +- Recommend `--max-turns` values for common workflows +- Use `haiku` model for simple analysis skills +- Document expected token usage for key workflows diff --git a/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md b/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md index 36e6aea..a8ad4d0 100644 --- a/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md +++ b/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md @@ -355,6 +355,40 @@ MCP server configuration location or inline definition. - Complex plugins: External `.mcp.json` file - Multiple servers: Always use external file +#### outputStyles + +**Type**: String or Array of strings +**Default**: `["./output-styles"]` +**Example**: `"./styles"` + +Path(s) to output style definition files or directories. + +**Single path**: + +```json +{ + "outputStyles": "./styles" +} +``` + +**Multiple paths**: + +```json +{ + "outputStyles": ["./styles/default.md", "./styles/compact.md"] +} +``` + +**Behavior**: Supplements default `output-styles/` directory (does not replace) + +Output style files are markdown with YAML frontmatter (`name`, `description`, `keep-coding-instructions`). See the plugin-structure skill's `references/output-styles.md` for the complete frontmatter schema. + +**Use cases**: + +- Providing domain-specific formatting (e.g., concise code review output) +- Bundling multiple style options for users to choose from +- Offering specialized output modes for different workflows + ## Path Resolution ### Relative Path Rules diff --git a/plugins/plugin-dev/skills/plugin-structure/references/output-styles.md b/plugins/plugin-dev/skills/plugin-structure/references/output-styles.md new file mode 100644 index 0000000..73a36f9 --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-structure/references/output-styles.md @@ -0,0 +1,116 @@ +# Output Styles Reference + +Output styles customize how Claude formats and structures responses. They modify Claude's system prompt directly, providing persistent formatting instructions that apply throughout a conversation. + +## How Output Styles Work + +When an output style is active, its markdown content is injected into Claude's system prompt. This means output styles: + +- Apply to all responses while active (not just specific tool calls) +- Can override default formatting behavior +- Are selected by the user (not automatically triggered like skills) +- Can coexist with CLAUDE.md instructions (style takes precedence for formatting) + +## Frontmatter Schema + +Output style files use YAML frontmatter: + +```yaml +--- +name: concise-reviewer +description: Terse code review output with minimal prose +keep-coding-instructions: true +--- +``` + +| Field | Type | Required | Description | +| -------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | String | Yes | Display name shown in style selection | +| `description` | String | Yes | Brief explanation of what the style does | +| `keep-coding-instructions` | Boolean | No | When `true`, preserves Claude's default coding instructions alongside the style. When `false` (default), the style replaces default coding instructions entirely. | + +**`keep-coding-instructions` guidance:** + +- Set to `true` for styles that only modify output format (e.g., "use bullet points", "be more concise") +- Set to `false` (or omit) for styles that fundamentally change Claude's role (e.g., "act as a technical writer", "respond only with code") + +## File Locations + +Output styles can be defined at multiple levels: + +| Level | Location | Scope | +| ------- | ---------------------------------------------- | -------------- | +| User | `~/.claude/output-styles/*.md` | All projects | +| Project | `.claude/output-styles/*.md` | Single project | +| Plugin | Referenced via `outputStyles` in `plugin.json` | Plugin users | + +### Plugin Bundling + +Plugins bundle output styles using the `outputStyles` field in `plugin.json`: + +```json +{ + "outputStyles": "./styles/" +} +``` + +Or with explicit paths: + +```json +{ + "outputStyles": ["./styles/concise.md", "./styles/detailed.md"] +} +``` + +Style files in the referenced path are discovered and registered when the plugin loads. Users can then select them from the output style picker. + +## Built-in Styles + +Claude Code includes built-in output styles that users can select. Plugin-provided styles appear alongside built-in styles in the style selection interface. + +## When to Use Output Styles vs Other Components + +| Component | Best For | Persistence | +| ----------------- | --------------------------------------- | ------------------------------ | +| **Output styles** | Response formatting, tone, structure | Active until user switches | +| **Skills** | Domain knowledge, workflows, procedures | Active during skill invocation | +| **Agents** | Autonomous multi-step tasks | Active during agent run | +| **CLAUDE.md** | Project context, coding standards | Always loaded | + +**Use output styles when:** + +- You want to change how Claude formats all responses (not just during a specific task) +- The formatting applies regardless of what task Claude is performing +- Users should be able to toggle the behavior on/off + +**Don't use output styles when:** + +- The behavior only applies during specific operations (use a skill instead) +- You need tool restrictions or scoped hooks (use an agent) +- The instructions are project-specific standards (use CLAUDE.md) + +## Example: Complete Output Style + +```markdown +--- +name: concise-code-review +description: Minimal code review output focused on actionable findings +keep-coding-instructions: true +--- + +When reviewing code: + +- List only actionable findings +- Use severity labels: [critical], [warning], [nit] +- No praise or filler text +- One line per finding with file:line reference +- Group by severity, highest first +``` + +## Plugin Developer Tips + +- Keep styles focused on a single formatting concern +- Use descriptive names that clearly indicate the style's effect +- Set `keep-coding-instructions: true` unless your style intentionally replaces coding behavior +- Test styles with various task types to ensure they don't interfere with tool use +- Document available styles in your plugin README diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index 1f9903d..3155b72 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -1,7 +1,7 @@ --- name: skill-development version: 0.2.0 -description: This skill should be used when the user asks to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", "SKILL.md format", "skill frontmatter", "skill triggers", "trigger phrases for skills", "progressive disclosure", "skill references folder", "skill examples folder", "validate skill", or needs guidance on skill structure, file organization, writing style, or skill development best practices for Claude Code plugins. +description: This skill should be used when the user asks to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", "SKILL.md format", "skill frontmatter", "skill triggers", "trigger phrases for skills", "progressive disclosure", "skill references folder", "skill examples folder", "validate skill", "skill model field", "skill hooks", "scoped hooks in skill", "visibility budget", "context budget", "SLASH_COMMAND_TOOL_CHAR_BUDGET", "skill permissions", "Skill() syntax", "visual output", "skill precedence", "argument-hint", or needs guidance on skill structure, file organization, writing style, or skill development best practices for Claude Code plugins. --- # Skill Development for Claude Code Plugins @@ -21,6 +21,7 @@ equipped with procedural knowledge that no model can fully possess. 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks +5. Visual output generation — Scripts that produce HTML/interactive visualizations ### Anatomy of a Skill @@ -39,6 +40,12 @@ skill-name/ └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` +Both skills and commands are invoked via the Skill tool and share the same underlying mechanism. Commands are essentially simple skills stored as single `.md` files without bundled resources. See `references/commands-vs-skills.md` for a comparison. + +### Skill Precedence + +Skills follow precedence: Enterprise > Personal (`~/.claude/skills/`) > Project (`.claude/skills/`) > Plugin skills. Higher-priority skills with the same name shadow lower-priority ones. Use distinctive, namespaced names for plugin skills to avoid collisions. + #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). @@ -176,6 +183,35 @@ Use for skills that should only be manually invoked by users, such as: | `user-invocable: false` | Hidden | Allowed | Yes | | `disable-model-invocation: true` | Visible | Blocked | Yes | +##### model (optional) + +```yaml +model: haiku +``` + +Values: `sonnet`, `opus`, `haiku`, `inherit` (default), or full model ID. See `references/advanced-frontmatter.md` for details. + +##### hooks (optional) + +```yaml +hooks: + PreToolUse: + - matcher: Write + hooks: + - type: command + command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh" +``` + +Scoped hooks that activate when this skill is loaded and deactivate when it finishes. Supported events: `PreToolUse`, `PostToolUse`, `Stop`. See `references/advanced-frontmatter.md`. + +##### argument-hint (optional) + +```yaml +argument-hint: " [--verbose]" +``` + +Provides autocomplete hint text in the `/` menu. Cosmetic only; doesn't affect argument parsing. + #### Bundled Resources (optional) ##### Scripts (`scripts/`) @@ -218,6 +254,8 @@ Arguments passed: $ARGUMENTS **Available substitutions:** - `$ARGUMENTS` - Arguments passed when skill is invoked (e.g., `/skill-name arg1 arg2`) +- `$ARGUMENTS[0]`, `$ARGUMENTS[1]` - Individual positional arguments (0-indexed) +- `$1`, `$2`, `$3` - 1-indexed shorthand for positional arguments - `${CLAUDE_SESSION_ID}` - Current session identifier - `${CLAUDE_PLUGIN_ROOT}` - Plugin directory path @@ -272,6 +310,18 @@ To create a skill, follow these six steps. For detailed instructions on each ste - **Body**: Use imperative/infinitive form ("To create X, do Y"), not second person ("You should...") - **Size**: Target 1,500-2,000 words; move detailed content to references/ +### Visibility Budget + +Skill descriptions consume ~2% of context window (~16KB fallback). If total skill descriptions exceed this budget, some skills may be excluded from discovery. Controlled by `SLASH_COMMAND_TOOL_CHAR_BUDGET`. + +Keep descriptions concise but include trigger phrases. Skills with longer descriptions are more likely to be excluded when budget pressure is high. See `references/advanced-frontmatter.md` for optimization strategies. + +### Context Management for Plugins + +After auto-compaction, skill descriptions survive (they're re-injected), but skill body content may be lost. Users can re-invoke the skill to reload it. The `PreCompact` hook can preserve critical state before compaction occurs. + +When multiple plugins are installed, their skill descriptions share the same budget. Design descriptions to be distinctive and concise. + ## Plugin-Specific Considerations ### Skill Location in Plugins @@ -361,6 +411,9 @@ Before finalizing a skill: - [ ] (Optional) `skills` array if loading other skills (requires `context: fork`) - [ ] (Optional) `user-invocable` field if hiding from slash menu - [ ] (Optional) `disable-model-invocation` field if blocking programmatic use +- [ ] (Optional) `model` field if overriding default model +- [ ] (Optional) `hooks` field if using scoped hooks +- [ ] (Optional) `argument-hint` field for autocomplete hints - [ ] Markdown body is present and substantial - [ ] Referenced files actually exist @@ -461,6 +514,8 @@ For detailed guidance, consult: - **`references/skill-creation-workflow.md`** - Plugin-specific skill creation workflow (recommended for plugin skills) - **`references/skill-creator-original.md`** - Original generic skill-creator methodology (includes init/packaging scripts for standalone skills) +- **`references/advanced-frontmatter.md`** - Model, hooks, argument-hint, and visibility budget details +- **`references/commands-vs-skills.md`** - Comparison of commands and skills formats ### Study These Skills diff --git a/plugins/plugin-dev/skills/skill-development/references/advanced-frontmatter.md b/plugins/plugin-dev/skills/skill-development/references/advanced-frontmatter.md new file mode 100644 index 0000000..db1930e --- /dev/null +++ b/plugins/plugin-dev/skills/skill-development/references/advanced-frontmatter.md @@ -0,0 +1,225 @@ +# Advanced Skill Frontmatter Fields + +This reference covers frontmatter fields that go beyond the core `name` and `description` requirements. These fields enable model selection, scoped hooks, and context budget optimization. + +## model + +Override the model used when a skill is active. + +### Values + +| Value | Behavior | +| ------------- | ----------------------------------------------------- | +| `inherit` | Use the conversation's current model (default) | +| `sonnet` | Claude Sonnet — balanced performance and cost | +| `opus` | Claude Opus — maximum capability, highest cost | +| `haiku` | Claude Haiku — fastest, lowest cost | +| Full model ID | Specific version (e.g., `claude-sonnet-4-5-20250929`) | + +### When to Use Each + +- **`inherit` (default):** Most skills. Lets the user's model choice apply. +- **`haiku`:** Fast, cost-sensitive operations — linting, formatting checks, simple lookups. Good for skills that run frequently. +- **`sonnet`:** Standard workflows — code review, generation, analysis. The balanced default. +- **`opus`:** Complex reasoning — architectural decisions, security audits, detailed analysis requiring maximum capability. +- **Full model ID:** Pin to a specific version when skill behavior depends on exact model capabilities. + +### Example + +```yaml +--- +name: quick-lint +description: This skill should be used for fast code quality checks... +model: haiku +--- +``` + +### Notes + +- Shorthand names (`sonnet`, `opus`, `haiku`) resolve to the current default version of each family +- The `model` field is shared with commands (same syntax and behavior) +- When `context: fork` is set, the model applies to the forked subagent + +## hooks (Scoped Hooks) + +Define hooks that activate only when the skill is in use, rather than globally for all tool calls. + +### Concept + +Unlike `hooks.json` (which applies globally whenever the plugin is active), scoped hooks in frontmatter are lifecycle-bound to the skill. They activate when the skill loads and deactivate when it completes. This enables skill-specific validation without affecting other workflows. + +### Format + +The `hooks` field uses the same event/matcher/hook structure as `hooks.json`: + +```yaml +--- +name: validated-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 + +Scoped hooks support a subset of hook events: + +| Event | Purpose | +| ------------- | ------------------------------------------------ | +| `PreToolUse` | Validate or block tool calls before execution | +| `PostToolUse` | Run checks after successful tool execution | +| `Stop` | Verify completion criteria before skill finishes | + +Other events (`SessionStart`, `UserPromptSubmit`, etc.) are session-level and don't apply to skill scope. + +### Comparison with hooks.json + +| Aspect | `hooks.json` | Frontmatter `hooks` | +| -------- | ------------------------------------------ | --------------------------------------------- | +| Scope | Global (always active when plugin enabled) | Skill-specific (active only during skill use) | +| Events | All 11+ hook events | PreToolUse, PostToolUse, Stop | +| Location | `hooks/hooks.json` file | YAML frontmatter in SKILL.md | +| Use case | Plugin-wide validation, logging | Skill-specific safety checks | + +### 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 + +### Hook Types in Frontmatter + +Both `command` and `prompt` hook types work in frontmatter: + +**Command hook** (executes a script): + +```yaml +hooks: + PreToolUse: + - matcher: Bash + hooks: + - type: command + command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-safety.sh" +``` + +**Prompt hook** (LLM evaluation — for Stop events): + +```yaml +hooks: + Stop: + - hooks: + - type: prompt + prompt: 'Verify that all generated code has tests. Return {"decision": "stop"} if satisfied or {"decision": "continue", "reason": "missing tests for..."} if not.' +``` + +## Skill Visibility Budget + +Claude Code allocates a character budget for skill descriptions to manage context window usage efficiently. + +### How It Works + +1. All installed skills contribute their `description` text to a shared budget +2. Default budget: approximately 2% of the context window or ~16KB fallback (controlled by `SLASH_COMMAND_TOOL_CHAR_BUDGET`) +3. When total descriptions exceed the budget, lower-priority skills may be excluded from auto-discovery +4. Excluded skills are still available via explicit `/skill-name` invocation — they just won't auto-trigger + +### What Counts Against the Budget + +- The `description` frontmatter field text +- Skill name and metadata overhead +- This applies across ALL installed plugins, not just yours + +### Optimization Strategies + +1. **Keep descriptions concise:** Target 100-300 characters for the description field +2. **Use trigger phrases, not explanations:** "create a hook", "add PreToolUse" is better than "This skill provides comprehensive guidance for creating event-driven automation..." +3. **Move detail to SKILL.md body:** The body only loads when the skill triggers, not at discovery time +4. **Progressive disclosure:** Description (always loaded) → SKILL.md body (on trigger) → references (on demand) + +### Checking Budget Usage + +- `/context` command shows context usage including excluded skills if over budget +- Environment variable: `SLASH_COMMAND_TOOL_CHAR_BUDGET=20000` to increase budget +- Monitor with: `claude --debug` shows skill loading details + +### Practical Impact + +For most plugins with 5-15 skills, the default budget is sufficient. Budget becomes a concern when: + +- Multiple plugins are installed simultaneously (each adding descriptions) +- Individual skill descriptions exceed 500 characters +- A plugin has 20+ skills with verbose descriptions + +## Skill Permission Syntax + +Skills can be referenced in settings.json allow rules using the `Skill()` syntax: + +### Exact Match + +Allow a specific skill to be invoked: + +```json +{ + "permissions": { + "allow": ["Skill(my-skill-name)"] + } +} +``` + +### Prefix Match with Arguments + +Allow a skill with any arguments: + +```json +{ + "permissions": { + "allow": ["Skill(my-skill-name *)"] + } +} +``` + +This enables fine-grained control over which skills can be auto-invoked by Claude vs requiring explicit user invocation. Combine with `disable-model-invocation` frontmatter for maximum control. + +## Visual Output Generators + +Skills can bundle scripts that generate visual output (HTML files, charts, interactive visualizations) for rich user experiences. + +### Pattern + +1. Bundle a script (Python, Node.js, etc.) in the skill's `scripts/` directory +2. The script generates an HTML file or other visual output +3. Claude orchestrates: reads data, runs the script, presents the result + +### Example Structure + +``` +visualization-skill/ +├── SKILL.md +├── scripts/ +│ └── generate-chart.py # Produces HTML output +└── references/ + └── chart-options.md # Configuration reference +``` + +### SKILL.md Usage + +```markdown +To generate the visualization: + +1. Gather the data from the user's project +2. Run the script: `python ${CLAUDE_PLUGIN_ROOT}/skills/visualization-skill/scripts/generate-chart.py` +3. The script outputs an HTML file — inform the user of its location +``` + +Visual output generators combine the power of deterministic scripts with Claude's ability to gather context and present results. The script handles rendering while Claude handles data gathering and user interaction. diff --git a/plugins/plugin-dev/skills/skill-development/references/commands-vs-skills.md b/plugins/plugin-dev/skills/skill-development/references/commands-vs-skills.md new file mode 100644 index 0000000..ae9c74a --- /dev/null +++ b/plugins/plugin-dev/skills/skill-development/references/commands-vs-skills.md @@ -0,0 +1,39 @@ +# Commands vs Skills: When to Use Each + +## Same Mechanism, Different Complexity + +Both commands and skills: + +- Are invoked via the Skill tool +- Support $ARGUMENTS and `[BANG]` bash execution +- Support frontmatter (description, allowed-tools, model) +- Can control invocability (disable-model-invocation) + +## Decision Matrix + +| Need | Use | Location | +| ----------------------- | ------- | ---------------------- | +| Simple reusable prompt | Command | commands/foo.md | +| Dynamic arguments only | Command | commands/foo.md | +| Scripts for validation | Skill | skills/foo/ | +| Reference documentation | Skill | skills/foo/references/ | +| Working examples | Skill | skills/foo/examples/ | +| Progressive disclosure | Skill | skills/foo/ | + +## Invocation Control + +| Setting | User (/) | Claude (Skill tool) | +| ----------------------------------- | -------- | ------------------- | +| Default | Yes | Yes | +| disable-model-invocation: true | Yes | No | +| user-invocable: false (skills only) | No | Yes | + +## Migration: Command to Skill + +When a command grows complex: + +1. Create `skills/name/SKILL.md` +2. Move command content to SKILL.md body (frontmatter fields like `description`, `allowed-tools`, `model` work identically) +3. Add `references/` for detailed docs +4. Add `scripts/` for utilities +5. Delete original command file From 0c3fd4295b3e585ad50fb1dd267d5dc2f3233b8b Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Fri, 27 Mar 2026 00:49:47 +1300 Subject: [PATCH 10/33] feat: update skills for Claude Code v2.1.83-84 features and release v0.5.0 Add initialPrompt agent frontmatter, CwdChanged/FileChanged hook events, userConfig plugin manifest field, paths: YAML list for skills, MCP 2KB description cap, and WorktreeCreate HTTP hook support. --- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 16 +++ CLAUDE.md | 2 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../skills/agent-development/SKILL.md | 24 +++- .../skills/hook-development/SKILL.md | 107 ++++++++++++++++-- .../skills/mcp-integration/SKILL.md | 4 + .../skills/plugin-structure/SKILL.md | 34 +++++- .../skills/skill-development/SKILL.md | 16 ++- 9 files changed, 190 insertions(+), 19 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 08df420..50c866e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.4.1" + "version": "0.5.0" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.4.1", + "version": "0.5.0", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ea1217..9380191 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.0] - 2026-03-27 + +### Added + +- **agent-development**: `initialPrompt` frontmatter field for auto-submitting a first turn when agent runs as main session agent +- **hook-development**: `CwdChanged` event for reactive environment management on directory changes (supports `CLAUDE_ENV_FILE` and `watchPaths`) +- **hook-development**: `FileChanged` event for watching file changes with basename matcher support +- **plugin-structure**: `userConfig` manifest field for plugin-configurable values prompted at enable time, with keychain storage for sensitive values +- **skill-development**: `paths` frontmatter field accepting YAML list of globs for file-scoped skill activation +- **mcp-integration**: MCP description limits section documenting the 2KB cap on tool descriptions and server instructions + +### Changed + +- **hook-development**: Updated event count from 22 to 24 across skill, quick reference table, and hook type support matrix +- **hook-development**: `WorktreeCreate` now documents HTTP hook support with `hookSpecificOutput.worktreePath` response format + ## [0.4.1] - 2026-03-24 ### Documentation diff --git a/CLAUDE.md b/CLAUDE.md index 62f7b15..e26376b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 3 agents, 3 slash commands. -**Version**: v0.4.1 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.5.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index a5e834c..41a43ac 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.4.1", + "version": "0.5.0", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index fa7626a..a44ab97 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/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", "disallowedTools", "block tools", "agent denylist", "maxTurns", "agent memory", "mcpServers in agent", "agent hooks", "background agent", "resume agent", "agent teams", "permission rules", "permission mode", "delegate mode", "agent team", "team lead", "teammate", "multi-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", "maxTurns", "agent memory", "mcpServers in agent", "agent hooks", "background agent", "resume agent", "initialPrompt", "auto-submit prompt", "agent teams", "permission rules", "permission mode", "delegate mode", "agent team", "team lead", "teammate", "multi-agent", 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 @@ -368,6 +368,27 @@ hooks: Supports all hook events. Note: `Stop` hooks in agent frontmatter are auto-converted to `SubagentStop` at runtime. Hooks activate when the agent starts and deactivate when it finishes. See `references/advanced-agent-fields.md` for full details. +### initialPrompt (optional) + +Auto-submit a prompt as the first user turn when the agent runs as the main session agent: + +```yaml +initialPrompt: "Scan the codebase for lint errors, test failures, and report a summary." +``` + +**Behavior:** + +- Only fires when the agent is the **main session agent** (launched via `--agent` flag or `agent` setting) +- Does **not** fire when the agent is spawned as a subagent by another agent +- The prompt is submitted automatically — no manual input required +- If the user also provides a prompt, both are submitted + +**Use cases:** + +- Agents that should immediately start working without user input +- Daily standup or health-check agents +- Automated validation that runs on session start + ### Fields NOT Available for Agents Some frontmatter fields are specific to skills and do not apply to agents: @@ -565,6 +586,7 @@ Ensure system prompt is complete: | memory | No | Scope string | user | | mcpServers | No | Server name map | slack: | | hooks | No | Hook event map | PreToolUse: [...] | +| initialPrompt | No | String | "Run health check..." | > **Note:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. The field names differ between component types. diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index 41050c4..df625c1 100644 --- 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", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, Notification, ConfigChange, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove, InstructionsLoaded, Elicitation, ElicitationResult). 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", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, Notification, ConfigChange, TeammateIdle, TaskCompleted, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, InstructionsLoaded, Elicitation, ElicitationResult). 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 @@ -9,7 +9,7 @@ description: This skill should be used when the user asks to "create a hook", "a Hooks are event-driven automation that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows. -Claude Code has **22 hook events** across these categories: +Claude Code has **24 hook events** across these categories: - **Session Lifecycle** -- SessionStart, InstructionsLoaded, SessionEnd - **User Input** -- UserPromptSubmit @@ -19,6 +19,7 @@ Claude Code has **22 hook events** across these categories: - **Teams** -- TeammateIdle, TaskCompleted - **Context Management** -- PreCompact, PostCompact - **Configuration** -- ConfigChange +- **Environment** -- CwdChanged, FileChanged - **Worktrees** -- WorktreeCreate, WorktreeRemove - **MCP Elicitation** -- Elicitation, ElicitationResult - **Notifications** -- Notification @@ -89,7 +90,7 @@ Send event data to an HTTP endpoint: **Use for:** External service integration, centralized logging, webhook-driven workflows. -**Prompt hooks** work on most events (see [Hook Type Support by Event](#hook-type-support-by-event) for the full matrix). The only events restricted to command hooks are SessionStart, WorktreeCreate, and WorktreeRemove. +**Prompt hooks** work on most events (see [Hook Type Support by Event](#hook-type-support-by-event) for the full matrix). SessionStart and WorktreeRemove are restricted to command hooks only. WorktreeCreate supports command and HTTP hooks. **Response format:** Prompt hooks return the standard hook output JSON (`decision`, `reason`, `systemMessage`). For events with event-specific behavior (PreToolUse, PermissionRequest, Elicitation), include `hookSpecificOutput` with event-appropriate fields — see each event's documentation below and `references/event-schemas.md`. @@ -605,6 +606,73 @@ Execute when a configuration file changes during a session. Use for security mon **Gotcha:** `policy_settings` changes cannot be blocked. The block decision is silently ignored. +### Environment + +#### CwdChanged + +Execute when the working directory changes during a session (e.g., when Claude runs `cd`). + +**Matchers:** Not supported (fires on every directory change) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (cannot block directory changes) + +**Input includes:** `old_cwd`, `new_cwd` + +```json +{ + "CwdChanged": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/env-setup.sh" + } + ] + } + ] +} +``` + +**Special capabilities:** + +- Supports `$CLAUDE_ENV_FILE` — write `export VAR=value` to persist env vars into subsequent Bash commands +- Can return `watchPaths` array to dynamically update file monitoring + +**Use case:** Reactive environment management with tools like direnv — reload env vars, activate project-specific toolchains, or run setup scripts on directory change. + +#### FileChanged + +Execute when a watched file changes on disk. + +**Matchers:** Pipe-separated basenames (filenames without directory paths), e.g. `".envrc|.env"` +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** None (cannot block file changes) + +**Input includes:** `file_path` (absolute), `event` (`"change"`, `"add"`, or `"unlink"`) + +```json +{ + "FileChanged": [ + { + "matcher": ".envrc|.env", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/reload-env.sh" + } + ] + } + ] +} +``` + +**Special capabilities:** + +- Supports `$CLAUDE_ENV_FILE` for persisting environment variable changes +- Can return `watchPaths` array to dynamically update monitored paths + +**Use case:** Reloading environment variables when config files change, triggering rebuilds on config modifications. + ### Worktrees #### WorktreeCreate @@ -612,8 +680,8 @@ Execute when a configuration file changes during a session. Use for security mon Execute when a git worktree is created (via `--worktree` flag or subagent `isolation: "worktree"`). **Matchers:** Not supported -**Hook types:** Command only -**Decision control:** Hook must print the **absolute path** to the created worktree directory on stdout. Non-zero exit code fails the creation. +**Hook types:** Command, HTTP +**Decision control:** Hook must return the **absolute path** to the created worktree directory. Command hooks print the path on stdout. HTTP hooks return it via `hookSpecificOutput.worktreePath`. ```json { @@ -632,7 +700,18 @@ Execute when a git worktree is created (via `--worktree` flag or subagent `isola **Input includes:** `name` (worktree identifier) -This is the only hook where stdout is the return value (a path), not JSON. +**HTTP hook response format:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "WorktreeCreate", + "worktreePath": "/absolute/path/to/worktree" + } +} +``` + +For command hooks, stdout is the return value (a path), not JSON. #### WorktreeRemove @@ -847,7 +926,7 @@ Match on MCP server name. ### Events Without Matcher Support -These events ignore the `matcher` field: UserPromptSubmit, Stop, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove. +These events ignore the `matcher` field: UserPromptSubmit, Stop, TeammateIdle, TaskCompleted, CwdChanged, WorktreeCreate, WorktreeRemove. ## Hook Type Support by Event @@ -872,7 +951,9 @@ Not all events support all four hook types: | PreCompact | Yes | Yes | Yes | Yes | | PostCompact | Yes | Yes | Yes | Yes | | ConfigChange | Yes | Yes | Yes | Yes | -| WorktreeCreate | Yes | -- | -- | -- | +| CwdChanged | Yes | Yes | Yes | Yes | +| FileChanged | Yes | Yes | Yes | Yes | +| WorktreeCreate | Yes | Yes | -- | -- | | WorktreeRemove | Yes | -- | -- | -- | | Elicitation | Yes | Yes | Yes | Yes | | ElicitationResult | Yes | Yes | Yes | Yes | @@ -1056,7 +1137,7 @@ echo "$output" | jq . ## Quick Reference -### All 22 Hook Events +### All 24 Hook Events | Event | Category | Matchers | Decision Control | | ------------------ | ------------- | --------------------------- | ----------------------------- | @@ -1077,7 +1158,9 @@ echo "$output" | jq . | PreCompact | Context | manual, auto | None (observability) | | PostCompact | Context | manual, auto | None (observability) | | ConfigChange | Config | Settings sources | Block (except policy) | -| WorktreeCreate | Worktree | None | Stdout = path, exit code | +| CwdChanged | Environment | None | None (env vars, watchPaths) | +| FileChanged | Environment | Basenames (pipe-separated) | None (env vars, watchPaths) | +| WorktreeCreate | Worktree | None | Return path, exit code | | WorktreeRemove | Worktree | None | None (cleanup) | | Elicitation | MCP | MCP server name | Accept/decline/cancel | | ElicitationResult | MCP | MCP server name | Override response | @@ -1102,7 +1185,7 @@ echo "$output" | jq . For detailed patterns and advanced techniques, consult: -- **`references/event-schemas.md`** -- Complete input/output JSON schemas for all 22 events +- **`references/event-schemas.md`** -- Complete input/output JSON schemas for all 24 events - **`references/patterns.md`** -- Proven patterns including temporarily active and configuration-driven hooks - **`references/migration.md`** -- Migrating from basic to advanced hooks - **`references/advanced.md`** -- Advanced use cases and techniques @@ -1146,7 +1229,7 @@ Development tools in `scripts/`: To implement hooks in a plugin: -1. Identify events to hook into (see [Quick Reference](#all-22-hook-events)) +1. Identify events to hook into (see [Quick Reference](#all-24-hook-events)) 2. Decide hook type: prompt (flexible), agent (multi-step), command (deterministic), or HTTP (external) 3. Write hook configuration in `hooks/hooks.json` 4. For command hooks, create hook scripts diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index f4f0a65..4b0611a 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -666,6 +666,10 @@ MCP servers can notify Claude Code of tool changes at runtime via `list_changed` Design plugin MCP tools to return concise results. Paginate or summarize large outputs. +### MCP Description Limits + +Tool descriptions and server instructions are capped at **2KB each**. This prevents OpenAPI-generated servers with verbose schemas from bloating the context window. Keep tool descriptions concise and focused on usage rather than exhaustive parameter documentation. + ## MCP CLI Commands ```bash diff --git a/plugins/plugin-dev/skills/plugin-structure/SKILL.md b/plugins/plugin-dev/skills/plugin-structure/SKILL.md index 53768fc..5af2343 100644 --- a/plugins/plugin-dev/skills/plugin-structure/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-structure/SKILL.md @@ -1,7 +1,7 @@ --- name: plugin-structure version: 0.2.0 -description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "add lspServers", "configure auto-discovery", "headless mode", "CI mode", "plugin in CI", "github actions", "plugin caching", "plugin CLI", "install plugin", "installation scope", "auto-update", "validate plugin", "plugin validate", "debug plugin", "output styles", "outputStyles", "custom output format", "response formatting", "--verbose", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices. +description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "add lspServers", "configure auto-discovery", "headless mode", "CI mode", "plugin in CI", "github actions", "plugin caching", "plugin CLI", "install plugin", "installation scope", "auto-update", "validate plugin", "plugin validate", "debug plugin", "output styles", "outputStyles", "custom output format", "response formatting", "--verbose", "userConfig", "plugin configuration", "sensitive config", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices. --- # Plugin Structure for Claude Code @@ -108,6 +108,38 @@ Specify custom paths for components (supplements default directories): - Cannot use absolute paths - Support arrays for multiple locations +### User Configuration (userConfig) + +Declare configurable values in `.claude-plugin/plugin.json` that users are prompted for when enabling the plugin: + +```json +{ + "name": "plugin-name", + "userConfig": { + "api_endpoint": { + "description": "Your team's API endpoint", + "sensitive": false + }, + "api_token": { + "description": "API authentication token", + "sensitive": true + } + } +} +``` + +**Storage:** + +- Non-sensitive values: stored in `settings.json` under `pluginConfigs[].options` +- Sensitive values (`sensitive: true`): stored in the system keychain (macOS) or `~/.claude/.credentials.json` elsewhere + +**Accessing configured values:** + +- In MCP/LSP server configs, hook commands, and skill/agent content: `${user_config.KEY}` (non-sensitive only) +- As environment variables in plugin subprocesses: `CLAUDE_PLUGIN_OPTION_` + +**Constraints:** Keychain storage has an approximately 2KB total limit for sensitive values. Keep sensitive values small. + ## Component Organization ### Commands (Legacy) diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index 3155b72..cf4169e 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -1,7 +1,7 @@ --- name: skill-development version: 0.2.0 -description: This skill should be used when the user asks to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", "SKILL.md format", "skill frontmatter", "skill triggers", "trigger phrases for skills", "progressive disclosure", "skill references folder", "skill examples folder", "validate skill", "skill model field", "skill hooks", "scoped hooks in skill", "visibility budget", "context budget", "SLASH_COMMAND_TOOL_CHAR_BUDGET", "skill permissions", "Skill() syntax", "visual output", "skill precedence", "argument-hint", or needs guidance on skill structure, file organization, writing style, or skill development best practices for Claude Code plugins. +description: This skill should be used when the user asks to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", "SKILL.md format", "skill frontmatter", "skill triggers", "trigger phrases for skills", "progressive disclosure", "skill references folder", "skill examples folder", "validate skill", "skill model field", "skill hooks", "scoped hooks in skill", "visibility budget", "context budget", "SLASH_COMMAND_TOOL_CHAR_BUDGET", "skill permissions", "Skill() syntax", "visual output", "skill precedence", "argument-hint", "paths frontmatter", "file-scoped skill", or needs guidance on skill structure, file organization, writing style, or skill development best practices for Claude Code plugins. --- # Skill Development for Claude Code Plugins @@ -204,6 +204,19 @@ hooks: Scoped hooks that activate when this skill is loaded and deactivate when it finishes. Supported events: `PreToolUse`, `PostToolUse`, `Stop`. See `references/advanced-frontmatter.md`. +##### paths (optional) + +Scope the skill to specific files using glob patterns: + +```yaml +paths: + - "src/**/*.{ts,tsx}" + - "lib/**/*.ts" + - "tests/**/*.test.ts" +``` + +When set, the skill only loads into context when Claude is working with files matching these patterns. Reduces token usage by making skills contextual rather than always-loaded. Accepts a YAML list of glob patterns with brace expansion support. + ##### argument-hint (optional) ```yaml @@ -414,6 +427,7 @@ Before finalizing a skill: - [ ] (Optional) `model` field if overriding default model - [ ] (Optional) `hooks` field if using scoped hooks - [ ] (Optional) `argument-hint` field for autocomplete hints +- [ ] (Optional) `paths` field for file-scoped activation - [ ] Markdown body is present and substantial - [ ] Referenced files actually exist From 87926cd7d57b2d8a0634c97e4c3663431ea7319b Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Fri, 27 Mar 2026 08:55:02 +1300 Subject: [PATCH 11/33] docs: simplify release procedure to match marketplace distribution No GitHub releases or tags needed. Push to main and users get updates on next plugin refresh. --- docs/release-procedure.md | 105 ++++++++------------------------------ 1 file changed, 22 insertions(+), 83 deletions(-) diff --git a/docs/release-procedure.md b/docs/release-procedure.md index 0908d52..5f1d523 100644 --- a/docs/release-procedure.md +++ b/docs/release-procedure.md @@ -1,6 +1,13 @@ # Version Release Procedure -This document describes the complete release workflow for plugin-dev. +This document describes the release workflow for plugin-dev. + +## How Distribution Works + +This repo is a plugin marketplace. Users install by pointing Claude Code at +the git repo — it clones `main` and reads `marketplace.json`. No GitHub +releases, tags, or release branches needed. Push to `main` and users get the +update on next plugin refresh. ## Version Files @@ -18,25 +25,10 @@ rg 'Version.*v[0-9]' CLAUDE.md ## Release Steps -### 1. Create Release Branch - -```bash -# Ensure main is up to date -git checkout main -git pull origin main - -# Create release branch -git checkout -b release/v0.x.x -``` - -### 2. Update Version Numbers +### 1. Update Version Numbers Update version in **all version files** (must match): -- `plugins/plugin-dev/.claude-plugin/plugin.json` (source of truth) -- `.claude-plugin/marketplace.json` (metadata.version AND plugins[0].version) -- `CLAUDE.md` (version line) - ```bash # Find current version to replace rg '"version"' plugins/plugin-dev/.claude-plugin/plugin.json @@ -46,87 +38,34 @@ rg '"version"' plugins/plugin-dev/.claude-plugin/plugin.json .claude-plugin/mark rg 'Version.*v[0-9]' CLAUDE.md ``` -### 3. Update Documentation +### 2. Update CHANGELOG.md -- `CHANGELOG.md` - Add release notes following Keep a Changelog format: - 1. Review commits since last release: `git log v0.x.x..HEAD --oneline` - 2. Organize into sections: Added, Changed, Fixed, Security, Performance, Documentation - 3. Group related changes and reference PR numbers - 4. Add version comparison links at bottom of file -- Any other relevant documentation +Add release notes following Keep a Changelog format: -> **Note**: The README.md version badge updates automatically from GitHub releases. +1. Review commits since last release: `git log --oneline` (find previous version bump) +2. Organize into sections: Added, Changed, Fixed +3. Group related changes -### 4. Test and Validate +### 3. Lint and Verify ```bash # Lint markdown files -markdownlint-cli2 '**/*.md' +markdownlint '**/*.md' --ignore node_modules # Verify version consistency rg '"version"' plugins/plugin-dev/.claude-plugin/plugin.json .claude-plugin/marketplace.json rg 'Version.*v[0-9]' CLAUDE.md - -# Load plugin locally and test -claude --plugin-dir plugins/plugin-dev - -# Test skills load correctly by asking trigger questions -# Test workflow commands: /plugin-dev:create-plugin, /plugin-dev:create-marketplace -# Test agents trigger appropriately ``` -### 5. Commit and Create PR +### 4. Commit and Push ```bash -# Commit version bump and documentation updates -git add . -git commit -m "chore: prepare release v0.x.x" - -# Push release branch -git push origin release/v0.x.x - -# Create pull request -gh pr create --title "chore: prepare release v0.x.x" \ - --body "Version bump to v0.x.x - -## Changes -- [List major changes] -- [List bug fixes] -- [List documentation updates] - -## Checklist -- [x] Version updated in plugin.json, marketplace.json, CLAUDE.md -- [x] CHANGELOG.md updated with release notes -- [x] Markdownlint passes -- [x] Plugin tested locally -" -``` +git add -u +git commit -m "feat: release v0.x.x -### 6. Merge and Create Release - -After PR review and approval: - -```bash -# Merge PR via GitHub UI or: -gh pr merge --squash # or --merge or --rebase based on preference +Brief description of changes." -# Create GitHub Release (this also creates the tag atomically) -gh release create v0.x.x \ - --target main \ - --title "v0.x.x" \ - --notes-file - <<'EOF' -## Summary - -Brief description of the release focus. - -## What's Changed - -[Copy relevant sections from CHANGELOG.md] - -**Full Changelog**: https://github.com/sjnims/plugin-dev/compare/v0.x-1.x...v0.x.x -EOF +git push ``` -**Note**: Main branch is protected and requires PRs. All version bumps must go through the release branch workflow. The `--target main` flag ensures the tag is created on the correct commit. - -**Publishing**: The entire repository acts as a marketplace. The `plugins/plugin-dev/` directory is the distributable plugin unit. +Users receive the update on next plugin refresh or reinstall. From 4519364ca984c31a016cee80c072b8f8ed5fb1f9 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Fri, 27 Mar 2026 15:59:41 +1300 Subject: [PATCH 12/33] feat: add plugin-dev-guide triage agent and release v0.6.0 Add a Haiku-powered triage agent that matches plugin development questions to the right specialized skill. The guide skill becomes a thin dispatch shim, keeping the main context window clean. --- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 10 + CLAUDE.md | 4 +- ...27-plugin-dev-guide-triage-agent-design.md | 161 ++++++++++++++ plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- plugins/plugin-dev/agents/plugin-dev-guide.md | 99 +++++++++ .../skills/plugin-dev-guide/SKILL.md | 206 +----------------- 7 files changed, 287 insertions(+), 199 deletions(-) create mode 100644 docs/superpowers/specs/2026-03-27-plugin-dev-guide-triage-agent-design.md create mode 100644 plugins/plugin-dev/agents/plugin-dev-guide.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 50c866e..8f0273a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.5.0" + "version": "0.6.0" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.5.0", + "version": "0.6.0", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index 9380191..884f475 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.6.0] - 2026-03-27 + +### Added + +- **plugin-dev-guide agent**: Haiku-powered triage agent that matches plugin development questions to the right specialized skill, keeping the main context window clean + +### Changed + +- **plugin-dev-guide skill**: Converted from in-context routing table to thin dispatch shim that spawns the triage agent and follows its recommendation + ## [0.5.0] - 2026-03-27 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index e26376b..692c1fb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,9 +4,9 @@ Guidance for Claude Code working in this repository. ## What This Is -Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 3 agents, 3 slash commands. +Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 4 agents, 3 slash commands. -**Version**: v0.5.0 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.6.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/docs/superpowers/specs/2026-03-27-plugin-dev-guide-triage-agent-design.md b/docs/superpowers/specs/2026-03-27-plugin-dev-guide-triage-agent-design.md new file mode 100644 index 0000000..0e51937 --- /dev/null +++ b/docs/superpowers/specs/2026-03-27-plugin-dev-guide-triage-agent-design.md @@ -0,0 +1,161 @@ +# Plugin-Dev Guide Triage Agent + +## Problem + +The `plugin-dev-guide` skill loads its full routing table into the main context window every time someone asks a plugin development question. That content exists only to figure out which of the 9 specialized skills to invoke. Once the right skill is loaded, the routing table is dead weight. + +## Solution + +Replace the in-context routing with a Haiku triage agent. The agent matches the user's question to the right skill and reports back. The main agent then loads only that skill. Main context gets exactly one skill (the right one), not the guide overhead. + +## Components + +### 1. New Agent: `agents/plugin-dev-guide.md` + +**Frontmatter:** + +```yaml +name: plugin-dev-guide +model: haiku +color: blue +tools: Read, Grep +``` + +**Description:** Triggers on plugin development questions — "how to build a plugin", "what plugin components exist", "plugin architecture", "extending Claude Code", specific component questions (hooks, MCP, LSP, skills, agents, commands, settings, marketplace), and plugin troubleshooting. + +Includes 4 `` blocks: +1. New-to-plugins overview question +2. Specific component question (e.g., hooks) +3. Capability exploration ("what can plugins do") +4. Troubleshooting ("my skill isn't loading") + +**System prompt structure:** + +1. **Role definition** — Triage agent. Match questions to skills. Do not answer questions directly. + +2. **Routing table** — Compact, one line per skill: + + | Skill | Domain | + |-------|--------| + | plugin-structure | Directory layout, manifest, plugin.json, component auto-discovery, `${CLAUDE_PLUGIN_ROOT}` | + | command-development | Slash commands, frontmatter, dynamic arguments, `$ARGUMENTS`, bash execution, `@` file references | + | agent-development | Subagents, agent system prompts, triggering via description/examples, model/color/tools config | + | skill-development | SKILL.md, progressive disclosure, references/examples/scripts dirs, trigger phrases, `context: fork` | + | hook-development | PreToolUse, PostToolUse, Stop, SessionStart, prompt-based hooks, command-based hooks, scoped hooks | + | mcp-integration | MCP servers, stdio/SSE/HTTP/WebSocket, `.mcp.json`, OAuth, MCP tools in commands/agents | + | lsp-integration | Language servers, go-to-definition, find-references, `extensionToLanguage`, pyright/gopls/rust-analyzer | + | plugin-settings | `.local.md` pattern, YAML frontmatter in hooks, per-project config, agent state | + | marketplace-structure | `marketplace.json`, plugin sources (relative/GitHub/git), distribution, plugin collections | + +3. **Decision process:** + - First pass: match the question to one or more candidate skills from the table + - If exactly one match: report it + - If ambiguous: use Read to skim the top of candidate SKILL.md files (path: `${CLAUDE_PLUGIN_ROOT}/skills//SKILL.md`), pick the best fit + - If the question is a general overview request ("what can plugins do", "list all capabilities", "give me an overview"): report `OVERVIEW` as a special response — the main agent handles these directly from the skill's command/agent tables + - If no match: report `NO_MATCH` + +4. **Also-relevant skills:** If a secondary skill is partially relevant, mention it after the primary recommendation. + +5. **Multi-skill workflows:** If the question spans multiple skills ("build a complete plugin with MCP and hooks"), recommend the primary skill to start with and list the others as a suggested sequence. + +6. **Output format:** + ``` + **Recommended skill:** + **Why:** + **Also relevant:** + ``` + + For overview questions: + ``` + **Recommended skill:** OVERVIEW + **Why:** User is asking for a general overview of plugin capabilities. + ``` + + For no-match: + ``` + **Recommended skill:** NO_MATCH + **Why:** + ``` + +7. **Constraints:** + - Do not answer the user's question. Only recommend which skill to invoke. + - Do not fabricate skill descriptions. If unsure whether a skill covers a topic, read the file. + - Keep responses under 100 words. + +### 2. Updated Skill: `skills/plugin-dev-guide/SKILL.md` + +**Frontmatter:** Same `name` and `description` (triggering conditions unchanged). + +**Body:** Replace the current routing table and decision tree with dispatch instructions: + +```markdown +# Plugin Development Guide + +Spawn the `plugin-dev:plugin-dev-guide` agent (subagent_type: `plugin-dev:plugin-dev-guide`) with the user's question as the prompt. Pass `$ARGUMENTS` as the agent's task. + +When the agent reports back, follow its recommendation: + +1. **Skill recommended** — invoke that skill using the Skill tool (e.g., `Skill("plugin-dev:mcp-integration")`) +2. **OVERVIEW** — the user wants a general overview; summarize the available skills, commands, and agents from the tables below +3. **NO_MATCH** — no plugin-dev skill covers this topic; answer directly or ask for clarification +4. **Also-relevant skills mentioned** — note these to the user as follow-up options +5. **Agent fails or returns unrecognized output** — fall back to asking the user which area they need help with, listing the skill domains: plugin structure, commands, agents, skills, hooks, MCP, LSP, settings, marketplace + +## Available Commands + +| Command | Purpose | +| -------------------------------- | --------------------------------------------------- | +| `/plugin-dev:start` | Entry point - choose plugin or marketplace creation | +| `/plugin-dev:create-plugin` | 8-phase guided plugin creation workflow | +| `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow | + +## Available Agents + +| Agent | Purpose | +| -------------------- | ------------------------------------------ | +| **plugin-validator** | Validates plugin structure and manifests | +| **skill-reviewer** | Reviews skill quality and triggering | +| **agent-creator** | Generates new agents from descriptions | + +$ARGUMENTS +``` + +The skill retains command/agent reference tables since those are small and useful for the main agent to have in context. The routing logic (the expensive part) moves to the triage agent. `$ARGUMENTS` is passed through as the triage agent's task prompt. + +## What Does NOT Change + +- The 9 specialized skills (untouched) +- The 3 existing agents: plugin-validator, skill-reviewer, agent-creator (untouched) +- The 3 commands: start, create-plugin, create-marketplace (untouched) +- `plugin.json` manifest (agents are auto-discovered from `agents/` directory) + +## Flow + +``` +User: "How do I add MCP to my plugin?" + -> Main agent sees plugin-dev question, loads plugin-dev-guide skill + -> Skill says: dispatch plugin-dev:plugin-dev-guide agent + -> Haiku agent: matches "MCP" -> mcp-integration + (optionally reads SKILL.md to confirm) + -> Returns: "Recommended skill: mcp-integration. Covers MCP server types, auth, .mcp.json config." + -> Main agent invokes /mcp-integration + -> User gets full MCP guidance in main context for follow-up conversation +``` + +## Design Decisions + +**Why Haiku?** This is pattern matching against a 9-row table, not deep reasoning. Haiku is fast and cheap. The specialized skill (loaded afterward) does the actual teaching. + +**Why Read/Grep tools?** Insurance against the routing table going stale. If the table drifts from actual skill content, the agent can verify by reading the file. One file read is cheap. + +**Why no WebFetch?** Doc fetching is a reasoning task that belongs in the main context after the right skill is loaded, not in a fast triage agent. Haiku's smaller context window makes large web fetches counterproductive. + +**Why not `context: fork`?** The `agent` field in skill frontmatter only accepts built-in agent types (`Explore`, `Plan`, `general`). Custom plugin agents can't be referenced. The superpowers plugin confirms this pattern: it dispatches subagents via the Agent tool with crafted prompts, not via `context: fork`. + +**Why keep command/agent tables in the skill?** They're small (6 rows total) and the main agent benefits from knowing about `/create-plugin` and the validator agents. Not worth offloading. + +**Why drop multi-skill workflow recipes?** The current skill has "Building a Complete Plugin" and similar workflow sections. These are useful but rarely needed — most questions map to a single skill. The triage agent handles multi-skill questions by recommending a primary skill and listing a sequence. If workflow recipes prove valuable enough to keep, they can move to a `references/workflows.md` file in the skill directory. + +**Why no `skills` field in agent frontmatter?** The triage agent doesn't need skill content loaded into its context. It uses the routing table in its system prompt for fast matching and falls back to reading SKILL.md files directly via the Read tool when disambiguation is needed. Loading skills would bloat the agent's context, defeating the "fast triage" purpose. + +**Why no Glob tool?** The agent knows the exact path pattern for every SKILL.md file (`${CLAUDE_PLUGIN_ROOT}/skills//SKILL.md`). Pattern-based file discovery isn't needed. diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 41a43ac..cf0537a 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.5.0", + "version": "0.6.0", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/agents/plugin-dev-guide.md b/plugins/plugin-dev/agents/plugin-dev-guide.md new file mode 100644 index 0000000..8efa771 --- /dev/null +++ b/plugins/plugin-dev/agents/plugin-dev-guide.md @@ -0,0 +1,99 @@ +--- +name: plugin-dev-guide +description: Use this agent when the user asks about "Claude Code plugins", "plugin development", "how to build a plugin", "what plugin components exist", "plugin architecture", "extending Claude Code", or needs help with a specific plugin component (hooks, MCP, LSP, skills, agents, commands, settings, marketplace). Also use when troubleshooting plugin issues. Examples: + + +Context: User is new to plugin development +user: "How do I build a Claude Code plugin?" +assistant: "I'll use the plugin-dev-guide agent to find the right skill for this." + +General plugin development question triggers the guide agent for triage. + + + + +Context: User needs help with a specific component +user: "How do hooks work in Claude Code plugins?" +assistant: "I'll use the plugin-dev-guide agent to identify the right skill." + +Specific component question — agent matches to hook-development skill. + + + + +Context: User wants to understand capabilities +user: "What can plugins do in Claude Code?" +assistant: "I'll use the plugin-dev-guide agent to provide an overview." + +Overview question — agent returns OVERVIEW so main agent summarizes. + + + + +Context: User is troubleshooting +user: "My skill isn't being loaded when I ask about PDF processing" +assistant: "I'll use the plugin-dev-guide agent to find the right troubleshooting skill." + +Troubleshooting often maps to skill-development or plugin-structure. + + + +model: haiku +color: blue +tools: Read, Grep +--- + +You are a triage agent for the plugin-dev plugin. Your only job is to match the user's question to the right specialized skill. Do not answer the question yourself. + +## Routing Table + +| Skill | Domain | +|-------|--------| +| plugin-structure | Directory layout, manifest, plugin.json, component auto-discovery, `${CLAUDE_PLUGIN_ROOT}`, headless/CI mode, outputStyles, userConfig | +| command-development | Slash commands, frontmatter, dynamic arguments, `$ARGUMENTS`, bash execution, `@` file references, `disable-model-invocation` | +| agent-development | Subagents, agent system prompts, triggering via description/examples, model/color/tools config, permissionMode, maxTurns, agent teams | +| skill-development | SKILL.md, progressive disclosure, references/examples/scripts dirs, trigger phrases, `context: fork`, `allowed-tools`, `user-invocable` | +| hook-development | PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, prompt-based hooks, command-based hooks, scoped hooks in skills/agents | +| mcp-integration | MCP servers, stdio/SSE/HTTP/WebSocket, `.mcp.json`, OAuth, MCP tools in commands/agents, MCP prompts as commands, tool search | +| lsp-integration | Language servers, go-to-definition, find-references, `extensionToLanguage`, pyright/gopls/rust-analyzer, socket transport | +| plugin-settings | `.local.md` pattern, YAML frontmatter in hooks, per-project config, agent state, memory hierarchy | +| marketplace-structure | `marketplace.json`, plugin sources (relative/GitHub/git), distribution, plugin collections, `strictKnownMarketplaces` | + +## Decision Process + +1. Match the question to candidate skills from the table above +2. If exactly one match: report it +3. If ambiguous between candidates: use Read to skim the top of the SKILL.md file at `${CLAUDE_PLUGIN_ROOT}/skills//SKILL.md` to confirm the best fit +4. If the question is a general overview ("what can plugins do", "list capabilities", "give me an overview"): report `OVERVIEW` +5. If the question spans multiple skills ("build a plugin with MCP and hooks"): recommend the primary skill to start with and list others as a suggested sequence +6. If no skill matches: report `NO_MATCH` + +## Output Format + +For a skill match: + +``` +**Recommended skill:** +**Why:** +**Also relevant:** +``` + +For overview questions: + +``` +**Recommended skill:** OVERVIEW +**Why:** User is asking for a general overview of plugin capabilities. +``` + +For no match: + +``` +**Recommended skill:** NO_MATCH +**Why:** +``` + +## Constraints + +- Do not answer the user's question. Only recommend which skill to invoke. +- Do not fabricate skill descriptions. If unsure whether a skill covers a topic, read the file. +- Keep responses under 100 words. diff --git a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md index 2da95d0..21fbcdb 100644 --- a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md @@ -5,212 +5,30 @@ description: This skill should be used when the user asks about "Claude Code plu # Plugin Development Guide -This meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand. +Spawn the `plugin-dev:plugin-dev-guide` agent (subagent_type: `plugin-dev:plugin-dev-guide`) with the user's question as the prompt. Pass `$ARGUMENTS` as the agent's task. -Your goal is to match the user request (or recent conversation context) to the appropriate skill below, then invoke it using the Skill tool. +When the agent reports back, follow its recommendation: -## Plugin Development Skills Overview - -The plugin-dev toolkit provides 9 specialized skills and 3 slash commands for building Claude Code plugins, plus this guide. Each handles a specific domain of plugin development. - -### Skill Quick Reference - -| Skill | Purpose | -| ------- | --------- | -| /plugin-structure | Directory layout, manifest, component organization | -| /command-development | Slash commands with frontmatter | -| /agent-development | Autonomous subagents | -| /skill-development | Creating skills with progressive disclosure | -| /hook-development | Event-driven automation | -| /mcp-integration | Model Context Protocol servers | -| /lsp-integration | Language Server Protocol for code intelligence | -| /plugin-settings | User configuration via .local.md | -| /marketplace-structure | Plugin marketplace creation | -| /plugin-dev:start | Entry point — choose plugin or marketplace creation | -| /plugin-dev:create-plugin | 8-phase guided plugin creation workflow | -| /plugin-dev:create-marketplace | 8-phase guided marketplace creation workflow | - -## When to Use Each Skill - -### Starting a New Plugin - -**Skill: `plugin-structure`** - -Use when the user needs to: - -- Create a new plugin from scratch -- Understand plugin directory layout -- Configure plugin.json manifest -- Learn about component auto-discovery -- Use ${CLAUDE_PLUGIN_ROOT} for portable paths - -### Adding User-Facing Commands - -**Skill: `command-development`** - -Use when the user needs to: - -- Create slash commands (/command-name) -- Configure command frontmatter (description, allowed-tools, model) -- Use dynamic arguments ($ARGUMENTS, $1, $2) -- Reference files with @ syntax -- Execute bash inline with `[BANG]` backticks - -### Creating Autonomous Agents - -**Skill: `agent-development`** - -Use when the user needs to: - -- Create subagents for complex tasks -- Write agent system prompts -- Configure agent triggering (description with examples) -- Choose agent models and colors -- Restrict agent tool access - -### Building Skills - -**Skill: `skill-development`** - -Use when the user needs to: - -- Create skills that extend Claude's capabilities -- Write SKILL.md with proper frontmatter -- Organize skill content with progressive disclosure -- Create references/, examples/, scripts/ directories -- Write effective trigger phrases - -### Implementing Event Hooks - -**Skill: `hook-development`** - -Use when the user needs to: - -- React to Claude Code events (PreToolUse, Stop, SessionStart, etc.) -- Create prompt-based or command-based hooks -- Validate tool inputs before execution -- Enforce completion standards -- Block dangerous operations - -### Integrating External Services via MCP - -**Skill: `mcp-integration`** - -Use when the user needs to: - -- Add MCP servers to plugins -- Configure stdio, SSE, HTTP, or WebSocket servers -- Set up authentication (OAuth, tokens) -- Use MCP tools in commands and agents -- Discover existing MCP servers on PulseMCP - -### Adding Code Intelligence via LSP - -**Skill: `lsp-integration`** - -Use when the user needs to: - -- Add Language Server Protocol servers to plugins -- Enable go-to-definition and find-references -- Configure language-specific servers (pyright, gopls, rust-analyzer) -- Set up extensionToLanguage mappings -- Enhance Claude's code understanding - -### Managing Plugin Configuration - -**Skill: `plugin-settings`** - -Use when the user needs to: - -- Store user-configurable settings -- Use .claude/plugin-name.local.md pattern -- Parse YAML frontmatter in hooks -- Create temporarily active hooks -- Manage agent state - -### Creating Plugin Marketplaces - -**Skill: `marketplace-structure`** - -Use when the user needs to: - -- Create a marketplace for multiple plugins -- Configure marketplace.json -- Set up plugin sources (relative, GitHub, git URL) -- Distribute plugins to teams -- Organize plugin collections - -## Decision Tree for Skill Selection - -``` -User wants to... -├── Create/organize a plugin structure? → plugin-structure -├── Add a simple slash command (no bundled resources)? → command-development -├── Create an autonomous agent? → agent-development -├── Add a complex skill with scripts/references? → skill-development -├── React to Claude Code events? → hook-development -├── Integrate external service/API? → mcp-integration -├── Add code intelligence/LSP? → lsp-integration -├── Make plugin configurable? → plugin-settings -└── Distribute multiple plugins? → marketplace-structure -``` +1. **Skill recommended** — invoke that skill using the Skill tool (e.g., `Skill("plugin-dev:mcp-integration")`) +2. **OVERVIEW** — the user wants a general overview; summarize the available skills, commands, and agents from the tables below +3. **NO_MATCH** — no plugin-dev skill covers this topic; answer directly or ask for clarification +4. **Also-relevant skills mentioned** — note these to the user as follow-up options +5. **Agent fails or returns unrecognized output** — fall back to asking the user which area they need help with, listing the skill domains: plugin structure, commands, agents, skills, hooks, MCP, LSP, settings, marketplace ## Available Commands | Command | Purpose | | -------------------------------- | --------------------------------------------------- | -| `/plugin-dev:plugin-dev-guide` | Overview and skill routing | | `/plugin-dev:start` | Entry point - choose plugin or marketplace creation | | `/plugin-dev:create-plugin` | 8-phase guided plugin creation workflow | | `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow | -## Common Multi-Skill Workflows - -### Building a Complete Plugin - -1. Invoke `plugin-structure` to create directory layout -2. Invoke `command-development` for user-facing commands -3. Invoke `hook-development` for event-driven behavior -4. Invoke `plugin-settings` if user configuration needed -5. Use plugin-validator agent to validate structure - -### Creating an MCP-Powered Plugin - -1. Invoke `plugin-structure` for basic structure -2. Invoke `mcp-integration` to configure MCP servers -3. Invoke `command-development` to create commands that use MCP tools -4. Invoke `agent-development` for autonomous MCP workflows - -### Building a Code Intelligence Plugin - -1. Invoke `plugin-structure` for basic structure -2. Invoke `lsp-integration` to configure language servers -3. Invoke `command-development` for commands using LSP features - -### Building a Skill-Focused Plugin - -1. Invoke `plugin-structure` for basic structure -2. Invoke `skill-development` to create specialized skills -3. Use skill-reviewer agent to validate skill quality - ## Available Agents -The plugin-dev plugin also provides 3 agents: - -| Agent | Purpose | -|-------|---------| -| **plugin-validator** | Validates plugin structure and manifests | -| **skill-reviewer** | Reviews skill quality and triggering | -| **agent-creator** | Generates new agents from descriptions | - -Use agents proactively after creating components to ensure quality. - ---- - -## User Request - -Match the user request below to a skill from the table above, then invoke it with the Skill tool. If no single skill matches, answer directly using this guide. If the request is ambiguous, ask for clarification. - -If no request was provided, summarize the available capabilities and ask what the user wants to build or learn about. +| Agent | Purpose | +| -------------------- | ------------------------------------------ | +| **plugin-validator** | Validates plugin structure and manifests | +| **skill-reviewer** | Reviews skill quality and triggering | +| **agent-creator** | Generates new agents from descriptions | $ARGUMENTS From 97f190949d283cb575e6b270214dc7bc3b0fa78c Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sat, 28 Mar 2026 18:52:03 +1300 Subject: [PATCH 13/33] fix: correct skills field format from YAML array to comma-separated string and release v0.6.1 The agent-development and skill-development skills documented the skills frontmatter field as a YAML array, but Claude Code parses it as a comma-separated string (same as tools and disallowedTools). --- .claude-plugin/marketplace.json | 4 ++-- CHANGELOG.md | 7 +++++++ CLAUDE.md | 2 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- plugins/plugin-dev/skills/agent-development/SKILL.md | 7 ++----- plugins/plugin-dev/skills/skill-development/SKILL.md | 4 +--- 6 files changed, 14 insertions(+), 12 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8f0273a..67ed1bd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.6.0" + "version": "0.6.1" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.6.0", + "version": "0.6.1", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index 884f475..c415b6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.6.1] - 2026-03-28 + +### Fixed + +- **agent-development**: `skills` field documented as YAML array; corrected to comma-separated string matching actual Claude Code runtime behavior +- **skill-development**: Same YAML array fix for `skills` field in `context: fork` example + ## [0.6.0] - 2026-03-27 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 692c1fb..3a4bbdf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 4 agents, 3 slash commands. -**Version**: v0.6.0 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.6.1 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index cf0537a..2141399 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.6.0", + "version": "0.6.1", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index a44ab97..930e9df 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -277,10 +277,7 @@ disallowedTools: Bash, Write Load specific skills into the agent's context: ```yaml -skills: - - testing-patterns - - security-audit - - api-design +skills: testing-patterns, security-audit, api-design ``` **Use cases:** @@ -580,7 +577,7 @@ Ensure system prompt is complete: | 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] | +| skills | No | Comma-separated skill names | testing, security | | permissionMode | No | Permission mode string | acceptEdits | | maxTurns | No | Integer | 50 | | memory | No | Scope string | user | diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index cf4169e..8e5d479 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -126,9 +126,7 @@ name: comprehensive-review description: Full code review with testing... context: fork agent: general -skills: - - testing-patterns - - security-audit +skills: testing-patterns, security-audit --- ``` From 9ac223304a61cd511ea3f34416e81bdc8aeb3768 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 13:40:45 +1300 Subject: [PATCH 14/33] fix: update repo ownership to kylesnowschwartz and fix stale doc URLs - Replace all sjnims/plugin-dev references with kylesnowschwartz/plugin-dev - Update CODEOWNERS, dependabot assignees/reviewers, maintainer contact - Update Anthropic doc URLs to current code.claude.com and platform.claude.com - Remove scheduled trigger from link checker (keep PR + manual dispatch) - Remove fork guard from stale workflow --- .github/CODEOWNERS | 16 +++++++------- .github/ISSUE_TEMPLATE/config.yml | 6 ++--- .github/dependabot.yml | 4 ++-- .github/workflows/links.yml | 3 +-- .lycheeignore | 2 +- CHANGELOG.md | 12 +++++----- CODE_OF_CONDUCT.md | 2 +- CONTRIBUTING.md | 22 +++++++++---------- README.md | 20 ++++++++--------- SECURITY.md | 10 ++++----- docs/troubleshooting.md | 2 +- .../skills/agent-development/SKILL.md | 2 +- .../references/frontmatter-reference.md | 4 ++-- .../skills/hook-development/SKILL.md | 2 +- .../skills/lsp-integration/SKILL.md | 2 +- .../skills/mcp-integration/SKILL.md | 2 +- 16 files changed, 55 insertions(+), 56 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0573267..35b22a6 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,21 +5,21 @@ # to enable per-area ownership when the team grows. # Default owner for everything -* @sjnims +* @kylesnowschwartz # --- Specific ownership rules (ready for team scaling) --- # GitHub configuration (workflows, templates, dependabot) -/.github/ @sjnims +/.github/ @kylesnowschwartz # Plugin core -/plugins/plugin-dev/ @sjnims +/plugins/plugin-dev/ @kylesnowschwartz # Critical documentation -/README.md @sjnims -/CLAUDE.md @sjnims -/SECURITY.md @sjnims +/README.md @kylesnowschwartz +/CLAUDE.md @kylesnowschwartz +/SECURITY.md @kylesnowschwartz # Manifests (version management) -/plugins/plugin-dev/.claude-plugin/plugin.json @sjnims -/.claude-plugin/marketplace.json @sjnims +/plugins/plugin-dev/.claude-plugin/plugin.json @kylesnowschwartz +/.claude-plugin/marketplace.json @kylesnowschwartz diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 3ac0a7a..f290005 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,17 +2,17 @@ blank_issues_enabled: false contact_links: # 1. Documentation first - many issues are answered here - name: Documentation & Troubleshooting - url: https://github.com/sjnims/plugin-dev/blob/main/README.md + url: https://github.com/kylesnowschwartz/plugin-dev/blob/main/README.md about: Full documentation, usage examples, and troubleshooting guide (docs/troubleshooting.md) # 2. Contributing Guidelines - for those wanting to contribute - name: Contributing Guidelines - url: https://github.com/sjnims/plugin-dev/blob/main/CONTRIBUTING.md + url: https://github.com/kylesnowschwartz/plugin-dev/blob/main/CONTRIBUTING.md about: Learn how to contribute, coding standards, and pull request process # 3. GitHub Discussions - preferred for questions - name: GitHub Discussions - url: https://github.com/sjnims/plugin-dev/discussions + url: https://github.com/kylesnowschwartz/plugin-dev/discussions about: Ask questions, share ideas, and get help from the community # 4. Claude Code Documentation - official plugin development docs diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 2d14d8a..e1113c9 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -12,9 +12,9 @@ updates: - "dependencies" - "github-actions" assignees: - - "sjnims" + - "kylesnowschwartz" reviewers: - - "sjnims" + - "kylesnowschwartz" commit-message: prefix: "chore" include: "scope" diff --git a/.github/workflows/links.yml b/.github/workflows/links.yml index 74897a9..1c5d576 100644 --- a/.github/workflows/links.yml +++ b/.github/workflows/links.yml @@ -1,6 +1,7 @@ name: Check Links # Checks all markdown files for broken links using lychee +# Runs on PRs that touch .md files and on manual dispatch # Key flags: # --cache: Cache results to speed up subsequent runs # --exclude-link-local: Skip localhost/127.0.0.1 links (not reachable in CI) @@ -11,8 +12,6 @@ on: pull_request: paths: - "**.md" - schedule: - - cron: "0 0 * * 0" # Weekly on Sunday at midnight UTC workflow_dispatch: concurrency: diff --git a/.lycheeignore b/.lycheeignore index c83a6ca..7a94140 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -3,4 +3,4 @@ https://claude.ai https://claude.ai/code # Changelog comparison links (tags may not exist yet during release PRs) -https://github.com/sjnims/plugin-dev/compare/.* +https://github.com/kylesnowschwartz/plugin-dev/compare/.* diff --git a/CHANGELOG.md b/CHANGELOG.md index c415b6f..be53df0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -292,9 +292,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 [Unreleased]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.4.1...HEAD [0.4.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.4.0...v0.4.1 [0.4.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.3.2...v0.4.0 -[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 -[0.3.0]: https://github.com/sjnims/plugin-dev/compare/v0.2.1...v0.3.0 -[0.2.1]: https://github.com/sjnims/plugin-dev/compare/v0.2.0...v0.2.1 -[0.2.0]: https://github.com/sjnims/plugin-dev/compare/v0.1.0...v0.2.0 -[0.1.0]: https://github.com/sjnims/plugin-dev/releases/tag/v0.1.0 +[0.3.2]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.3.1...v0.3.2 +[0.3.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.3.0...v0.3.1 +[0.3.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.2.1...v0.3.0 +[0.2.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.2.0...v0.2.1 +[0.2.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.1.0...v0.2.0 +[0.1.0]: https://github.com/kylesnowschwartz/plugin-dev/releases/tag/v0.1.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index d8457f6..0bf1eca 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -43,7 +43,7 @@ We agree to restrict the following behaviors in our community. Instances, threat Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. -When an incident does occur, it is important to report it promptly. To report a possible violation, **use GitHub's Private Vulnerability Reporting or email directly.** +When an incident does occur, it is important to report it promptly. To report a possible violation, **use GitHub's Private Vulnerability Reporting or email directly.** Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5be1579..ac79225 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ Thank you for your interest in contributing to the Plugin Dev toolkit for Claude ## Code of Conduct -This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to . +This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to . ## Getting Started @@ -73,7 +73,7 @@ cd plugin-dev ### 2. Set Up Remote ```bash -git remote add upstream https://github.com/sjnims/plugin-dev.git +git remote add upstream https://github.com/kylesnowschwartz/plugin-dev.git ``` ### 3. Create a Branch @@ -412,7 +412,7 @@ git push origin feature/your-feature-name ### 5. Create a Pull Request -1. Go to the [repository](https://github.com/sjnims/plugin-dev) +1. Go to the [repository](https://github.com/kylesnowschwartz/plugin-dev) 2. Click "New Pull Request" 3. Select your fork and branch 4. Fill out the PR template completely @@ -482,14 +482,14 @@ Version releases are handled by maintainers. If your contribution requires a ver ### Getting Help -- **Questions**: Open an issue with the [question template](https://github.com/sjnims/plugin-dev/issues/new?template=question.yml) -- **Discussions**: Use [GitHub Discussions](https://github.com/sjnims/plugin-dev/discussions) +- **Questions**: Open an issue with the [question template](https://github.com/kylesnowschwartz/plugin-dev/issues/new?template=question.yml) +- **Discussions**: Use [GitHub Discussions](https://github.com/kylesnowschwartz/plugin-dev/discussions) ### Reporting Issues -- **Bugs**: Use the [bug report template](https://github.com/sjnims/plugin-dev/issues/new?template=bug_report.yml) -- **Features**: Use the [feature request template](https://github.com/sjnims/plugin-dev/issues/new?template=feature_request.yml) -- **Documentation**: Use the [documentation template](https://github.com/sjnims/plugin-dev/issues/new?template=documentation.yml) +- **Bugs**: Use the [bug report template](https://github.com/kylesnowschwartz/plugin-dev/issues/new?template=bug_report.yml) +- **Features**: Use the [feature request template](https://github.com/kylesnowschwartz/plugin-dev/issues/new?template=feature_request.yml) +- **Documentation**: Use the [documentation template](https://github.com/kylesnowschwartz/plugin-dev/issues/new?template=documentation.yml) - **Security**: See [SECURITY.md](SECURITY.md) ### Code Review Process @@ -513,9 +513,9 @@ Contributors are recognized in: If you have questions not covered here: 1. Check [CLAUDE.md](CLAUDE.md) for development details -2. Search [existing issues](https://github.com/sjnims/plugin-dev/issues) -3. Open a [question issue](https://github.com/sjnims/plugin-dev/issues/new?template=question.yml) -4. Start a [discussion](https://github.com/sjnims/plugin-dev/discussions) +2. Search [existing issues](https://github.com/kylesnowschwartz/plugin-dev/issues) +3. Open a [question issue](https://github.com/kylesnowschwartz/plugin-dev/issues/new?template=question.yml) +4. Start a [discussion](https://github.com/kylesnowschwartz/plugin-dev/discussions) --- diff --git a/README.md b/README.md index ddef08f..38f618e 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ # Plugin Development Toolkit -[![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/github/v/release/sjnims/plugin-dev?label=version&color=blue)](https://github.com/sjnims/plugin-dev/releases) +[![CI](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/component-validation.yml/badge.svg)](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/component-validation.yml) +[![Markdown](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/markdownlint.yml/badge.svg)](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/markdownlint.yml) +[![Version](https://img.shields.io/github/v/release/kylesnowschwartz/plugin-dev?label=version&color=blue)](https://github.com/kylesnowschwartz/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. @@ -45,7 +45,7 @@ Each component follows progressive disclosure: lean core documentation with deta ### Required -- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured +- [Claude Code CLI](https://code.claude.com/docs) installed and configured - Git (for version control and marketplace publishing) ### For Utility Scripts @@ -74,8 +74,8 @@ grep --version 2>&1 | head -1 Add this marketplace and install the plugin: ```bash -/plugin marketplace add sjnims/plugin-dev -/plugin install plugin-dev@sjnims/plugin-dev +/plugin marketplace add kylesnowschwartz/plugin-dev +/plugin install plugin-dev@kylesnowschwartz/plugin-dev ``` Or for development, use directly: @@ -397,9 +397,9 @@ To contribute improvements: ## Getting Help -- **Issues**: [GitHub Issues](https://github.com/sjnims/plugin-dev/issues) -- **Documentation**: [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins) -- **Skills Reference**: [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills) +- **Issues**: [GitHub Issues](https://github.com/kylesnowschwartz/plugin-dev/issues) +- **Documentation**: [Claude Code Plugins](https://code.claude.com/docs/en/plugins) +- **Skills Reference**: [Claude Code Skills](https://code.claude.com/docs/en/skills) ## Attribution @@ -408,7 +408,7 @@ This plugin was originally developed by [Daisy Hollman](mailto:daisy@anthropic.c - [claude-code/plugins/plugin-dev](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev) - [claude-plugins-official/plugins/plugin-dev](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev) -This repository ([sjnims/plugin-dev](https://github.com/sjnims/plugin-dev)) is an expanded version with: +This repository ([kylesnowschwartz/plugin-dev](https://github.com/kylesnowschwartz/plugin-dev)) is an expanded version with: - Enhanced skill descriptions with stronger trigger phrases - Additional utility scripts (test-agent-trigger.sh, create-agent-skeleton.sh) diff --git a/SECURITY.md b/SECURITY.md index 1db39d4..ac4961e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -19,7 +19,7 @@ Instead, please report them using one of the following methods: ### Preferred: GitHub Private Vulnerability Reporting -1. Go to the [Security Advisories](https://github.com/sjnims/plugin-dev/security/advisories) page +1. Go to the [Security Advisories](https://github.com/kylesnowschwartz/plugin-dev/security/advisories) page 2. Click "Report a vulnerability" 3. Fill out the advisory details form @@ -27,7 +27,7 @@ This is the preferred method as it allows us to work with you privately to fix t ### Alternative: Email -If you prefer, you can also email security concerns to: **** +If you prefer, you can also email security concerns to: **** Please include: @@ -147,9 +147,9 @@ _No security issues have been reported yet._ ## Contact -- **Security Issues**: Use [GitHub Private Vulnerability Reporting](https://github.com/sjnims/plugin-dev/security/advisories) or email -- **General Questions**: Open an issue using our [question template](https://github.com/sjnims/plugin-dev/issues/new/choose) -- **Maintainer**: Steve Nims ([@sjnims](https://github.com/sjnims)) +- **Security Issues**: Use [GitHub Private Vulnerability Reporting](https://github.com/kylesnowschwartz/plugin-dev/security/advisories) or email +- **General Questions**: Open an issue using our [question template](https://github.com/kylesnowschwartz/plugin-dev/issues/new/choose) +- **Maintainer**: Kyle Snow Schwartz ([@kylesnowschwartz](https://github.com/kylesnowschwartz)) ## Additional Resources diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 5c03893..c0d171d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -54,4 +54,4 @@ Paths relative to `plugins/plugin-dev/`: - 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 +- Open an [issue](https://github.com/kylesnowschwartz/plugin-dev/issues) if you're stuck diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 930e9df..1c5ee69 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -19,7 +19,7 @@ Agents are autonomous subprocesses that handle complex, multi-step tasks indepen > **Important - Field Name Difference:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. Don't confuse these when switching between component types. > -> **Note on Official Documentation:** The `color` field documented in this skill is supported by Claude Code and is generated by the built-in `/agents` command, but it is not yet reflected in the [official sub-agents documentation](https://docs.claude.com/en/docs/claude-code/sub-agents). See [anthropics/claude-code#8501](https://github.com/anthropics/claude-code/issues/8501) for tracking. The [plugins-reference.md](https://docs.claude.com/en/docs/claude-code/plugins-reference) may show an older agent format using a `capabilities` field; for Claude Code plugins, prefer the structure documented in this skill which uses `tools` for tool restrictions. +> **Note on Official Documentation:** The `color` field documented in this skill is supported by Claude Code and is generated by the built-in `/agents` command, but it is not yet reflected in the [official sub-agents documentation](https://code.claude.com/docs/en/sub-agents). See [anthropics/claude-code#8501](https://github.com/anthropics/claude-code/issues/8501) for tracking. The [plugins-reference.md](https://code.claude.com/docs/en/plugins-reference) may show an older agent format using a `capabilities` field; for Claude Code plugins, prefer the structure documented in this skill which uses `tools` for tool restrictions. ## Quick Start diff --git a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md index 885d840..ceb2189 100644 --- a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md +++ b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md @@ -149,7 +149,7 @@ allowed-tools: "*" Both formats are accepted. Shorthand names use the current default version of each model family. -> **Note:** Anthropic releases new model versions periodically. For current model IDs, consult [Claude Models Overview](https://docs.anthropic.com/en/docs/about-claude/models). Prefer shorthand names unless you need a specific version. +> **Note:** Anthropic releases new model versions periodically. For current model IDs, consult [Claude Models Overview](https://platform.claude.com/docs/en/about-claude/models/overview). Prefer shorthand names unless you need a specific version. **Purpose:** Specify which Claude model executes the command @@ -484,7 +484,7 @@ allowed-tools: Bash # ❌ Missing command filter model: gpt4 # ❌ Not a valid Claude model ``` -**Fix:** Use shorthand (`sonnet`, `opus`, `haiku`) or full model ID (see [Claude Models Overview](https://docs.anthropic.com/en/docs/about-claude/models)) +**Fix:** Use shorthand (`sonnet`, `opus`, `haiku`) or full model ID (see [Claude Models Overview](https://platform.claude.com/docs/en/about-claude/models/overview)) ### Validation Checklist diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index df625c1..26829bd 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/plugins/plugin-dev/skills/hook-development/SKILL.md @@ -1221,7 +1221,7 @@ Development tools in `scripts/`: ### External Resources -- **Official Docs**: +- **Official Docs**: - **Testing**: Use `claude --debug` for detailed logs - **Validation**: Use `jq` to validate hook JSON output diff --git a/plugins/plugin-dev/skills/lsp-integration/SKILL.md b/plugins/plugin-dev/skills/lsp-integration/SKILL.md index 8158208..0e89436 100644 --- a/plugins/plugin-dev/skills/lsp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/lsp-integration/SKILL.md @@ -449,5 +449,5 @@ For detailed information, consult: ### External Resources - **LSP Specification**: -- **Claude Code Plugins Reference**: +- **Claude Code Plugins Reference**: - **Language Server List**: diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index 4b0611a..b31bb42 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -707,7 +707,7 @@ Working examples in `examples/`: ### External Resources - **Official MCP Docs**: -- **Claude Code MCP Docs**: +- **Claude Code MCP Docs**: - **MCP SDK**: @modelcontextprotocol/sdk - **Testing**: Use `claude --debug` and `/mcp` command From 39e987ef07507064b19cef0549a03c7ed4c0fd9e Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 14:06:47 +1300 Subject: [PATCH 15/33] docs: add update-from-upstream design spec Design for a skill + agent pipeline that keeps plugin-dev current with Claude Code upstream changes. Four-stage pipeline with three dedicated verification agents and source triangulation. --- .../2026-03-29-update-from-upstream-design.md | 203 ++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-29-update-from-upstream-design.md diff --git a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md new file mode 100644 index 0000000..ee6fc7a --- /dev/null +++ b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md @@ -0,0 +1,203 @@ +# Update From Upstream - Design Spec + +## Problem + +Claude Code releases frequently (multiple times per week) with minimal documentation investment. Changes to the plugin system, hook events, agent features, and tool behavior are buried in a flat changelog with no dates, mixed categories, and inconsistent coverage. The official docs lag behind. Plugin-dev's accuracy degrades silently as CC evolves. + +There is no automated way to detect what changed, assess relevance, or apply updates. Each sync is manual, error-prone, and requires cross-referencing multiple unreliable sources. + +## Solution + +An orchestrator skill (`update-from-upstream`) that runs a four-stage pipeline with three dedicated agents. Reliability comes from source triangulation and independent verification agents, not human checkpoints. + +## Pipeline + +``` +Stage 1: Discover → changelog-differ agent +Stage 2: Verify Plan → update-manifest-verifier agent +Stage 3: Apply → orchestrator (inline) +Stage 4: Verify Work → update-reviewer agent +Release: Commit, bump version, update compatibility log +``` + +Each stage produces a structured artifact consumed by the next. Stages 2 and 4 are verification gates run by agents with independent context from the agent that produced the work they're checking. + +## Stage 1: Discover + +**Agent:** `changelog-differ` + +**Inputs:** +- `docs/claude-code-compatibility.md` — reads `Last audited: Claude Code X.Y.Z` to determine the starting version +- CC changelog from `anthropics/claude-code` repo (fetched via WebFetch) +- CC system prompts CHANGELOG.md from `/Users/kyle/Code/meta-claude/claude-code-system-prompts` (local read) +- `claude-code-guide` built-in agent — cross-references changes against official documentation + +**Process:** +1. Parse last audited version from compatibility file +2. Fetch CC changelog, extract all entries since last audited version +3. Read system-prompts CHANGELOG.md for the same version range (more structured, includes token deltas and explicit NEW/REMOVED markers) +4. Dispatch `claude-code-guide` agent to cross-reference each change against official docs — catches things changelogs understate or omit +5. Classify each change by relevance to plugin-dev: + - **Affects plugin system** (new plugin.json fields, hook events, agent features, skill format changes) → must update + - **Affects tool behavior** (Bash, Edit, Grep changes) → may affect examples/references + - **Irrelevant** (IDE extensions, API headers, internal fixes) → skip + +**Three-source triangulation:** If something appears in only one source, it gets flagged as lower confidence. + +**Output:** Structured change manifest written to `.agent-history/upstream-changes.md`: + +```markdown +# Upstream Change Manifest +## CC Version Range: 2.1.87 - 2.1.92 +## Generated: 2026-03-29 + +### Must Update +- [ ] New hook event `ProjectInit` added (CC 2.1.89) + - Source: changelog, confirmed in system-prompts + - Affects: hook-development skill + - Details: Fires when Claude first enters a new project directory + +### May Update +- [ ] Read tool now supports .parquet files (CC 2.1.90) + - Source: changelog only (not yet in system-prompts) + - Affects: examples referencing file reading + +### No Action +- VSCode extension fix for status bar (CC 2.1.88) +- API header change for proxy support (CC 2.1.87) +``` + +## Stage 2: Verify Plan + +**Agent:** `update-manifest-verifier` + +This agent operates in a separate context from the differ. It independently: + +1. Re-reads the CC changelog entries for the version range and confirms each "Must Update" item actually exists and is categorized correctly +2. Scans the changelog for plugin-relevant keywords (`hook`, `plugin`, `agent`, `skill`, `command`, `MCP`, `LSP`, `tool`) that the differ might have classified as "No Action" +3. For each affected skill, reads the current SKILL.md to confirm the gap actually exists (maybe plugin-dev already covers it from a previous manual update) +4. Validates the "Affects" mapping — does the change belong to the identified skill, or a different one? + +**Output:** Annotated manifest with verification status: + +```markdown +### Verification Results +- ✓ `ProjectInit` hook event — confirmed in CC 2.1.89 changelog, + not present in hook-development/SKILL.md +- ✗ `.parquet` support — already mentioned in plugin-structure + examples, downgrade to No Action +- ! Missed: new `permissionMode` value `auto` added in CC 2.1.91, + affects agent-development skill +``` + +**On corrections:** The verifier amends the manifest directly. Stage 3 works from the verified version. No re-run of Stage 1 — the pipeline stays linear. + +## Stage 3: Apply + +**Actor:** The orchestrator skill itself (no dedicated agent — the manifest tells it exactly what to do). + +**Process:** For each "Must Update" item in the verified manifest: + +1. Read the target SKILL.md (or reference doc) +2. Determine the edit type: + - **Add** — new capability, event, field → add a new section or bullet in the appropriate place + - **Modify** — changed behavior → update existing description + - **Deprecate** — removed feature → mark as deprecated with the CC version it was removed +3. Apply the edit, following existing patterns in the file (heading levels, formatting conventions, example style) +4. If a change spans multiple skills, update all affected files + +**After all edits:** + +5. Update `docs/claude-code-compatibility.md`: + - Set `Last audited:` to the newest CC version in the range + - Append a row to the audit log table +6. Determine version bump based on scope: + - **Patch** (0.6.1 → 0.6.2): doc corrections, minor additions to existing sections + - **Minor** (0.6.1 → 0.7.0): new sections, new capabilities documented, structural changes +7. Bump version across plugin.json, marketplace.json, CLAUDE.md +8. Update CHANGELOG.md with the new version entry + +**No commit yet** — Stage 4 verifies first. + +## Stage 4: Verify Work + +**Agent:** `update-reviewer` + +**Input:** Verified manifest from Stage 2 + current state of all modified files. + +**Checks:** + +1. **Completeness** — Walk every "Must Update" item. Grep the target file, confirm new content exists. Flag anything missing. +2. **Accuracy** — Compare each update against source material (CC changelog entry + system-prompts detail). Does the doc accurately describe the feature? +3. **Consistency** — Run existing validation: + - `markdownlint` on modified .md files + - Version sync check across plugin.json, marketplace.json, CLAUDE.md + - CHANGELOG.md has an entry for the new version +4. **Regression** — Read modified SKILL.md files in full. Did edits break surrounding content? Wrong heading nesting, orphaned references, duplicated sections? +5. **Style** — Do new sections match tone and structure of existing content? Third-person descriptions, progressive disclosure pattern, trigger phrases in descriptions. + +**Output:** + +```markdown +### Review Results: PASS +- Completeness: 5/5 items applied ✓ +- Accuracy: all entries match source material ✓ +- Lint: clean ✓ +- Versions: synced at 0.6.2 ✓ +- Regressions: none found ✓ +- Style: new hook-development section matches existing pattern ✓ +``` + +**On failure:** The orchestrator applies the reviewer's specific corrections and re-runs Stage 4 (max one retry, then stops and reports what couldn't be resolved). + +**On pass:** The orchestrator commits and pushes. + +## Component Inventory + +### New Skill (1) + +| Component | Path | +|---|---| +| `update-from-upstream` | `plugins/plugin-dev/skills/update-from-upstream/SKILL.md` | + +### New Agents (3) + +| Agent | Stage | Purpose | +|---|---|---| +| `changelog-differ` | 1 | Fetches and triangulates changes across three sources | +| `update-manifest-verifier` | 2 | Independently validates the change manifest | +| `update-reviewer` | 4 | Verifies applied changes against manifest | + +### New Files (1) + +| File | Purpose | +|---|---| +| `docs/claude-code-compatibility.md` | Version tracking with audit log table | + +### Modified Files (existing) + +| File | Change | +|---|---| +| `plugin.json` | Register new skill and agents | +| `marketplace.json` | Version bump | +| `CLAUDE.md` | Reference to new skill | +| `plugin-dev-guide.md` | Add `update-from-upstream` to routing table | + +### External Dependencies + +| Dependency | Type | Used In | +|---|---|---| +| `claude-code-guide` agent | Built-in subagent | Stage 1 (doc cross-referencing) | +| `markdownlint` | CLI tool | Stage 4 (lint check) | +| `claude-code-system-prompts` | Local repo | Stage 1 (structured changelog) | +| `anthropics/claude-code` | GitHub repo | Stage 1 (upstream changelog) | + +## Design Decisions + +**Why no shell scripts:** The ambiguous parts of this workflow (interpreting changelog entries, classifying relevance, deciding where content fits) are semantic, not mechanical. LLMs handle this better than regex parsers. The changelog format is loose enough that a script would miss context. + +**Why no human gates:** Reliability comes from three mechanisms: source triangulation (three independent sources in Stage 1), independent verification (Stages 2 and 4 use fresh agent context), and existing tooling (markdownlint, version sync checks). This is sufficient for doc updates where the worst case is a slightly inaccurate description that gets caught in the next audit. + +**Why the orchestrator applies edits (not an agent):** Stage 3 has the least ambiguity — the manifest says exactly what to change and where. The creative judgment is limited to "where in this file does new content fit" and "match existing style." This doesn't need the overhead of a separate agent context. + +**Why patch-default versioning:** Most upstream syncs will add a few bullets to existing sections. Minor bumps are reserved for structural additions (new sections, new skills). From 90be1a5e5ea272590aa49118965320bfc86c614a Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 14:09:26 +1300 Subject: [PATCH 16/33] docs: address spec review feedback for update-from-upstream - Specify exact CC changelog URL with fetch validation - Use full paths in modified files table - Remove plugin.json registration (auto-discovery handles it) - Add conventional commit format for release commits - Add bootstrap behavior for first run - Clarify Stage 4 retry mechanics - Add SKILL.md frontmatter sketch with trigger phrases - Add agent tool allowlists - Add fallback column to external dependencies - Update CLAUDE.md component count note - Fix plugin-dev-guide routing table (use SKILL.md listing, not agent routing) --- .../2026-03-29-update-from-upstream-design.md | 78 ++++++++++++++++--- 1 file changed, 66 insertions(+), 12 deletions(-) diff --git a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md index ee6fc7a..c8cc522 100644 --- a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md +++ b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md @@ -28,9 +28,9 @@ Each stage produces a structured artifact consumed by the next. Stages 2 and 4 a **Inputs:** - `docs/claude-code-compatibility.md` — reads `Last audited: Claude Code X.Y.Z` to determine the starting version -- CC changelog from `anthropics/claude-code` repo (fetched via WebFetch) +- CC changelog fetched via WebFetch from `https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md`. If the fetched content does not contain the expected version range, Stage 1 fails explicitly rather than proceeding with partial data. - CC system prompts CHANGELOG.md from `/Users/kyle/Code/meta-claude/claude-code-system-prompts` (local read) -- `claude-code-guide` built-in agent — cross-references changes against official documentation +- `claude-code-guide` built-in subagent type — cross-references changes against official documentation. This agent has access to WebFetch, WebSearch, Glob, Grep, and Read. If this subagent type is unavailable at runtime, Stage 1 degrades gracefully to two-source triangulation (changelog + system-prompts) with keyword scanning from Stage 2 as the compensating check. **Process:** 1. Parse last audited version from compatibility file @@ -152,6 +152,35 @@ This agent operates in a separate context from the differ. It independently: **On pass:** The orchestrator commits and pushes. +**Stage 4 retry mechanics:** When the reviewer reports failures, its output includes specific corrections (e.g., "missing section X in file Y", "version mismatch in Z"). The orchestrator applies these corrections as targeted edits, then re-dispatches the update-reviewer agent for a full re-check. If the second pass still fails, the orchestrator stops and reports the unresolved items without committing. + +## Bootstrap Behavior + +On first run, `docs/claude-code-compatibility.md` won't exist. The skill creates it with: + +```markdown +# Claude Code Compatibility + +Last audited: Claude Code 2.1.86 (2026-03-28) +Plugin-dev version: 0.6.1 + +## Audit Log +| plugin-dev | CC version range | Date | Notes | +|---|---|---|---| +| v0.6.1 | ≤2.1.86 | 2026-03-28 | Initial compatibility baseline | +``` + +The initial "Last audited" version is set to the CC version current at the time of implementation. All prior plugin-dev versions are treated as a single baseline row. + +## Release Commit Format + +Follows conventional commits per project standards: + +- **Patch bump:** `docs: sync plugin-dev with Claude Code vX.Y.Z-vA.B.C` +- **Minor bump:** `feat: sync plugin-dev with Claude Code vX.Y.Z-vA.B.C` + +The commit body includes a summary of what changed (generated from the manifest). + ## Component Inventory ### New Skill (1) @@ -178,19 +207,20 @@ This agent operates in a separate context from the differ. It independently: | File | Change | |---|---| -| `plugin.json` | Register new skill and agents | -| `marketplace.json` | Version bump | -| `CLAUDE.md` | Reference to new skill | -| `plugin-dev-guide.md` | Add `update-from-upstream` to routing table | +| `.claude-plugin/marketplace.json` | Version bump | +| `CLAUDE.md` (root) | Version bump, update component counts (11 skills, 7 agents), reference to new skill | +| `plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md` | Add `update-from-upstream` to available skills listing | + +Note: `plugins/plugin-dev/.claude-plugin/plugin.json` and agent/skill directories use auto-discovery — no registration needed. The plugin-dev-guide *agent* routing table is not modified because `update-from-upstream` is a maintenance skill, not a user-facing plugin development question. ### External Dependencies -| Dependency | Type | Used In | -|---|---|---| -| `claude-code-guide` agent | Built-in subagent | Stage 1 (doc cross-referencing) | -| `markdownlint` | CLI tool | Stage 4 (lint check) | -| `claude-code-system-prompts` | Local repo | Stage 1 (structured changelog) | -| `anthropics/claude-code` | GitHub repo | Stage 1 (upstream changelog) | +| Dependency | Type | Used In | Fallback | +|---|---|---|---| +| `claude-code-guide` subagent | Built-in subagent type | Stage 1 (doc cross-referencing) | Degrade to two-source triangulation | +| `markdownlint` | CLI tool | Stage 4 (lint check) | Skip lint check, warn in output | +| `claude-code-system-prompts` | Local repo at `/Users/kyle/Code/meta-claude/claude-code-system-prompts` | Stage 1 (structured changelog) | Degrade to single-source + claude-code-guide | +| `anthropics/claude-code` CHANGELOG.md | Remote file via `https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md` | Stage 1 (upstream changelog) | Fail — this is the primary source | ## Design Decisions @@ -201,3 +231,27 @@ This agent operates in a separate context from the differ. It independently: **Why the orchestrator applies edits (not an agent):** Stage 3 has the least ambiguity — the manifest says exactly what to change and where. The creative judgment is limited to "where in this file does new content fit" and "match existing style." This doesn't need the overhead of a separate agent context. **Why patch-default versioning:** Most upstream syncs will add a few bullets to existing sections. Minor bumps are reserved for structural additions (new sections, new skills). + +## SKILL.md Frontmatter (sketch) + +```yaml +--- +name: update-from-upstream +version: 0.1.0 +description: >- + This skill should be used when the user asks to "sync with upstream", + "update from Claude Code", "check for Claude Code changes", + "update plugin-dev docs", "sync with latest CC release", + "what changed in Claude Code", "audit against upstream", + or needs to bring plugin-dev documentation current with recent + Claude Code releases. +--- +``` + +## Agent Tool Allowlists + +| Agent | Tools | Why | +|---|---|---| +| `changelog-differ` | Read, Grep, Glob, WebFetch, Agent (for claude-code-guide dispatch) | Needs to fetch remote changelog, read local files, dispatch subagent | +| `update-manifest-verifier` | Read, Grep, Glob, WebFetch, Edit | Needs to read changelogs and skill files, amend the manifest | +| `update-reviewer` | Read, Grep, Glob, Bash (for markdownlint) | Needs to read modified files, run lint, verify content | From c476d2f6d4bf4cb6fc3616ad8e5acc8e76a696df Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 14:10:44 +1300 Subject: [PATCH 17/33] docs: clarify Stage 2 verifier fetches its own changelog copy --- .../specs/2026-03-29-update-from-upstream-design.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md index c8cc522..0e69e39 100644 --- a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md +++ b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md @@ -71,9 +71,9 @@ Each stage produces a structured artifact consumed by the next. Stages 2 and 4 a **Agent:** `update-manifest-verifier` -This agent operates in a separate context from the differ. It independently: +This agent operates in a separate context from the differ. It independently fetches its own copy of the CC changelog (fresh WebFetch, not reading from Stage 1's output) to ensure true independence: -1. Re-reads the CC changelog entries for the version range and confirms each "Must Update" item actually exists and is categorized correctly +1. Fetches the CC changelog and re-reads entries for the version range, confirming each "Must Update" item actually exists and is categorized correctly 2. Scans the changelog for plugin-relevant keywords (`hook`, `plugin`, `agent`, `skill`, `command`, `MCP`, `LSP`, `tool`) that the differ might have classified as "No Action" 3. For each affected skill, reads the current SKILL.md to confirm the gap actually exists (maybe plugin-dev already covers it from a previous manual update) 4. Validates the "Affects" mapping — does the change belong to the identified skill, or a different one? From c6ff47bea4a2c6c7d361963f2efa2246fcf87628 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 14:18:24 +1300 Subject: [PATCH 18/33] feat: add update-from-upstream skill and pipeline agents, release v0.7.0 Four-stage pipeline for syncing plugin-dev docs with Claude Code upstream releases. Uses source triangulation (CC changelog, system-prompts repo, claude-code-guide agent) and independent verification agents to ensure accuracy without human gates. --- .claude-plugin/marketplace.json | 6 +- CHANGELOG.md | 10 + CLAUDE.md | 12 +- docs/claude-code-compatibility.md | 10 + .../2026-03-29-update-from-upstream-design.md | 2 +- plugins/plugin-dev/.claude-plugin/plugin.json | 4 +- plugins/plugin-dev/agents/changelog-differ.md | 111 +++++++++++ .../agents/update-manifest-verifier.md | 106 ++++++++++ plugins/plugin-dev/agents/update-reviewer.md | 125 ++++++++++++ .../skills/plugin-dev-guide/SKILL.md | 19 +- .../skills/update-from-upstream/SKILL.md | 188 ++++++++++++++++++ 11 files changed, 580 insertions(+), 13 deletions(-) create mode 100644 docs/claude-code-compatibility.md create mode 100644 plugins/plugin-dev/agents/changelog-differ.md create mode 100644 plugins/plugin-dev/agents/update-manifest-verifier.md create mode 100644 plugins/plugin-dev/agents/update-reviewer.md create mode 100644 plugins/plugin-dev/skills/update-from-upstream/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 67ed1bd..75cf7e5 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.6.1" + "version": "0.7.0" }, "plugins": [ { "name": "plugin-dev", - "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.6.1", + "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", + "version": "0.7.0", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index be53df0..ee53858 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.7.0] - 2026-03-29 + +### Added + +- **update-from-upstream skill**: Four-stage pipeline for syncing plugin-dev documentation with Claude Code upstream releases, using source triangulation and independent verification agents +- **changelog-differ agent**: Stage 1 agent that fetches CC changelog, reads system-prompts repo, and dispatches claude-code-guide for three-source triangulation +- **update-manifest-verifier agent**: Stage 2 agent that independently re-fetches sources and validates the change manifest before edits are applied +- **update-reviewer agent**: Stage 4 agent that verifies completeness, accuracy, lint, version sync, regressions, and style of applied updates +- **claude-code-compatibility.md**: Version tracking file with audit log table recording which CC version plugin-dev is built against + ## [0.6.1] - 2026-03-28 ### Fixed diff --git a/CLAUDE.md b/CLAUDE.md index 3a4bbdf..17b1bc5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,9 +4,9 @@ Guidance for Claude Code working in this repository. ## What This Is -Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 10 skills, 4 agents, 3 slash commands. +Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 11 skills, 7 agents, 3 slash commands. -**Version**: v0.6.1 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.7.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) @@ -90,3 +90,11 @@ uvx yamllint .github/workflows/ - **plugin-validator**: Validates plugin structure and manifests - **skill-reviewer**: Reviews skill quality and triggering - **agent-creator**: Generates agents from descriptions + +## Upstream Sync + +- **update-from-upstream**: Skill that syncs plugin-dev docs with Claude Code releases +- **changelog-differ**: Discovers upstream changes (Stage 1) +- **update-manifest-verifier**: Validates change manifest (Stage 2) +- **update-reviewer**: Verifies applied updates (Stage 4) +- Compatibility tracking: [docs/claude-code-compatibility.md](docs/claude-code-compatibility.md) diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md new file mode 100644 index 0000000..d6b16c6 --- /dev/null +++ b/docs/claude-code-compatibility.md @@ -0,0 +1,10 @@ +# Claude Code Compatibility + +Last audited: Claude Code 2.1.86 (2026-03-28) +Plugin-dev version: 0.6.1 + +## Audit Log + +| plugin-dev | CC version range | Date | Notes | +|---|---|---|---| +| v0.6.1 | ≤2.1.86 | 2026-03-28 | Initial compatibility baseline | diff --git a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md index 0e69e39..1920a2a 100644 --- a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md +++ b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md @@ -211,7 +211,7 @@ The commit body includes a summary of what changed (generated from the manifest) | `CLAUDE.md` (root) | Version bump, update component counts (11 skills, 7 agents), reference to new skill | | `plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md` | Add `update-from-upstream` to available skills listing | -Note: `plugins/plugin-dev/.claude-plugin/plugin.json` and agent/skill directories use auto-discovery — no registration needed. The plugin-dev-guide *agent* routing table is not modified because `update-from-upstream` is a maintenance skill, not a user-facing plugin development question. +Note: `plugins/plugin-dev/.claude-plugin/plugin.json` and agent/skill directories use auto-discovery — no registration needed. The plugin-dev-guide _agent_ routing table is not modified because `update-from-upstream` is a maintenance skill, not a user-facing plugin development question. ### External Dependencies diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 2141399..332cf5f 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "plugin-dev", - "version": "0.6.1", - "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 10 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", + "version": "0.7.0", + "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/plugins/plugin-dev/agents/changelog-differ.md b/plugins/plugin-dev/agents/changelog-differ.md new file mode 100644 index 0000000..7c5c196 --- /dev/null +++ b/plugins/plugin-dev/agents/changelog-differ.md @@ -0,0 +1,111 @@ +--- +name: changelog-differ +description: | + Use this agent to discover what changed in Claude Code since the last plugin-dev audit. Fetches the upstream changelog, cross-references with system-prompts repo and official docs, and produces a structured change manifest. This agent is dispatched by the update-from-upstream skill as Stage 1 of the update pipeline. Examples: + + + Context: Orchestrator skill needs to discover upstream changes + user: "Find all Claude Code changes since our last audit at version 2.1.86" + assistant: "I'll use the changelog-differ agent to fetch and triangulate upstream changes." + + Stage 1 of the update-from-upstream pipeline. Agent fetches changelog, reads system-prompts, dispatches claude-code-guide, and classifies changes. + + + +model: inherit +color: yellow +tools: Read, Grep, Glob, WebFetch, Agent +--- + +You are a changelog analysis agent. Your job is to discover what changed in Claude Code since the last plugin-dev audit and produce a structured change manifest. + +## Inputs + +You will be given: +- The last audited Claude Code version (from `docs/claude-code-compatibility.md`) +- Access to the upstream changelog and local system-prompts repo + +## Process + +### Step 1: Fetch the CC Changelog + +Fetch the Claude Code changelog: +``` +WebFetch: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md +``` + +Extract all version entries **after** the last audited version. If the fetched content does not contain the expected version range, **stop and report the error** rather than proceeding with partial data. + +### Step 2: Read System Prompts Changelog + +Read the local system-prompts CHANGELOG.md: +``` +Read: /Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md +``` + +Extract entries for the same version range. This source is more structured (includes NEW/REMOVED markers and token deltas). + +### Step 3: Cross-Reference with Official Docs + +Dispatch the `claude-code-guide` subagent type to cross-reference significant changes against official documentation. This catches features the changelogs understate or omit. + +If the `claude-code-guide` subagent type is unavailable, skip this step and note in the manifest that triangulation is degraded to two sources. + +### Step 4: Classify Changes + +For each change found, classify by relevance to plugin-dev: + +**Affects plugin system** (must update): +- New plugin.json fields or manifest changes +- New or modified hook events +- Agent feature changes (model, tools, permissions, teams) +- Skill format changes (frontmatter fields, loading behavior) +- Command changes +- MCP or LSP integration changes + +**Affects tool behavior** (may update): +- Changes to built-in tools (Bash, Edit, Read, Grep, Glob, Write, Agent) +- Changes that affect examples or reference docs + +**Irrelevant** (no action): +- IDE extension changes (VSCode, JetBrains) +- API headers, proxy support +- Internal performance fixes +- Bug fixes unrelated to plugin system + +**Confidence scoring:** If a change appears in only one source, flag it as lower confidence. Changes confirmed across multiple sources get higher confidence. + +## Output + +Write the manifest to `.agent-history/upstream-changes.md` in this format: + +```markdown +# Upstream Change Manifest +## CC Version Range: [start] - [end] +## Generated: [date] +## Sources: changelog [✓/✗], system-prompts [✓/✗], claude-code-guide [✓/✗/skipped] + +### Must Update +- [ ] [Description of change] (CC [version]) + - Source: [which sources confirmed this] + - Confidence: [high/medium/low] + - Affects: [skill-name] skill + - Details: [what the change does and why it matters for plugin-dev] + +### May Update +- [ ] [Description] (CC [version]) + - Source: [sources] + - Confidence: [level] + - Affects: [what it touches] + - Details: [description] + +### No Action +- [Brief description] (CC [version]) +``` + +## Constraints + +- Do not modify any plugin-dev files. Only write the manifest. +- Do not attempt to fix or update documentation. That is Stage 3's job. +- Be thorough — a missed change is worse than a false positive. +- Include the raw changelog text for each "Must Update" item so downstream agents can verify independently. diff --git a/plugins/plugin-dev/agents/update-manifest-verifier.md b/plugins/plugin-dev/agents/update-manifest-verifier.md new file mode 100644 index 0000000..0cf3247 --- /dev/null +++ b/plugins/plugin-dev/agents/update-manifest-verifier.md @@ -0,0 +1,106 @@ +--- +name: update-manifest-verifier +description: | + Use this agent to independently verify a change manifest produced by the changelog-differ agent. Re-fetches sources, checks for missed changes, and validates classifications. This agent is dispatched by the update-from-upstream skill as Stage 2 of the update pipeline. Examples: + + + Context: Orchestrator needs to verify the change manifest before applying updates + user: "Verify the upstream change manifest at .agent-history/upstream-changes.md" + assistant: "I'll use the update-manifest-verifier agent to independently validate the manifest." + + Stage 2 of the update-from-upstream pipeline. Agent re-fetches changelog, scans for missed items, and validates classifications. + + + +model: inherit +color: green +tools: Read, Grep, Glob, WebFetch, Edit +--- + +You are an independent verification agent. Your job is to validate a change manifest that was produced by a different agent. You must not trust the manifest — verify everything from primary sources. + +## Inputs + +You will be given the path to the change manifest (typically `.agent-history/upstream-changes.md`). + +## Process + +### Step 1: Read the Manifest + +Read the manifest and note: +- The CC version range +- Every item in "Must Update", "May Update", and "No Action" +- The sources each item claims to come from + +### Step 2: Independently Fetch Sources + +Fetch your own copy of the CC changelog (do NOT rely on Stage 1's fetch): +``` +WebFetch: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md +``` + +Read the local system-prompts CHANGELOG: +``` +Read: /Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md +``` + +### Step 3: Verify Each "Must Update" Item + +For each item: +1. Confirm the change actually exists in the changelog at the stated version +2. Confirm the classification is correct (does it actually affect the plugin system?) +3. Confirm the "Affects" skill mapping — read the target SKILL.md at `${CLAUDE_PLUGIN_ROOT}/skills//SKILL.md` to verify this is the right skill +4. Check whether the gap actually exists (maybe plugin-dev already documents this feature) + +### Step 4: Scan for Missed Changes + +Scan the changelog entries for the version range looking for plugin-relevant keywords that may have been classified as "No Action": +- `hook`, `plugin`, `agent`, `skill`, `command` +- `MCP`, `LSP`, `mcp`, `lsp` +- `tool`, `permission`, `subagent` +- `frontmatter`, `manifest`, `plugin.json` +- `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop` + +For each potential miss, read the full changelog entry and determine if it should be promoted. + +### Step 5: Validate "May Update" Items + +For each "May Update" item, determine if it should be promoted to "Must Update" or demoted to "No Action" based on reading the affected files. + +## Output + +Append a verification section to the manifest using Edit: + +```markdown +## Stage 2: Verification Results +### Verified: [date] + +#### Must Update Verification +- ✓ [item] — confirmed in [sources], gap exists in [skill]/SKILL.md +- ✗ [item] — [reason for rejection, e.g., "already documented at line X"] +- ! [item] — reclassified: [reason] + +#### Missed Items (promoted from No Action) +- ! [description] (CC [version]) — missed because [reason] + - Affects: [skill-name] + - Details: [description] + +#### May Update Resolution +- ↑ [item] — promoted to Must Update: [reason] +- ↓ [item] — demoted to No Action: [reason] +- = [item] — kept as May Update: [reason] + +#### Summary +- Must Update: [count] items ([count] confirmed, [count] rejected, [count] added) +- May Update: [count] items remaining +- Confidence: [overall assessment] +``` + +After appending the verification results, also update the "Must Update" and "No Action" sections in the manifest body to reflect your corrections. The corrected manifest is what Stage 3 will work from. + +## Constraints + +- Do not modify any plugin-dev files other than the manifest. +- Do not apply documentation updates. That is Stage 3's job. +- When in doubt, promote an item to "Must Update" rather than demoting it. False positives are cheaper than false negatives. +- If you find significant issues (>30% of items rejected or >3 missed items), note this prominently so the orchestrator can assess whether Stage 1 needs improvement. diff --git a/plugins/plugin-dev/agents/update-reviewer.md b/plugins/plugin-dev/agents/update-reviewer.md new file mode 100644 index 0000000..d6c6ea4 --- /dev/null +++ b/plugins/plugin-dev/agents/update-reviewer.md @@ -0,0 +1,125 @@ +--- +name: update-reviewer +description: | + Use this agent to verify that documentation updates were applied correctly after the update-from-upstream skill's Stage 3 (Apply). Checks completeness, accuracy, lint, version sync, regressions, and style. This agent is dispatched by the update-from-upstream skill as Stage 4 of the update pipeline. Examples: + + + Context: Orchestrator has applied doc updates and needs verification before committing + user: "Review the applied updates against the manifest at .agent-history/upstream-changes.md" + assistant: "I'll use the update-reviewer agent to verify all changes were applied correctly." + + Stage 4 of the update-from-upstream pipeline. Agent checks every manifest item was applied, runs lint, verifies versions. + + + +model: inherit +color: red +tools: Read, Grep, Glob, Bash +--- + +You are an independent review agent. Your job is to verify that documentation updates were applied correctly. You did not write these updates — your job is to find problems. + +## Inputs + +You will be given: +- The verified change manifest (typically `.agent-history/upstream-changes.md`, including Stage 2 verification results) +- The current state of all modified files in the plugin-dev repository + +## Checks + +### 1. Completeness + +Walk every "Must Update" item in the manifest (using the Stage 2-verified version). For each: +- Grep the target SKILL.md or reference file for the new content +- Confirm the content exists and is in the right location +- Flag anything missing + +### 2. Accuracy + +For each update applied: +- Compare what was written against the source material (the raw changelog text included in the manifest) +- Does the documentation accurately describe the feature? +- Are version numbers correct? +- Are any details lost in translation or misrepresented? + +### 3. Consistency + +Run validation checks: + +```bash +# Lint modified markdown files +markdownlint '**/*.md' --ignore node_modules + +# Version sync check +rg '"version"' plugins/plugin-dev/.claude-plugin/plugin.json .claude-plugin/marketplace.json +rg 'Version.*v[0-9]' CLAUDE.md +``` + +Verify: +- All version numbers match across plugin.json, marketplace.json, CLAUDE.md +- CHANGELOG.md has an entry for the new version +- The compatibility file's "Last audited" version matches the manifest's version range end + +### 4. Regression + +Read each modified SKILL.md in full. Check for: +- Broken heading hierarchy (skipped levels, wrong nesting) +- Orphaned references (links to files or sections that don't exist) +- Duplicated sections or content +- Content that was accidentally deleted or overwritten +- Formatting inconsistencies introduced by the edits + +### 5. Style + +Verify new content matches existing conventions: +- Third-person descriptions ("This event fires when..." not "You can use this event to...") +- Progressive disclosure pattern (core info in SKILL.md, details in references/) +- Consistent formatting (code blocks, tables, bullet styles) +- Trigger phrases updated in skill description if a significant new feature was added + +## Output + +```markdown +## Stage 4: Review Results + +### Verdict: [PASS / FAIL] + +#### Completeness: [X/Y items applied] +- ✓ [item] — found in [file]:[location] +- ✗ [item] — MISSING from [expected file] + - Fix: [specific instruction for what to add and where] + +#### Accuracy: [assessment] +- ✓ [item] — matches source material +- ✗ [item] — inaccuracy: [description of what's wrong] + - Fix: [specific correction] + +#### Consistency: [assessment] +- Lint: [clean / N issues] + - [issue details if any] +- Versions: [synced at X.Y.Z / MISMATCH] + - [mismatch details if any] +- CHANGELOG: [present / MISSING] +- Compatibility file: [correct / MISMATCH] + +#### Regressions: [none found / N issues] +- [file]: [issue description] + - Fix: [specific instruction] + +#### Style: [assessment] +- [file]: [issue or ✓] + +### Summary +- Total checks: [count] +- Passed: [count] +- Failed: [count] +- Fixes required: [list of specific fixes needed] +``` + +## Constraints + +- Do not fix problems yourself. Report them with specific fix instructions. +- Be thorough — a missed regression that gets committed is expensive. +- Run markdownlint even if you think the files look fine. Catch what humans miss. +- If lint fails, include the specific errors and file locations. +- On PASS, the orchestrator will commit. On FAIL, the orchestrator applies your fixes and re-dispatches you for a second check (max one retry). diff --git a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md index 21fbcdb..346fc97 100644 --- a/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md @@ -25,10 +25,19 @@ When the agent reports back, follow its recommendation: ## Available Agents -| Agent | Purpose | -| -------------------- | ------------------------------------------ | -| **plugin-validator** | Validates plugin structure and manifests | -| **skill-reviewer** | Reviews skill quality and triggering | -| **agent-creator** | Generates new agents from descriptions | +| Agent | Purpose | +| ------------------------------ | ---------------------------------------------- | +| **plugin-validator** | Validates plugin structure and manifests | +| **skill-reviewer** | Reviews skill quality and triggering | +| **agent-creator** | Generates new agents from descriptions | +| **changelog-differ** | Discovers upstream Claude Code changes (Stage 1)| +| **update-manifest-verifier** | Validates change manifest (Stage 2) | +| **update-reviewer** | Verifies applied documentation updates (Stage 4)| + +## Available Skills (Maintenance) + +| Skill | Purpose | +| -------------------------- | ---------------------------------------------------- | +| **update-from-upstream** | Sync plugin-dev docs with Claude Code upstream releases | $ARGUMENTS diff --git a/plugins/plugin-dev/skills/update-from-upstream/SKILL.md b/plugins/plugin-dev/skills/update-from-upstream/SKILL.md new file mode 100644 index 0000000..48b4b1d --- /dev/null +++ b/plugins/plugin-dev/skills/update-from-upstream/SKILL.md @@ -0,0 +1,188 @@ +--- +name: update-from-upstream +version: 0.1.0 +description: >- + This skill should be used when the user asks to "sync with upstream", + "update from Claude Code", "check for Claude Code changes", + "update plugin-dev docs", "sync with latest CC release", + "what changed in Claude Code", "audit against upstream", + "bring docs up to date", "check upstream changelog", + "sync plugin-dev with Claude Code", "update compatibility", + or needs to bring plugin-dev documentation current with recent + Claude Code releases. +--- + +# Update From Upstream + +Sync plugin-dev documentation with Claude Code upstream changes using a four-stage pipeline with independent verification. + +## Prerequisites + +Before running this skill, ensure: +- The local clone of `claude-code-system-prompts` is up to date: `cd /Users/kyle/Code/meta-claude/claude-code-system-prompts && git pull` +- `docs/claude-code-compatibility.md` exists (the skill creates it on first run if missing) + +## Pipeline Overview + +``` +Stage 1: Discover → changelog-differ agent +Stage 2: Verify Plan → update-manifest-verifier agent +Stage 3: Apply → orchestrator (you, inline) +Stage 4: Verify Work → update-reviewer agent +Release: Commit, bump version, update compatibility log +``` + +Each stage produces a structured artifact consumed by the next. Stages 2 and 4 are verification gates run by agents with independent context. + +## Stage 1: Discover + +Dispatch the `changelog-differ` agent with this prompt: + +``` +Find all Claude Code changes since our last audit. Read the last audited +version from docs/claude-code-compatibility.md, then: + +1. Fetch the CC changelog from https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md +2. Read the system-prompts CHANGELOG at /Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md +3. Cross-reference with the claude-code-guide agent for official doc coverage +4. Classify all changes and write the manifest to .agent-history/upstream-changes.md + +Follow your agent instructions exactly. +``` + +**Wait for the agent to complete before proceeding.** + +If the agent reports that the CC changelog could not be fetched or the version range is empty (already up to date), stop the pipeline and report to the user. + +## Stage 2: Verify Plan + +Dispatch the `update-manifest-verifier` agent with this prompt: + +``` +Independently verify the change manifest at .agent-history/upstream-changes.md. + +Re-fetch the CC changelog yourself (do not trust Stage 1's data). Check every +item for correctness, scan for missed changes, and validate skill mappings by +reading the actual SKILL.md files. + +Follow your agent instructions exactly. +``` + +**Wait for the agent to complete before proceeding.** + +Read the updated manifest after Stage 2 completes. The verified manifest is your source of truth for Stage 3. + +## Stage 3: Apply + +You execute this stage directly. Work through the verified manifest: + +### For each "Must Update" item + +1. Read the target SKILL.md (or reference doc) at `plugins/plugin-dev/skills//SKILL.md` +2. Determine the edit type: + - **Add** — new capability, event, field: add a new section or bullet in the appropriate place + - **Modify** — changed behavior: update existing description + - **Deprecate** — removed feature: mark as deprecated with the CC version it was removed +3. Apply the edit. Match the existing patterns in the file: + - Same heading levels as sibling sections + - Same formatting (code blocks, tables, bullet styles) + - Same tone (third-person, imperative) +4. If a change spans multiple skills, update all affected files + +### For each "May Update" item + +Use judgment. If the change materially affects examples or references that users rely on, update them. Otherwise skip. + +### After all edits, update metadata + +**Compatibility file** (`docs/claude-code-compatibility.md`): +- Set `Last audited:` to the newest CC version in the range +- Update `Plugin-dev version:` to the new version +- Append a row to the audit log table + +**Version bump** — determine scope: +- **Patch** (e.g., 0.7.1 → 0.7.2): doc corrections, minor additions to existing sections +- **Minor** (e.g., 0.7.1 → 0.8.0): new sections, new capabilities documented, structural changes + +**Bump version in all three locations:** +- `plugins/plugin-dev/.claude-plugin/plugin.json` — `"version"` field +- `.claude-plugin/marketplace.json` — both `metadata.version` and the plugin entry `version` +- `CLAUDE.md` (root) — version line, component counts if changed + +**Update CHANGELOG.md:** +- Add a new version entry following Keep a Changelog format +- Organize changes into Added/Changed/Fixed sections +- Reference the CC version range in the entry + +**Do not commit yet** — Stage 4 verifies first. + +## Stage 4: Verify Work + +Dispatch the `update-reviewer` agent with this prompt: + +``` +Review the applied documentation updates against the verified manifest at +.agent-history/upstream-changes.md. + +Check completeness, accuracy, lint (run markdownlint), version sync, regressions, +and style. Report PASS or FAIL with specific fix instructions. + +Follow your agent instructions exactly. +``` + +**Wait for the agent to complete.** + +### On PASS + +Commit and push: + +```bash +# Stage files selectively +git add -u + +# Commit with conventional format +# For patch bumps: +git commit -m "docs: sync plugin-dev with Claude Code vX.Y.Z-vA.B.C" +# For minor bumps: +git commit -m "feat: sync plugin-dev with Claude Code vX.Y.Z-vA.B.C" + +git push +``` + +### On FAIL + +1. Read the reviewer's specific fix instructions +2. Apply each fix as a targeted edit +3. Re-dispatch the `update-reviewer` agent for a second check +4. If the second check still fails, **stop and report** the unresolved items to the user. Do not commit broken changes. + +## First Run Bootstrap + +If `docs/claude-code-compatibility.md` does not exist, create it before Stage 1: + +```markdown +# Claude Code Compatibility + +Last audited: Claude Code 2.1.86 (2026-03-28) +Plugin-dev version: 0.6.1 + +## Audit Log + +| plugin-dev | CC version range | Date | Notes | +|---|---|---|---| +| v0.6.1 | ≤2.1.86 | 2026-03-28 | Initial compatibility baseline | +``` + +Then proceed with Stage 1 as normal. + +## Error Handling + +| Condition | Action | +|---|---| +| CC changelog fetch fails | Stop pipeline, report to user | +| No new versions since last audit | Stop pipeline, report "already up to date" | +| `claude-code-guide` agent unavailable | Continue with two-source triangulation, note degraded confidence | +| System-prompts repo not found | Continue with CC changelog only, note degraded confidence | +| `markdownlint` not installed | Skip lint check in Stage 4, warn in output | +| Stage 4 fails twice | Stop, report unresolved items, do not commit | +| Manifest verifier finds >30% rejections | Note prominently in output, proceed with corrected manifest | From e363a38345aa1146c92eeed30ed47a4e4a0cc6e9 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 14:22:49 +1300 Subject: [PATCH 19/33] fix: correct last audited CC version to 2.1.84 The last actual upstream audit was v0.5.0 against CC 2.1.83-84. Versions 0.6.0 and 0.6.1 were internal changes, not upstream syncs. --- docs/claude-code-compatibility.md | 6 +++--- plugins/plugin-dev/skills/update-from-upstream/SKILL.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md index d6b16c6..7af9b6c 100644 --- a/docs/claude-code-compatibility.md +++ b/docs/claude-code-compatibility.md @@ -1,10 +1,10 @@ # Claude Code Compatibility -Last audited: Claude Code 2.1.86 (2026-03-28) -Plugin-dev version: 0.6.1 +Last audited: Claude Code 2.1.84 (2026-03-27) +Plugin-dev version: 0.7.0 ## Audit Log | plugin-dev | CC version range | Date | Notes | |---|---|---|---| -| v0.6.1 | ≤2.1.86 | 2026-03-28 | Initial compatibility baseline | +| v0.5.0 | ≤2.1.84 | 2026-03-27 | Initial compatibility baseline (initialPrompt, CwdChanged, FileChanged, userConfig, paths) | diff --git a/plugins/plugin-dev/skills/update-from-upstream/SKILL.md b/plugins/plugin-dev/skills/update-from-upstream/SKILL.md index 48b4b1d..7af5646 100644 --- a/plugins/plugin-dev/skills/update-from-upstream/SKILL.md +++ b/plugins/plugin-dev/skills/update-from-upstream/SKILL.md @@ -163,14 +163,14 @@ If `docs/claude-code-compatibility.md` does not exist, create it before Stage 1: ```markdown # Claude Code Compatibility -Last audited: Claude Code 2.1.86 (2026-03-28) -Plugin-dev version: 0.6.1 +Last audited: Claude Code 2.1.84 (2026-03-27) +Plugin-dev version: 0.7.0 ## Audit Log | plugin-dev | CC version range | Date | Notes | |---|---|---|---| -| v0.6.1 | ≤2.1.86 | 2026-03-28 | Initial compatibility baseline | +| v0.5.0 | ≤2.1.84 | 2026-03-27 | Initial compatibility baseline | ``` Then proceed with Stage 1 as normal. From 073dfd27b83bbd7e7b45be9c0caa67afe9e44eeb Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 14:33:14 +1300 Subject: [PATCH 20/33] fix: add Write and Bash tools to changelog-differ agent Agent couldn't write the manifest file because Write wasn't in its tool allowlist and .agent-history/ may not exist yet. --- .../superpowers/specs/2026-03-29-update-from-upstream-design.md | 2 +- plugins/plugin-dev/agents/changelog-differ.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md index 1920a2a..39cc35f 100644 --- a/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md +++ b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md @@ -252,6 +252,6 @@ description: >- | Agent | Tools | Why | |---|---|---| -| `changelog-differ` | Read, Grep, Glob, WebFetch, Agent (for claude-code-guide dispatch) | Needs to fetch remote changelog, read local files, dispatch subagent | +| `changelog-differ` | Read, Write, Grep, Glob, WebFetch, Agent, Bash | Needs to fetch remote changelog, read local files, dispatch subagent, write manifest, create directories | | `update-manifest-verifier` | Read, Grep, Glob, WebFetch, Edit | Needs to read changelogs and skill files, amend the manifest | | `update-reviewer` | Read, Grep, Glob, Bash (for markdownlint) | Needs to read modified files, run lint, verify content | diff --git a/plugins/plugin-dev/agents/changelog-differ.md b/plugins/plugin-dev/agents/changelog-differ.md index 7c5c196..07851d0 100644 --- a/plugins/plugin-dev/agents/changelog-differ.md +++ b/plugins/plugin-dev/agents/changelog-differ.md @@ -14,7 +14,7 @@ description: | model: inherit color: yellow -tools: Read, Grep, Glob, WebFetch, Agent +tools: Read, Write, Grep, Glob, WebFetch, Agent, Bash --- You are a changelog analysis agent. Your job is to discover what changed in Claude Code since the last plugin-dev audit and produce a structured change manifest. From b47c55e5ed4bc29a842fd5f60e85baa1a4642e79 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 14:47:09 +1300 Subject: [PATCH 21/33] feat: sync plugin-dev with Claude Code v2.1.85-v2.1.86 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Upstream sync via update-from-upstream pipeline (4-stage verified). Added: - hook-development: conditional `if` field, AskUserQuestion via updatedInput - skill-development: 250-char description cap, alphabetical /skills sorting - plugin-structure: org plugin blocking, Permission denied fix - mcp-integration: CLAUDE_CODE_MCP_SERVER_NAME/URL env vars - agent-development: prompt change, fork naming, Production Reads - marketplace-structure: org plugin blocking Fixed: - event-schemas: event count 22 → 24 - skill-development: noted resolved paths: frontmatter bug Bumps plugin-dev to v0.8.0. --- .claude-plugin/marketplace.json | 4 +-- CHANGELOG.md | 21 +++++++++++++++ CLAUDE.md | 2 +- docs/claude-code-compatibility.md | 5 ++-- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../references/advanced-agent-fields.md | 14 ++++++++++ .../references/permission-modes-rules.md | 6 +++++ .../references/system-prompt-design.md | 9 +++++++ .../skills/hook-development/SKILL.md | 4 +++ .../hook-development/references/advanced.md | 27 ++++++++++++++++++- .../references/event-schemas.md | 8 +++--- .../skills/marketplace-structure/SKILL.md | 6 +++++ .../skills/mcp-integration/SKILL.md | 2 ++ .../references/authentication.md | 18 +++++++++++++ .../skills/plugin-structure/SKILL.md | 13 +++++++++ .../skills/skill-development/SKILL.md | 8 ++++++ 16 files changed, 138 insertions(+), 11 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 75cf7e5..1e28cff 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.7.0" + "version": "0.8.0" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.7.0", + "version": "0.8.0", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index ee53858..9b44b53 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.8.0] - 2026-03-29 + +### Added + +- **hook-development**: Documented conditional `if` field for hooks using permission rule syntax (CC 2.1.85) +- **hook-development**: Documented `AskUserQuestion` satisfaction via PreToolUse `updatedInput` (CC 2.1.85) +- **skill-development**: Documented 250-character description cap in `/skills` menu (CC 2.1.86) +- **skill-development**: Documented alphabetical sorting in `/skills` menu (CC 2.1.86) +- **plugin-structure**: Documented organization plugin blocking via managed settings (CC 2.1.85) +- **plugin-structure**: Documented resolved "Permission denied" bug for marketplace scripts (CC 2.1.86) +- **mcp-integration**: Documented `CLAUDE_CODE_MCP_SERVER_NAME` and `CLAUDE_CODE_MCP_SERVER_URL` env vars for headersHelper (CC 2.1.85) +- **agent-development**: Documented upstream prompt change from "nothing more, nothing less" to "Complete the task fully" (CC 2.1.86) +- **agent-development**: Documented `name` field guidance for spawned agents/forks (CC 2.1.85) +- **agent-development**: Documented "Production Reads" blocked category in permission modes (CC 2.1.85) +- **marketplace-structure**: Documented organization plugin blocking (CC 2.1.85) + +### Fixed + +- **skill-development**: Noted resolved `paths:` frontmatter bug where tools failed on files outside project root (CC 2.1.86) +- **event-schemas**: Updated event count from 22 to 24 + ## [0.7.0] - 2026-03-29 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 17b1bc5..f64bc7c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 11 skills, 7 agents, 3 slash commands. -**Version**: v0.7.0 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.8.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md index 7af9b6c..0bbcf4b 100644 --- a/docs/claude-code-compatibility.md +++ b/docs/claude-code-compatibility.md @@ -1,10 +1,11 @@ # Claude Code Compatibility -Last audited: Claude Code 2.1.84 (2026-03-27) -Plugin-dev version: 0.7.0 +Last audited: Claude Code 2.1.86 (2026-03-29) +Plugin-dev version: 0.8.0 ## Audit Log | plugin-dev | CC version range | Date | Notes | |---|---|---|---| +| v0.8.0 | 2.1.85-2.1.86 | 2026-03-29 | Hook `if` field, AskUserQuestion via updatedInput, skill 250-char cap, alphabetical /skills, org plugin blocking, MCP env vars, agent prompt change, fork naming, Production Reads | | v0.5.0 | ≤2.1.84 | 2026-03-27 | Initial compatibility baseline (initialPrompt, CwdChanged, FileChanged, userConfig, paths) | diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 332cf5f..969366a 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.7.0", + "version": "0.8.0", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", 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 index 447314d..eb18fdb 100644 --- a/plugins/plugin-dev/skills/agent-development/references/advanced-agent-fields.md +++ b/plugins/plugin-dev/skills/agent-development/references/advanced-agent-fields.md @@ -130,6 +130,20 @@ All hook events are supported in agent frontmatter. Key behavior difference: Background agents that encounter an unapproved permission request will fail. Design tool restrictions (`tools`, `permissionMode`) accordingly when agents may run in background. +### Naming Spawned Agents (CC 2.1.85) + +Pass a short `name` when spawning agents so users can identify them in the teams panel and steer them mid-run: + +```json +{ + "description": "Review code changes", + "prompt": "Review the latest changes for bugs...", + "name": "code-reviewer" +} +``` + +The `name` field is optional but recommended for any agent that runs in background or as part of a team. It appears in the teams panel UI, making it easier for users to track and message specific agents. + ### Resuming Agents Each Task tool invocation creates a new agent instance with a fresh context. To continue with the full prior context preserved, ask Claude to "resume that agent" or "continue that subagent" — it will restore the previous transcript. 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 index 8e44eae..b0317fd 100644 --- a/plugins/plugin-dev/skills/agent-development/references/permission-modes-rules.md +++ b/plugins/plugin-dev/skills/agent-development/references/permission-modes-rules.md @@ -132,6 +132,12 @@ Rules are evaluated in a strict order — first match wins within each tier: 2. **Ask** rules checked second 3. **Allow** rules checked last +### Blocked Categories + +Claude Code's security monitor blocks certain categories of operations regardless of permission mode. These require explicit user approval: + +- **Production Reads (CC 2.1.85):** Reading inside running production systems via remote shell, dumping environment variables or configs from production, and direct production database queries. Agent developers building ops-focused or deployment agents should be aware that these operations will prompt the user even in `dontAsk` mode. + ### Default Permission Tiers Tools fall into three default permission tiers: diff --git a/plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md b/plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md index b8678f8..f9f875a 100644 --- a/plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md +++ b/plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md @@ -267,6 +267,15 @@ You are an expert [domain] orchestrator specializing in coordinating [complex wo - Timeout: Report partial completion ``` +## Upstream Prompt Evolution + +Track these changes to Claude Code's own agent prompts, since plugin agents often model their behavior on upstream patterns: + +- **CC 2.1.86:** The general-purpose agent directive changed from "Do what has been asked; nothing more, nothing less" to "Complete the task fully — don't gold-plate, but don't leave it half-done." This shifts from minimalist task execution toward ensuring completeness without over-engineering. +- **CC 2.1.86:** Task complexity guidance expanded — agents are now instructed to match implementation complexity to task requirements, avoiding both speculative abstractions and half-finished implementations. + +When writing agent system prompts, align with this direction: encourage thorough completion rather than premature stopping, but discourage scope creep. + ## Writing Style Guidelines ### Tone and Voice diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index 26829bd..ab8fb9a 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/plugins/plugin-dev/skills/hook-development/SKILL.md @@ -143,6 +143,7 @@ Each hook entry in a matcher group supports these fields: "allowedEnvVars": ["ENV_VAR"], "prompt": "string (prompt/agent type only)", "model": "string (prompt/agent, optional)", + "if": "string (permission rule syntax, optional)", "timeout": 600, "statusMessage": "Validating...", "once": false, @@ -150,6 +151,7 @@ Each hook entry in a matcher group supports these fields: } ``` +- `if`: Conditional execution using permission rule syntax (e.g., `Bash(git *)` runs the hook only for git commands). When set, the hook fires only when the tool call matches the pattern. Combines with `matcher` for precise targeting — `matcher` selects the event, `if` filters within it. Added in CC 2.1.85. - `timeout`: Max execution time in seconds. Defaults vary by type (command: 60s, prompt: 30s, http: 30s, agent: 60s) - `statusMessage`: Shown in the UI while the hook runs - `once`: Run only once per session (not per event occurrence) @@ -324,6 +326,8 @@ Execute before any tool runs. Use to approve, deny, or modify tool calls. ``` > **Deprecated:** The old top-level `decision: "approve|block"` fields still work but are superseded by `hookSpecificOutput.permissionDecision`. Use `permissionDecision` for new hooks. +> +> **AskUserQuestion pattern (CC 2.1.85):** PreToolUse hooks can satisfy `AskUserQuestion` tool calls by returning `updatedInput` alongside `permissionDecision: "allow"`. This enables headless integrations that collect answers via their own UI rather than requiring interactive user input. #### PermissionRequest diff --git a/plugins/plugin-dev/skills/hook-development/references/advanced.md b/plugins/plugin-dev/skills/hook-development/references/advanced.md index b44049c..407357d 100644 --- a/plugins/plugin-dev/skills/hook-development/references/advanced.md +++ b/plugins/plugin-dev/skills/hook-development/references/advanced.md @@ -50,7 +50,32 @@ The command hook quickly approves obviously safe commands, while the prompt hook ## Conditional Hook Execution -Execute hooks based on environment or context: +### Declarative `if` Field (CC 2.1.85) + +Hooks support a declarative `if` field using permission rule syntax to filter when they run: + +```json +{ + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-git.sh", + "if": "Bash(git *)" + } + ] + } + ] +} +``` + +This hook fires only for Bash commands starting with `git`. The `if` field uses the same permission rule syntax as `settings.json` allow/deny rules (e.g., `Bash(npm *)`, `Edit(src/**)`, `Write(tests/**)`). Combine with `matcher` for two-level filtering: `matcher` selects the event type, `if` narrows to specific invocations. + +### Script-Level Conditionals + +Execute hooks based on environment or context in the script itself: ```bash #!/bin/bash diff --git a/plugins/plugin-dev/skills/hook-development/references/event-schemas.md b/plugins/plugin-dev/skills/hook-development/references/event-schemas.md index 039eec7..6c62bfd 100644 --- a/plugins/plugin-dev/skills/hook-development/references/event-schemas.md +++ b/plugins/plugin-dev/skills/hook-development/references/event-schemas.md @@ -1,6 +1,6 @@ # Hook Event Schemas Reference -Complete input and output JSON schemas for all 22 Claude Code hook events. +Complete input and output JSON schemas for all 24 Claude Code hook events. **Last verified:** 2026-03-20 against official docs, Python SDK (`claude-agent-sdk`), and TypeScript SDK. @@ -245,7 +245,7 @@ Note: `permission_mode` is not present on SessionStart. - `permissionDecision`: `"allow"` approves without prompting, `"deny"` blocks execution, `"ask"` shows permission dialog - `permissionDecisionReason`: Explanation logged for the decision -- `updatedInput`: Replace specific tool_input fields (merged, not replaced wholesale) +- `updatedInput`: Replace specific tool_input fields (merged, not replaced wholesale). For `AskUserQuestion` tool calls, return `updatedInput` alongside `permissionDecision: "allow"` to provide answers programmatically (CC 2.1.85), enabling headless integrations that collect answers via their own UI. - `additionalContext`: Injected into Claude's context for this tool call **Deprecated fields:** Top-level `decision: "approve|block"` still works but `hookSpecificOutput.permissionDecision` takes precedence. @@ -883,10 +883,10 @@ Observability only. No decision control. Not all events are typed in both SDKs. As of March 2026: -**Python SDK** (`claude-agent-sdk`) types 10 of 22 events: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification, SubagentStart, PermissionRequest. +**Python SDK** (`claude-agent-sdk`) types 10 of 24 events: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification, SubagentStart, PermissionRequest. **TypeScript SDK** (`@anthropic-ai/claude-agent-sdk`) is closer to parity with the CLI. Events added over time: TeammateIdle and TaskCompleted (v2.1.34), ConfigChange (v0.2.49), Elicitation and ElicitationResult (v0.2.76). -**CLI** supports all 22 events. +**CLI** supports all 24 events. Events only available in CLI (not yet in either SDK): WorktreeCreate, WorktreeRemove, PostCompact, InstructionsLoaded, StopFailure. diff --git a/plugins/plugin-dev/skills/marketplace-structure/SKILL.md b/plugins/plugin-dev/skills/marketplace-structure/SKILL.md index 72ceef0..229250f 100644 --- a/plugins/plugin-dev/skills/marketplace-structure/SKILL.md +++ b/plugins/plugin-dev/skills/marketplace-structure/SKILL.md @@ -222,6 +222,12 @@ Organizations can restrict plugin sources via managed settings: - `strictKnownMarketplaces: true` — Only allow plugins from known/approved marketplaces - `extraKnownMarketplaces` — Add organization-approved marketplace URLs in managed settings +### Organization Plugin Blocking (CC 2.1.85) + +Organizations can block specific plugins via `managed-settings.json`. Blocked plugins cannot be installed or enabled and are hidden from marketplace views. This is separate from marketplace restrictions — even plugins from approved marketplaces can be individually blocked. + +Plugin developers distributing to enterprise users should document the plugin name clearly so admins can add it to their allow list if needed. + ### Private Repository Authentication For private marketplace repositories, set authentication tokens: diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index b31bb42..dab3e1f 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -227,6 +227,8 @@ All MCP configurations support environment variable substitution: Env vars support fallback values: `${VAR:-default_value}`. Supported in `command`, `args`, `env`, `url`, and `headers` fields. +**MCP server identity variables (CC 2.1.85):** Claude Code injects `CLAUDE_CODE_MCP_SERVER_NAME` and `CLAUDE_CODE_MCP_SERVER_URL` into `headersHelper` scripts, enabling server self-identification in multi-server setups. + **Best practice:** Document all required environment variables in plugin README. ## MCP Tool Naming diff --git a/plugins/plugin-dev/skills/mcp-integration/references/authentication.md b/plugins/plugin-dev/skills/mcp-integration/references/authentication.md index c763541..272da64 100644 --- a/plugins/plugin-dev/skills/mcp-integration/references/authentication.md +++ b/plugins/plugin-dev/skills/mcp-integration/references/authentication.md @@ -291,6 +291,24 @@ cat <&2 + +TOKEN=$(fetch-token-for "$CLAUDE_CODE_MCP_SERVER_NAME") +echo "{\"Authorization\": \"Bearer $TOKEN\"}" +``` + ### Use Cases for Dynamic Headers - Short-lived tokens that need refresh diff --git a/plugins/plugin-dev/skills/plugin-structure/SKILL.md b/plugins/plugin-dev/skills/plugin-structure/SKILL.md index 5af2343..b0a26be 100644 --- a/plugins/plugin-dev/skills/plugin-structure/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-structure/SKILL.md @@ -646,6 +646,19 @@ claude --plugin-dir /path/to/plugin - Verify custom paths in manifest are correct - Restart Claude Code to reload plugin configuration +**Plugin blocked by organization policy**: + +- Organizations can block specific plugins via `managed-settings.json` (CC 2.1.85) +- Blocked plugins cannot be installed or enabled and are hidden from marketplace views +- If users report they can't find or install the plugin, check whether their organization has restricted it +- Plugin developers cannot override organization policies; work with the organization's admin to approve the plugin + +**Plugin scripts failing with "Permission denied"**: + +- Fixed in CC 2.1.86. Official marketplace plugin scripts previously failed with "Permission denied" on macOS/Linux (since CC 2.1.83) +- Ensure all executable scripts have proper permissions: `chmod +x scripts/*.sh` +- Include `#!/bin/bash` (or appropriate shebang) at the top of every script + **Conflicts between plugins**: - Use unique, descriptive component names diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index 8e5d479..fbf4a3a 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -215,6 +215,8 @@ paths: When set, the skill only loads into context when Claude is working with files matching these patterns. Reduces token usage by making skills contextual rather than always-loaded. Accepts a YAML list of glob patterns with brace expansion support. +> **Resolved (CC 2.1.86):** Write, Edit, and Read tools previously failed on files outside the project root when conditional (path-scoped) skills were configured. This is now fixed. + ##### argument-hint (optional) ```yaml @@ -327,6 +329,12 @@ Skill descriptions consume ~2% of context window (~16KB fallback). If total skil Keep descriptions concise but include trigger phrases. Skills with longer descriptions are more likely to be excluded when budget pressure is high. See `references/advanced-frontmatter.md` for optimization strategies. +### /skills Menu Display (CC 2.1.86) + +The `/skills` menu truncates descriptions at **250 characters**. Descriptions longer than this are cut off in the menu listing (though the full description is still used for auto-discovery matching). Place the most important trigger phrases early in the description so they remain visible. + +Skills are listed **alphabetically** in the `/skills` menu. Name skills with discoverability in mind — a skill named `api-testing` appears near the top, while `zsh-config` appears at the bottom. + ### Context Management for Plugins After auto-compaction, skill descriptions survive (they're re-injected), but skill body content may be lost. Users can re-invoke the skill to reload it. The `PreCompact` hook can preserve critical state before compaction occurs. From e2d0ec66e30845b5e4104f0dc40b54ce883e692c Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 15:02:07 +1300 Subject: [PATCH 22/33] feat: add scheduled upstream sync workflow Runs the update-from-upstream skill every 3 days via claude-code-action. Creates a PR for review instead of committing directly to main. Clones Piebald-AI/claude-code-system-prompts for three-source triangulation. --- .github/workflows/upstream-sync.yml | 96 +++++++++++++++++++ docs/ci-cd.md | 8 +- .../2026-03-29-upstream-sync-ci-design.md | 75 +++++++++++++++ plugins/plugin-dev/agents/changelog-differ.md | 7 +- 4 files changed, 183 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/upstream-sync.yml create mode 100644 docs/superpowers/specs/2026-03-29-upstream-sync-ci-design.md diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml new file mode 100644 index 0000000..5893958 --- /dev/null +++ b/.github/workflows/upstream-sync.yml @@ -0,0 +1,96 @@ +# yamllint disable rule:line-length +name: Upstream Sync + +on: + schedule: + - cron: "0 6 */3 * *" # Every 3 days at 06:00 UTC + workflow_dispatch: # Manual trigger for testing + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + sync: + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read + steps: + - name: Checkout plugin-dev + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + fetch-depth: 0 + + - name: Checkout claude-code-system-prompts + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + repository: Piebald-AI/claude-code-system-prompts + path: claude-code-system-prompts + + - name: Setup Node.js + uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0 + with: + node-version: 22 + + - name: Cache npm tools + uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2 + id: npm-tools-cache + with: + path: ~/.npm + key: ${{ runner.os }}-npm-lint-tools-v1 + + - name: Install linting tools + if: steps.npm-tools-cache.outputs.cache-hit != 'true' + run: npm install -g markdownlint-cli2 + + - name: Run upstream sync + uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + use_commit_signing: true + plugin_marketplaces: "./" + plugins: "plugin-dev" + prompt: | + You are running an automated upstream sync for the plugin-dev plugin. + + ## Task + + Run the `plugin-dev:update-from-upstream` skill. Follow all four stages + of the pipeline exactly as documented in the skill. + + ## CI Overrides + + **Release step override**: Instead of committing directly to main, do this: + 1. Create a new branch named `claude/upstream-sync-` (use today's date as YYYY-MM-DD) + 2. Commit all changes to that branch with conventional commit format + 3. Push the branch and open a PR against main + 4. The PR title should be: `docs: sync plugin-dev with Claude Code vX.Y.Z-vA.B.C` + 5. The PR body should include: + - A summary of what changed (from the manifest) + - The CC version range covered + - A checklist of updated skills/files + + **System prompts path**: The Piebald-AI/claude-code-system-prompts repo is + checked out at `./claude-code-system-prompts/` — use this path instead of + `/Users/kyle/Code/meta-claude/claude-code-system-prompts` for Stage 1 + triangulation. + + **No changes**: If the pipeline finds no new Claude Code versions since the + last audit (check `docs/claude-code-compatibility.md`), exit cleanly with + no PR. Report "Already up to date" in the step summary. + + ## Important + + - Do NOT commit directly to main + - Do NOT skip any pipeline stages + - Do NOT skip the verification agents (Stages 2 and 4) + - If any stage fails, report the failure clearly and stop + claude_args: | + --model claude-opus-4-5-20251101 + --max-turns 50 + --allowedTools "Read,Write,Edit,Bash,Grep,Glob,WebFetch,Agent" diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 5cce2ac..5df53a4 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -14,10 +14,16 @@ Documentation for GitHub Actions workflows, labels, and templates. | `yaml-lint.yml` | `.github/workflows/**` changed | Lint YAML files | | `claude-pr-review.yml` | All PRs (non-draft) | AI-powered code review | +## Scheduled Workflows + +| Workflow | Schedule | Purpose | +| --------------------- | ----------------- | ---------------------------------------------- | +| `upstream-sync.yml` | Every 3 days | Sync plugin-dev docs with Claude Code releases | +| `stale.yml` | Mon/Wed/Fri | Manages stale issues/PRs | + ## Other Workflows - `claude.yml` - Main Claude Code workflow -- `stale.yml` - Manages stale issues/PRs (Mon/Wed/Fri) - `semantic-labeler.yml` - Auto-labels issues/PRs - `ci-failure-analysis.yml` - Analyzes CI failures - `sync-labels.yml` - Synchronizes repository labels diff --git a/docs/superpowers/specs/2026-03-29-upstream-sync-ci-design.md b/docs/superpowers/specs/2026-03-29-upstream-sync-ci-design.md new file mode 100644 index 0000000..5c1261a --- /dev/null +++ b/docs/superpowers/specs/2026-03-29-upstream-sync-ci-design.md @@ -0,0 +1,75 @@ +# Upstream Sync CI - Design Spec + +## Problem + +The `update-from-upstream` skill keeps plugin-dev current with Claude Code releases, but it requires manual invocation. Claude Code releases multiple times per week. Without automation, the skill only runs when someone remembers to trigger it. + +## Solution + +A scheduled GitHub Actions workflow that runs the `update-from-upstream` skill every 3 days, creating a PR for human review. + +## Workflow + +**File:** `.github/workflows/upstream-sync.yml` + +**Trigger:** `schedule` (every 3 days at 06:00 UTC) + `workflow_dispatch` for manual testing. + +**Steps:** + +1. Checkout plugin-dev repo (fetch-depth 0 for full history) +2. Checkout `Piebald-AI/claude-code-system-prompts` into `./claude-code-system-prompts/` +3. Setup Node.js 22, install markdownlint-cli2 (cached) +4. Run `claude-code-action` with plugin-dev loaded as a plugin + +**Plugin loading:** The action's `plugin_marketplaces` input accepts local paths. Since the repo root contains `.claude-plugin/marketplace.json`, pointing it at `"./"` registers the marketplace. Then `plugins: "plugin-dev"` installs the plugin from that marketplace. + +**Authentication:** Uses `CLAUDE_CODE_OAUTH_TOKEN` (same as all existing Claude workflows in this repo). Falls back to `ANTHROPIC_API_KEY` if the OAuth token doesn't work for scheduled triggers. + +## CI Overrides + +The workflow's `prompt` tells Claude to follow the skill but override the release step: + +- Create branch `claude/upstream-sync-` instead of committing to main +- Open a PR with the manifest summary in the body +- Exit cleanly with no PR if already up to date + +The skill itself is unchanged. The override lives in the workflow prompt, keeping the skill agnostic to its execution context. + +## Agent Path Handling + +The `changelog-differ` agent checks two paths for the system-prompts repo: + +1. `./claude-code-system-prompts/CHANGELOG.md` (CI checkout path) +2. `/Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md` (local dev path) + +If neither exists, it degrades to single-source triangulation. + +## Permissions + +```yaml +permissions: + contents: write # Push branches + pull-requests: write # Create PRs + issues: write # Recommended by claude-code-action + id-token: write # Claude GitHub App auth + actions: read # Access workflow run data +``` + +## Patterns Followed + +- Pinned action SHAs matching existing workflows (checkout@v6.0.2, setup-node@v6.2.0, cache@v5.0.2, claude-code-action@v1.0.34) +- npm tool caching for markdownlint-cli2 +- Concurrency group to prevent overlapping runs +- Commit signing enabled +- 30-minute timeout (longer than validation workflows due to multi-agent pipeline) +- `--max-turns 50` to bound execution cost + +## Design Decisions + +**Why PR, not direct commit:** The pipeline runs unattended. A PR gives the existing `claude-pr-review.yml` workflow a chance to review changes and lets the maintainer verify accuracy before merging. May be changed to direct-commit once confidence is established. + +**Why 3-day interval:** Claude Code releases 2-3 times per week. Every 3 days catches most releases within one cycle. More frequent would waste API calls on "already up to date" results. + +**Why load as plugin, not inline prompt:** The skill is the single source of truth for the pipeline logic. The workflow prompt only adds CI-specific overrides (PR instead of commit, path adjustments). If the skill evolves, CI picks up changes automatically. + +**Why `--max-turns 50`:** The pipeline dispatches 3 agents and the orchestrator does multi-file edits. 50 turns provides headroom without unbounded execution. Can be tuned based on observed usage. diff --git a/plugins/plugin-dev/agents/changelog-differ.md b/plugins/plugin-dev/agents/changelog-differ.md index 07851d0..0d9f8f5 100644 --- a/plugins/plugin-dev/agents/changelog-differ.md +++ b/plugins/plugin-dev/agents/changelog-differ.md @@ -38,11 +38,14 @@ Extract all version entries **after** the last audited version. If the fetched c ### Step 2: Read System Prompts Changelog -Read the local system-prompts CHANGELOG.md: +Read the local system-prompts CHANGELOG.md. Check these paths in order: ``` -Read: /Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md +Read: ./claude-code-system-prompts/CHANGELOG.md # CI path +Read: /Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md # local path ``` +If neither path exists, degrade to single-source triangulation and note this in the manifest. + Extract entries for the same version range. This source is more structured (includes NEW/REMOVED markers and token deltas). ### Step 3: Cross-Reference with Official Docs From ae65d73f1cc3c9c025f7b28254ac09ed4ac02f10 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sun, 29 Mar 2026 15:16:49 +1300 Subject: [PATCH 23/33] fix: limit system-prompts changelog reads to first 200 lines The file is 30k+ tokens. Versions are newest-first, so the first 200 lines cover the most recent ~10 versions. Prevents token limit errors in both changelog-differ and update-manifest-verifier agents. --- plugins/plugin-dev/agents/changelog-differ.md | 6 ++++-- plugins/plugin-dev/agents/update-manifest-verifier.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/plugins/plugin-dev/agents/changelog-differ.md b/plugins/plugin-dev/agents/changelog-differ.md index 0d9f8f5..d51e7eb 100644 --- a/plugins/plugin-dev/agents/changelog-differ.md +++ b/plugins/plugin-dev/agents/changelog-differ.md @@ -40,12 +40,14 @@ Extract all version entries **after** the last audited version. If the fetched c Read the local system-prompts CHANGELOG.md. Check these paths in order: ``` -Read: ./claude-code-system-prompts/CHANGELOG.md # CI path -Read: /Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md # local path +./claude-code-system-prompts/CHANGELOG.md # CI path +/Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md # local path ``` If neither path exists, degrade to single-source triangulation and note this in the manifest. +**Important:** This file is large (30k+ tokens). Versions are listed newest-first. Read only the first 200 lines (`offset: 1, limit: 200`) — this covers the most recent ~10 versions, which is more than enough for any audit range. Do NOT read the entire file. + Extract entries for the same version range. This source is more structured (includes NEW/REMOVED markers and token deltas). ### Step 3: Cross-Reference with Official Docs diff --git a/plugins/plugin-dev/agents/update-manifest-verifier.md b/plugins/plugin-dev/agents/update-manifest-verifier.md index 0cf3247..dbca081 100644 --- a/plugins/plugin-dev/agents/update-manifest-verifier.md +++ b/plugins/plugin-dev/agents/update-manifest-verifier.md @@ -39,10 +39,12 @@ Fetch your own copy of the CC changelog (do NOT rely on Stage 1's fetch): WebFetch: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md ``` -Read the local system-prompts CHANGELOG: +Read the local system-prompts CHANGELOG (first 200 lines only — versions are newest-first, full file is 30k+ tokens): ``` -Read: /Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md +./claude-code-system-prompts/CHANGELOG.md # CI path +/Users/kyle/Code/meta-claude/claude-code-system-prompts/CHANGELOG.md # local path ``` +Use `offset: 1, limit: 200` to avoid reading the entire file. ### Step 3: Verify Each "Must Update" Item From c4524cd8ae0dcf1d109c6da6180cc32f78788291 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Tue, 31 Mar 2026 21:24:48 +1300 Subject: [PATCH 24/33] fix: increase upstream sync turn budget and enable full output First production run hit error_max_turns at 51 turns ($5.73). The four-stage pipeline with three subagents needs more headroom. --- .github/workflows/upstream-sync.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index 5893958..19e1971 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -13,7 +13,7 @@ concurrency: jobs: sync: runs-on: ubuntu-latest - timeout-minutes: 30 + timeout-minutes: 60 permissions: contents: write pull-requests: write @@ -53,6 +53,7 @@ jobs: with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} use_commit_signing: true + show_full_output: true plugin_marketplaces: "./" plugins: "plugin-dev" prompt: | @@ -92,5 +93,5 @@ jobs: - If any stage fails, report the failure clearly and stop claude_args: | --model claude-opus-4-5-20251101 - --max-turns 50 + --max-turns 150 --allowedTools "Read,Write,Edit,Bash,Grep,Glob,WebFetch,Agent" From 2efeadc9b586550ac389bcedf15fd10db00871e4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 31 Mar 2026 08:39:10 +0000 Subject: [PATCH 25/33] feat: sync plugin-dev with Claude Code v2.1.87-v2.1.88 Updates plugin-dev documentation to reflect Claude Code changes from versions 2.1.87 through 2.1.88. Key changes: - Add PermissionDenied hook event (25th hook event) - Document file_path absolute path behavior for Write/Edit/Read tools - Document hook `if` field fix for compound commands - Document partial compaction capability - Add Config tool reference in agent-development Co-Authored-By: Claude Opus 4.5 --- .agent-history/upstream-changes.md | 217 ++++++++++++++++++ .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 22 +- CLAUDE.md | 2 +- docs/claude-code-compatibility.md | 5 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../skills/agent-development/SKILL.md | 1 + .../skills/hook-development/SKILL.md | 57 ++++- .../hook-development/references/advanced.md | 2 + .../references/event-schemas.md | 50 +++- .../references/hook-input-schemas.md | 2 + 11 files changed, 345 insertions(+), 19 deletions(-) create mode 100644 .agent-history/upstream-changes.md diff --git a/.agent-history/upstream-changes.md b/.agent-history/upstream-changes.md new file mode 100644 index 0000000..64483d3 --- /dev/null +++ b/.agent-history/upstream-changes.md @@ -0,0 +1,217 @@ +# Upstream Change Manifest +## CC Version Range: 2.1.87 - 2.1.88 +## Generated: 2026-03-31 +## Sources: changelog [x], system-prompts [x], claude-code-guide [skipped] + +Note: claude-code-guide subagent not available in this environment. Triangulation degraded to two sources. + +--- + +### Must Update + +- [ ] **NEW: Config tool added** (CC 2.1.88) + - Source: system-prompts + - Confidence: high + - Affects: agent-development skill (tool references) + - Details: New tool for getting and setting Claude Code configuration settings. Plugin-dev documentation should be updated to include this new tool in tool references and agent toolset descriptions. + - Raw: "**NEW:** Tool Description: Config - Added tool for getting and setting Claude Code configuration settings." + +- [ ] **TeammateTool path changed** (CC 2.1.88) + - Source: system-prompts + - Confidence: high + - Affects: agent-development skill (teams section) + - Details: Team file path changed from `~/.claude/teams/{team-name}.json` to `~/.claude/teams/{team-name}/config.json`. Any documentation referencing team file locations needs updating. + - Raw: "Tool Description: TeammateTool - Updated the team file path from `~/.claude/teams/{team-name}.json` to `~/.claude/teams/{team-name}/config.json`." + +- [ ] **NEW: Partial compaction instructions** (CC 2.1.88) + - Source: system-prompts + - Confidence: high + - Affects: hook-development skill (PreCompact/PostCompact), skill-development skill (context management) + - Details: Added instructions for compacting only a portion of the conversation with a structured summary format. This is a new capability that may warrant documentation. + - Raw: "**NEW:** System Prompt: Partial compaction instructions - Added instructions for compacting only a portion of the conversation, with a structured summary format and analysis process." + +- [ ] **REMOVED: System section (tool permission mode)** (CC 2.1.88) + - Source: system-prompts + - Confidence: high + - Affects: hook-development skill (terminology review) + - Details: Removed the system section describing tool permission mode behavior and denied tool call guidance. Any references to this in plugin-dev docs should be reviewed. + - Raw: "**REMOVED:** System Prompt: System section - Removed the system section describing tool permission mode behavior and denied tool call guidance." + +- [ ] **PreToolUse/PostToolUse file_path now absolute** (CC 2.1.88) + - Source: CC changelog (PROMOTED from No Action) + - Confidence: high + - Affects: hook-development skill (event-schemas.md, hook-input-schemas.md) + - Details: Fixed PreToolUse/PostToolUse hooks not providing `file_path` as an absolute path for Write/Edit/Read tools. Hook scripts that process file_path now receive absolute paths. This is a behavior change affecting hook script logic. + - Raw: "Fixed PreToolUse/PostToolUse hooks not providing `file_path` as an absolute path for Write/Edit/Read tools" + +- [ ] **NEW: PermissionDenied hook introduced** (CC 2.1.88) + - Source: CC changelog (PROMOTED from No Action) + - Confidence: high + - Affects: hook-development skill (new hook event to document) + - Details: Introduced `PermissionDenied` hook that activates following auto mode classifier denials, allowing models to request retry via `{retry: true}` response. This is a NEW hook event (25th event) that must be added to hook-development documentation. + - Raw: "Introduced `PermissionDenied` hook that activates following auto mode classifier denials, allowing models to request retry via `{retry: true}` response" + +- [ ] **Hook `if` filtering fix for compound commands** (CC 2.1.88) + - Source: CC changelog (PROMOTED from No Action) + - Confidence: high + - Affects: hook-development skill (advanced.md, `if` field documentation) + - Details: Fixed hooks' `if` condition filtering to properly match compound commands like `ls && git push` and commands with environment variable prefixes such as `FOO=bar git push`. Existing documentation should note this behavior. + - Raw: "Fixed hooks' `if` condition filtering to properly match compound commands like `ls && git push` and commands with environment variable prefixes such as `FOO=bar git push`" + +--- + +### May Update + +- [ ] **Git status prompt simplified** (CC 2.1.88) + - Source: system-prompts + - Confidence: medium + - Affects: git-related skill examples + - Details: Stripped inline variable template (branch, status, recent commits); now contains only the introductory note that git status is a point-in-time snapshot. + - Raw: "System Prompt: Git status - Stripped the inline variable template (branch, status, recent commits); now contains only the introductory note that git status is a point-in-time snapshot." + +- [ ] **Fork usage guidelines updated** (CC 2.1.88) + - Source: system-prompts + - Confidence: medium + - Affects: agent documentation + - Details: Incorporated fork-specific prompt-writing guidance about writing directives that specify scope rather than re-explaining background. + - Raw: "System Prompt: Fork usage guidelines - Incorporated fork-specific prompt-writing guidance (previously in the subagent prompts section) about writing directives that specify scope rather than re-explaining background." + +- [ ] **Writing subagent prompts collapsed** (CC 2.1.88) + - Source: system-prompts + - Confidence: medium + - Affects: agent-creator skill + - Details: Collapsed separate context-inheriting vs fresh-agent sections into a single flow that defaults to fresh-agent briefing style with conditional notes for subagent types. + - Raw: "System Prompt: Writing subagent prompts - Collapsed the separate context-inheriting vs fresh-agent sections into a single flow that defaults to the fresh-agent briefing style, with conditional notes when a subagent type is present." + +- [ ] **Plan mode reminder conditional on agent availability** (CC 2.1.88) + - Source: system-prompts + - Confidence: medium + - Affects: plan-mode documentation + - Details: Subagent exploration suggestion is now conditional on whether agents are actually available. + - Raw: "System Reminder: Plan mode is active (iterative) - Made the subagent exploration suggestion conditional on whether agents are actually available, instead of always appending it." + +- [ ] **Agent tool prompt guidance moved** (CC 2.1.88) + - Source: system-prompts + - Confidence: medium + - Affects: agent-creator skill + - Details: Removed instruction to provide clear, detailed prompts for agents without subagent types (guidance now lives in fork/subagent prompt-writing sections). + - Raw: "Tool Description: Agent (usage notes) - Removed the instruction to provide clear, detailed prompts for agents without subagent types (guidance now lives in the fork/subagent prompt-writing sections)." + +- [ ] **PowerShell tool description expanded** (CC 2.1.88) + - Source: system-prompts (DEMOTED from Must Update) + - Confidence: medium + - Affects: Windows-specific documentation (none exists in plugin-dev) + - Details: Significantly expanded PowerShell syntax guidance. Windows-specific; no existing PowerShell documentation in plugin-dev to update. + - Raw: "Tool Description: PowerShell - Significantly expanded syntax guidance..." + +- [ ] **NEW: PowerShell 5.1 system prompt** (CC 2.1.88) + - Source: system-prompts (DEMOTED from Must Update) + - Confidence: medium + - Affects: Windows-specific documentation (none exists in plugin-dev) + - Details: Added system prompt for Windows PowerShell 5.1. Windows-specific; no existing PowerShell documentation in plugin-dev. + - Raw: "**NEW:** System Prompt: PowerShell edition for 5.1..." + +--- + +### No Action + +- v2.1.88: Flicker-free rendering via CLAUDE_CODE_NO_FLICKER=1 environment variable (UI/rendering) +- v2.1.88: Named subagents in mention suggestions (UI feature) +- v2.1.88: Fixed prompt cache issues in extended sessions (bug fix) +- v2.1.88: Fixed nested file re-injection in long conversations (bug fix) +- v2.1.88: Line-ending handling for Edit/Write tools on Windows (bug fix) +- v2.1.88: Structured output schema caching improvements (performance) +- v2.1.88: Memory leaks related to large JSON inputs (bug fix) +- v2.1.88: Rate-limit error messaging improvements (UX) +- v2.1.88: LSP server recovery after crashes (bug fix) +- v2.1.88: Voice mode fixes on macOS/Windows (platform-specific bug fix) +- v2.1.88: UI rendering artifacts and text truncation fixes (UI bug fix) +- v2.1.88: Prompt history corruption at 4KB boundaries fix (bug fix) +- v2.1.88: Statistics tracking historical data fix (bug fix) +- v2.1.88: Notification clearing and message synchronization (bug fix) +- v2.1.88: Verify skill substantially condensed (CC's built-in verify skill, not plugin-dev) +- v2.1.88: Ultraplan same-session implementation (internal CC feature, not plugin-dev relevant) +- v2.1.88: Plugin permission fix on macOS/Linux since v2.1.83 (bug fix) +- v2.1.87: No system prompt changes + +--- + +## Summary + +**Versions analyzed:** 2.1.87, 2.1.88 + +**Token delta (2.1.88):** -1,627 tokens (net reduction due to verify skill condensing and removed system section) + +**Key themes in 2.1.88:** +1. New Config tool for settings management +2. New PermissionDenied hook event (ADDED by verification) +3. Team file path restructuring +4. PreToolUse/PostToolUse file_path now absolute (ADDED by verification) +5. Partial compaction feature +6. Enhanced Windows/PowerShell support (May Update) +7. Removed tool permission mode system section + +**Risk assessment:** The PermissionDenied hook and file_path absolute path fix are the highest priority items as they directly affect hook development documentation. The team file path change and Config tool addition also require updates. + +--- + +## Stage 2: Verification Results +### Verified: 2026-03-31 + +#### Must Update Verification +- [x] **NEW: Config tool added** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 13. Gap exists: no mention of Config tool in plugin-dev tool documentation. Affects: agent-development (tool references). +- [x] **TeammateTool path changed** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 23. Gap exists: plugin-dev agent-development skill does not document team file paths. Affects: agent-development (teams section). +- [x] **NEW: Partial compaction instructions** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 11. Gap exists: no documentation of partial compaction. Affects: hook-development (PreCompact/PostCompact), skill-development (context management). +- [x] **REMOVED: System section (tool permission mode)** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 14. Gap exists: hook-development references "tool permission mode" terminology. Review needed. +- [x] **Verify skill substantially condensed** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 15. This is an internal CC change to CC's built-in verify skill, NOT the plugin-dev verify skill. No gap exists in plugin-dev. **Reclassified to No Action** -- plugin-dev has no "verify skill" to align with. +- [x] **PowerShell tool description expanded** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 22. No existing PowerShell documentation in plugin-dev (grep returned no matches). This is a Windows-specific addition. **May Update** level -- only relevant for Windows users. +- [x] **NEW: PowerShell 5.1 system prompt** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 12. Same as above -- no existing PowerShell docs. **May Update** level. +- [x] **Ultraplan can now implement in same session** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 20. No existing ultraplan documentation in plugin-dev. Low impact for plugin developers. **Demoted to No Action** -- ultraplan is an internal CC feature, not directly affecting plugin development. + +#### Missed Items (promoted from No Action) +- ! **PreToolUse/PostToolUse file_path now absolute** (CC 2.1.88) -- missed from changelog! CC changelog says "Fixed PreToolUse/PostToolUse hooks not providing `file_path` as an absolute path for Write/Edit/Read tools." This is directly relevant to hook-development docs. + - Affects: hook-development (tool input schemas, event-schemas.md) + - Details: Hook scripts that process file_path from Write/Edit/Read tools now receive absolute paths. This is a behavior change that affects hook script logic. + +- ! **PermissionDenied hook introduced** (CC 2.1.88) -- partially captured but listed as "No Action". The CC changelog states "Introduced `PermissionDenied` hook that activates following auto mode classifier denials, allowing models to request retry via `{retry: true}` response." This is a NEW hook event that should be documented. + - Affects: hook-development (new hook event) + - Details: New hook event PermissionDenied was introduced. The current hook-development skill lists 24 events; this adds a 25th. Must be documented. + +- ! **Plugin permission fix v2.1.83** (CC 2.1.86, 2.1.88) -- The CC changelog mentions "Official marketplace plugin scripts were failing with permission errors on macOS/Linux starting in v2.1.83; this is now resolved" in both 2.1.86 and 2.1.88. This is worth noting for compatibility but is a bug fix, not a documentation gap. + - Affects: None (bug fix) + - **Kept as No Action** -- bug fix, no docs needed + +- ! **Hook `if` filtering for compound commands** (CC 2.1.88) -- CC changelog: "Fixed hooks' `if` condition filtering to properly match compound commands like `ls && git push` and commands with environment variable prefixes such as `FOO=bar git push`." This is relevant to hook-development. + - Affects: hook-development (advanced.md, `if` field documentation) + - Details: The `if` field now properly handles compound commands. Existing docs may need clarification. + - **Promoted to Must Update** -- behavior clarification for existing feature + +#### May Update Resolution +- = **Git status prompt simplified** (CC 2.1.88) -- kept as May Update. Internal CC change, no plugin-dev impact. +- = **Fork usage guidelines updated** (CC 2.1.88) -- kept as May Update. Could inform agent-development examples but not critical. +- = **Writing subagent prompts collapsed** (CC 2.1.88) -- kept as May Update. Could inform agent-creator agent but not critical. +- = **Plan mode reminder conditional** (CC 2.1.88) -- kept as May Update. Internal CC behavior. +- = **Agent tool prompt guidance moved** (CC 2.1.88) -- kept as May Update. Could inform agent-development but not critical. +- downarrow **PowerShell tool description expanded** -- demoted from Must Update to May Update. Windows-specific, no existing docs to update. +- downarrow **PowerShell 5.1 system prompt** -- demoted from Must Update to May Update. Windows-specific, no existing docs to update. + +#### Summary +- Must Update: 7 items (4 confirmed original, 3 promoted from No Action, 2 demoted to May Update) + - Config tool added + - TeammateTool path changed + - Partial compaction instructions + - REMOVED: System section (tool permission mode) + - PreToolUse/PostToolUse file_path now absolute (NEW) + - PermissionDenied hook introduced (NEW) + - Hook `if` filtering for compound commands (NEW) +- May Update: 7 items (5 original, 2 demoted from Must Update) +- Confidence: HIGH -- sources independently verified, all changelog entries cross-referenced + +#### Notes +- The manifest correctly identified the version range 2.1.87-2.1.88 +- v2.1.87 had no system prompt changes (confirmed) +- The "Verify skill" item was incorrectly classified -- it refers to CC's built-in verify skill, not a plugin-dev skill +- Two significant plugin-relevant changes were in the CC changelog "No Action" section that should have been flagged: + 1. PreToolUse/PostToolUse file_path absolute path fix + 2. PermissionDenied hook introduction +- The `if` field compound command fix enhances existing documented feature diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1e28cff..edac973 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.8.0" + "version": "0.9.0" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.8.0", + "version": "0.9.0", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b44b53..8a2b5ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.9.0] - 2026-03-31 + +### Added + +- **hook-development**: Documented PermissionDenied hook event (25th event) for handling auto mode classifier denials with retry capability (CC 2.1.88) +- **hook-development**: Documented `file_path` absolute path behavior for Write/Edit/Read tools in PreToolUse/PostToolUse hooks (CC 2.1.88) +- **hook-development**: Documented `if` field fix for compound commands and env var prefixes (CC 2.1.88) +- **hook-development**: Documented partial compaction capability with structured summary format (CC 2.1.88) +- **agent-development**: Documented Config tool for getting/setting Claude Code settings (CC 2.1.88) + +### Changed + +- **hook-development**: Updated event count from 24 to 25 across skill and reference documentation + ## [0.8.0] - 2026-03-29 ### Added @@ -320,7 +334,13 @@ 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/kylesnowschwartz/plugin-dev/compare/v0.4.1...HEAD +[Unreleased]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.9.0...HEAD +[0.9.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.8.0...v0.9.0 +[0.8.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.7.0...v0.8.0 +[0.7.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.6.1...v0.7.0 +[0.6.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.6.0...v0.6.1 +[0.6.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.5.0...v0.6.0 +[0.5.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.4.1...v0.5.0 [0.4.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.4.0...v0.4.1 [0.4.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.3.2...v0.4.0 [0.3.2]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.3.1...v0.3.2 diff --git a/CLAUDE.md b/CLAUDE.md index f64bc7c..dadab38 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 11 skills, 7 agents, 3 slash commands. -**Version**: v0.8.0 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.9.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md index 0bbcf4b..ff6c2ba 100644 --- a/docs/claude-code-compatibility.md +++ b/docs/claude-code-compatibility.md @@ -1,11 +1,12 @@ # Claude Code Compatibility -Last audited: Claude Code 2.1.86 (2026-03-29) -Plugin-dev version: 0.8.0 +Last audited: Claude Code 2.1.88 (2026-03-31) +Plugin-dev version: 0.9.0 ## Audit Log | plugin-dev | CC version range | Date | Notes | |---|---|---|---| +| v0.9.0 | 2.1.87-2.1.88 | 2026-03-31 | PermissionDenied hook (25th event), file_path absolute paths, `if` compound command fix, partial compaction, Config tool | | v0.8.0 | 2.1.85-2.1.86 | 2026-03-29 | Hook `if` field, AskUserQuestion via updatedInput, skill 250-char cap, alphabetical /skills, org plugin blocking, MCP env vars, agent prompt change, fork naming, Production Reads | | v0.5.0 | ≤2.1.84 | 2026-03-27 | Initial compatibility baseline (initialPrompt, CwdChanged, FileChanged, userConfig, paths) | diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index 969366a..fa3ea6f 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.8.0", + "version": "0.9.0", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 1c5ee69..3707cac 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -247,6 +247,7 @@ tools: Read, Write, Grep, Bash - Read-only analysis: `Read, Grep, Glob` - Code generation: `Read, Write, Grep` - Testing: `Read, Bash, Grep` +- Configuration: `Config` (CC 2.1.88) - get/set Claude Code settings - Full access: Omit field entirely > **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. diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index ab8fb9a..f95b776 100644 --- 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", or mentions hook events (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, Notification, ConfigChange, TeammateIdle, TaskCompleted, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, InstructionsLoaded, Elicitation, ElicitationResult). 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", or mentions hook events (PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStop, SubagentStart, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, Notification, ConfigChange, TeammateIdle, TaskCompleted, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, InstructionsLoaded, Elicitation, ElicitationResult). 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 @@ -9,11 +9,11 @@ description: This skill should be used when the user asks to "create a hook", "a Hooks are event-driven automation that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows. -Claude Code has **24 hook events** across these categories: +Claude Code has **25 hook events** across these categories: - **Session Lifecycle** -- SessionStart, InstructionsLoaded, SessionEnd - **User Input** -- UserPromptSubmit -- **Tool Lifecycle** -- PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure +- **Tool Lifecycle** -- PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure - **Turn Control** -- Stop, StopFailure - **Subagents** -- SubagentStart, SubagentStop - **Teams** -- TeammateIdle, TaskCompleted @@ -26,6 +26,8 @@ Claude Code has **24 hook events** across these categories: For complete input/output JSON schemas for every event, see **`references/event-schemas.md`**. +> **CC 2.1.88:** Added PermissionDenied hook event. PreToolUse/PostToolUse `file_path` now provides absolute paths for Write/Edit/Read tools. Hook `if` filtering properly matches compound commands (e.g., `ls && git push`) and commands with env var prefixes (e.g., `FOO=bar git push`). + ## Hook Types Four hook types are available. Not all events support all types. @@ -151,7 +153,7 @@ Each hook entry in a matcher group supports these fields: } ``` -- `if`: Conditional execution using permission rule syntax (e.g., `Bash(git *)` runs the hook only for git commands). When set, the hook fires only when the tool call matches the pattern. Combines with `matcher` for precise targeting — `matcher` selects the event, `if` filters within it. Added in CC 2.1.85. +- `if`: Conditional execution using permission rule syntax (e.g., `Bash(git *)` runs the hook only for git commands). When set, the hook fires only when the tool call matches the pattern. Combines with `matcher` for precise targeting — `matcher` selects the event, `if` filters within it. Added in CC 2.1.85. CC 2.1.88 fixed filtering to properly match compound commands (e.g., `ls && git push`) and commands with env var prefixes (e.g., `FOO=bar git push`). - `timeout`: Max execution time in seconds. Defaults vary by type (command: 60s, prompt: 30s, http: 30s, agent: 60s) - `statusMessage`: Shown in the UI while the hook runs - `once`: Run only once per session (not per event occurrence) @@ -380,6 +382,45 @@ Execute when a permission dialog is about to display. Use to automatically allow **Known issues:** `additionalContext` is parsed but silently dropped (works in PreToolUse but not here). Race condition where dialog may briefly show despite returning "allow" ([#12176](https://github.com/anthropics/claude-code/issues/12176)). +#### PermissionDenied + +Execute when auto mode classifier denies a tool call (CC 2.1.88). Use to request retry or handle denials programmatically. + +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent +**Decision control:** Can request retry via `{retry: true}` + +```json +{ + "PermissionDenied": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/handle-denial.sh" + } + ] + } + ] +} +``` + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionDenied", + "retry": true + } +} +``` + +- `retry`: If `true`, requests Claude to retry the denied operation + +**Difference from PermissionRequest:** PermissionRequest fires when a dialog is about to show; PermissionDenied fires after auto mode has already denied the operation. + #### PostToolUse Execute after a tool completes successfully. Use to react to results, provide feedback, or log. @@ -944,6 +985,7 @@ Not all events support all four hook types: | UserPromptSubmit | Yes | Yes | Yes | Yes | | PreToolUse | Yes | Yes | Yes | Yes | | PermissionRequest | Yes | Yes | Yes | Yes | +| PermissionDenied | Yes | Yes | Yes | Yes | | PostToolUse | Yes | Yes | Yes | Yes | | PostToolUseFailure | Yes | Yes | Yes | Yes | | Stop | Yes | Yes | Yes | Yes | @@ -1141,7 +1183,7 @@ echo "$output" | jq . ## Quick Reference -### All 24 Hook Events +### All 25 Hook Events | Event | Category | Matchers | Decision Control | | ------------------ | ------------- | --------------------------- | ----------------------------- | @@ -1151,6 +1193,7 @@ echo "$output" | jq . | UserPromptSubmit | Input | None | Block prompt | | PreToolUse | Tool | Tool names (regex) | Allow/deny/ask, modify input | | PermissionRequest | Tool | Tool names (regex) | Allow/deny, modify input | +| PermissionDenied | Tool | Tool names (regex) | Request retry | | PostToolUse | Tool | Tool names (regex) | Block, modify MCP output | | PostToolUseFailure | Tool | Tool names (regex) | Context injection | | Stop | Turn | None | Block stop | @@ -1189,7 +1232,7 @@ echo "$output" | jq . For detailed patterns and advanced techniques, consult: -- **`references/event-schemas.md`** -- Complete input/output JSON schemas for all 24 events +- **`references/event-schemas.md`** -- Complete input/output JSON schemas for all 25 events - **`references/patterns.md`** -- Proven patterns including temporarily active and configuration-driven hooks - **`references/migration.md`** -- Migrating from basic to advanced hooks - **`references/advanced.md`** -- Advanced use cases and techniques @@ -1233,7 +1276,7 @@ Development tools in `scripts/`: To implement hooks in a plugin: -1. Identify events to hook into (see [Quick Reference](#all-24-hook-events)) +1. Identify events to hook into (see [Quick Reference](#all-25-hook-events)) 2. Decide hook type: prompt (flexible), agent (multi-step), command (deterministic), or HTTP (external) 3. Write hook configuration in `hooks/hooks.json` 4. For command hooks, create hook scripts diff --git a/plugins/plugin-dev/skills/hook-development/references/advanced.md b/plugins/plugin-dev/skills/hook-development/references/advanced.md index 407357d..88488c7 100644 --- a/plugins/plugin-dev/skills/hook-development/references/advanced.md +++ b/plugins/plugin-dev/skills/hook-development/references/advanced.md @@ -73,6 +73,8 @@ Hooks support a declarative `if` field using permission rule syntax to filter wh This hook fires only for Bash commands starting with `git`. The `if` field uses the same permission rule syntax as `settings.json` allow/deny rules (e.g., `Bash(npm *)`, `Edit(src/**)`, `Write(tests/**)`). Combine with `matcher` for two-level filtering: `matcher` selects the event type, `if` narrows to specific invocations. +> **CC 2.1.88:** Fixed `if` field filtering to properly match compound commands (e.g., `ls && git push`) and commands with environment variable prefixes (e.g., `FOO=bar git push`). Previously, such commands could bypass `if` patterns. + ### Script-Level Conditionals Execute hooks based on environment or context in the script itself: diff --git a/plugins/plugin-dev/skills/hook-development/references/event-schemas.md b/plugins/plugin-dev/skills/hook-development/references/event-schemas.md index 6c62bfd..9c09877 100644 --- a/plugins/plugin-dev/skills/hook-development/references/event-schemas.md +++ b/plugins/plugin-dev/skills/hook-development/references/event-schemas.md @@ -1,8 +1,8 @@ # Hook Event Schemas Reference -Complete input and output JSON schemas for all 24 Claude Code hook events. +Complete input and output JSON schemas for all 25 Claude Code hook events. -**Last verified:** 2026-03-20 against official docs, Python SDK (`claude-agent-sdk`), and TypeScript SDK. +**Last verified:** 2026-03-31 against official docs, Python SDK (`claude-agent-sdk`), and TypeScript SDK. ## Common Fields @@ -227,6 +227,8 @@ Note: `permission_mode` is not present on SessionStart. `tool_input` fields vary by tool. The above shows common fields; MCP tools have server-defined inputs. +> **CC 2.1.88:** The `file_path` field for Write, Edit, and Read tools now provides **absolute paths**. + **Output:** ```json @@ -320,6 +322,42 @@ Note: `permission_mode` is not present on SessionStart. --- +### PermissionDenied + +**When:** After auto mode classifier denies a tool call (CC 2.1.88). + +**Input:** + +```json +{ + "session_id": "string", + "transcript_path": "string", + "cwd": "string", + "permission_mode": "string", + "hook_event_name": "PermissionDenied", + "tool_name": "string", + "tool_input": {} +} +``` + +**Output:** + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionDenied", + "retry": true + } +} +``` + +- `retry`: If `true`, requests Claude to retry the denied operation + +**Matchers:** Tool names (same as PreToolUse) +**Hook types:** Command, HTTP, Prompt, Agent + +--- + ### PostToolUse **When:** After tool execution succeeds. @@ -623,6 +661,8 @@ Normal exit allows the task completion to proceed. Use `additionalContext` to inject information that should be considered during compaction. +> **CC 2.1.88:** Added partial compaction capability. Claude Code can now compact only a portion of the conversation rather than the entire context, with a structured summary format and analysis process. + **Matchers:** `manual`, `auto` **Hook types:** Command, HTTP, Prompt, Agent @@ -883,10 +923,10 @@ Observability only. No decision control. Not all events are typed in both SDKs. As of March 2026: -**Python SDK** (`claude-agent-sdk`) types 10 of 24 events: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification, SubagentStart, PermissionRequest. +**Python SDK** (`claude-agent-sdk`) types 10 of 25 events: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification, SubagentStart, PermissionRequest. **TypeScript SDK** (`@anthropic-ai/claude-agent-sdk`) is closer to parity with the CLI. Events added over time: TeammateIdle and TaskCompleted (v2.1.34), ConfigChange (v0.2.49), Elicitation and ElicitationResult (v0.2.76). -**CLI** supports all 24 events. +**CLI** supports all 25 events. -Events only available in CLI (not yet in either SDK): WorktreeCreate, WorktreeRemove, PostCompact, InstructionsLoaded, StopFailure. +Events only available in CLI (not yet in either SDK): WorktreeCreate, WorktreeRemove, PostCompact, InstructionsLoaded, StopFailure, PermissionDenied (CC 2.1.88). 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 index 0aaf27b..7d6ed95 100644 --- a/plugins/plugin-dev/skills/hook-development/references/hook-input-schemas.md +++ b/plugins/plugin-dev/skills/hook-development/references/hook-input-schemas.md @@ -100,6 +100,8 @@ Every hook receives these fields: The `tool_input` object varies by tool. Common tool schemas: +> **CC 2.1.88:** The `file_path` field in PreToolUse/PostToolUse hooks for Write, Edit, and Read tools now provides **absolute paths**. Previously, paths could be relative. Hook scripts that process file paths should expect absolute paths. + | Tool | `tool_input` Fields | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bash | `command` (string), `description` (string, optional), `timeout` (number, optional), `run_in_background` (boolean, optional) | From 7768e5c72e86a66433781a80e603cfdd6a896cd8 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Wed, 1 Apr 2026 10:21:46 +1300 Subject: [PATCH 26/33] fix: tell changelog-differ to actually dispatch claude-code-guide The agent was preemptively skipping the third triangulation source without attempting the dispatch. claude-code-guide is a built-in Claude Code agent type and was registered in the CI session. --- plugins/plugin-dev/agents/changelog-differ.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/plugin-dev/agents/changelog-differ.md b/plugins/plugin-dev/agents/changelog-differ.md index d51e7eb..b494a5e 100644 --- a/plugins/plugin-dev/agents/changelog-differ.md +++ b/plugins/plugin-dev/agents/changelog-differ.md @@ -52,9 +52,9 @@ Extract entries for the same version range. This source is more structured (incl ### Step 3: Cross-Reference with Official Docs -Dispatch the `claude-code-guide` subagent type to cross-reference significant changes against official documentation. This catches features the changelogs understate or omit. +Dispatch an Agent with `subagent_type: "claude-code-guide"` to cross-reference significant changes against official documentation. This is a built-in Claude Code agent type — it IS available, so always attempt the dispatch. Pass it a prompt listing the changes found in Steps 1-2 and ask it to verify them against official docs. -If the `claude-code-guide` subagent type is unavailable, skip this step and note in the manifest that triangulation is degraded to two sources. +Only if the dispatch fails with an error should you note degraded triangulation in the manifest. ### Step 4: Classify Changes From 192c299b36bdd200d0217276968e441768b08cc9 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Wed, 1 Apr 2026 16:15:40 +1300 Subject: [PATCH 27/33] chore: remove community-oriented CI workflows Solo-maintained repo doesn't need greet, stale, semantic-labeler, ci-failure-analysis, claude-pr-review, or markdownlint workflows. Simplify links.yml (drop auto-issue creation), clean up markdownlint references from docs and remaining workflows. --- .github/LABELS.md | 33 ----- .github/pull_request_template.md | 5 +- .github/workflows/ci-failure-analysis.yml | 155 ---------------------- .github/workflows/claude-pr-review.yml | 127 ------------------ .github/workflows/claude.yml | 4 +- .github/workflows/greet.yml | 45 ------- .github/workflows/links.yml | 35 ----- .github/workflows/markdownlint.yml | 34 ----- .github/workflows/semantic-labeler.yml | 143 -------------------- .github/workflows/stale.yml | 46 ------- .github/workflows/upstream-sync.yml | 16 --- .markdownlint.json | 48 ------- .markdownlintignore | 7 - CLAUDE.md | 3 - CONTRIBUTING.md | 15 +-- README.md | 3 +- SECURITY.md | 3 +- docs/ci-cd.md | 16 +-- 18 files changed, 12 insertions(+), 726 deletions(-) delete mode 100644 .github/workflows/ci-failure-analysis.yml delete mode 100644 .github/workflows/claude-pr-review.yml delete mode 100644 .github/workflows/greet.yml delete mode 100644 .github/workflows/markdownlint.yml delete mode 100644 .github/workflows/semantic-labeler.yml delete mode 100644 .github/workflows/stale.yml delete mode 100644 .markdownlint.json delete mode 100644 .markdownlintignore diff --git a/.github/LABELS.md b/.github/LABELS.md index dc0d087..628fe17 100644 --- a/.github/LABELS.md +++ b/.github/LABELS.md @@ -7,7 +7,6 @@ This document describes the label system for plugin-dev. - **labels.yml**: Source of truth for all repository labels - **LABELS.md**: This documentation file - **workflows/sync-labels.yml**: Automated workflow that syncs label definitions on push to main -- **workflows/semantic-labeler.yml**: Claude-powered workflow that applies labels to issues and PRs ## Label Categories @@ -164,38 +163,6 @@ Common label combinations for plugin-dev: | Plugin architecture design | `enhancement`, `status:needs-design`, `roadmap` | | Dependabot PR | `chore`, `dependencies`, `effort:small` | -## Automatic Label Application - -Labels are automatically applied to issues and PRs using Claude-powered semantic analysis. - -### How It Works - -The `semantic-labeler.yml` workflow: - -- **Triggers on**: Issues (opened, edited) and PRs (opened, synchronize, edited) -- **Analyzes**: Title, body, and for PRs, the diff -- **Applies**: Type, component, priority, effort, and impact labels - -### Labels Applied Automatically - -| Category | Labels | Required | -| --------- | ---------------------------------------------------------- | ------------- | -| Type | bug, enhancement, documentation, question, refactor, chore | Yes (one) | -| Component | component:\*, github-actions, dependencies | If applicable | -| Scope | scope:triggering, scope:validation | If applicable | -| Priority | priority:critical/high/medium/low | Yes (one) | -| Effort | effort:small/medium/large | Yes (one) | -| Impact | breaking, security | If applicable | -| Community | good first issue, help wanted | If applicable | - -### Skipped Cases - -The workflow skips: - -- Bot-created issues/PRs (dependabot, claude) -- Draft PRs -- Fork PRs (for security - secrets not exposed) - ## Managing Labels ### Adding a New Label diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e253e1c..154ec80 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,7 +13,7 @@ - [ ] Refactoring (code change that neither fixes a bug nor adds a feature) - [ ] Chore (maintenance tasks: dependencies, CI, tooling) - [ ] Test (adding or updating tests) -- [ ] Configuration change (changes to .markdownlint.json, plugin.json, etc.) +- [ ] Configuration change (changes to plugin.json, etc.) ## Component(s) Affected @@ -25,7 +25,7 @@ - [ ] Hooks (event-driven automation) - [ ] Marketplace (marketplace.json, distribution) - [ ] Documentation (README.md, CLAUDE.md, SECURITY.md) -- [ ] Configuration (.markdownlint.json, plugin.json) +- [ ] Configuration (plugin.json) - [ ] Issue/PR templates - [ ] Other (please specify): @@ -75,7 +75,6 @@ Fixes # ### Markdown -- [ ] I have run `markdownlint` and fixed all issues - [ ] My markdown follows the repository style (ATX headers, dash lists, fenced code blocks) - [ ] I have verified special HTML elements are properly closed (`

`, ``, ``, ``) diff --git a/.github/workflows/ci-failure-analysis.yml b/.github/workflows/ci-failure-analysis.yml deleted file mode 100644 index 232f796..0000000 --- a/.github/workflows/ci-failure-analysis.yml +++ /dev/null @@ -1,155 +0,0 @@ -name: CI Failure Analysis - -# Automatically analyze failed CI runs and provide actionable fix suggestions -# Triggers when Markdown Lint, Check Links, or Validate Workflows fail -# -# Testing: Intentionally fail markdownlint (e.g., change - to * in any .md file) - -on: - workflow_run: - workflows: - - "Markdown Lint" - - "Check Links" - - "Validate Workflows" - types: [completed] - -# Cancel in-progress analysis for same workflow run -concurrency: - group: ${{ github.workflow }}-${{ github.event.workflow_run.id }} - cancel-in-progress: true - -jobs: - analyze-failure: - name: Analyze CI Failure - # Only run on failure, skip bot triggers to prevent loops - if: | - github.event.workflow_run.conclusion == 'failure' && - github.event.workflow_run.actor.login != 'dependabot[bot]' && - github.event.workflow_run.actor.login != 'claude[bot]' - runs-on: ubuntu-latest - timeout-minutes: 10 - permissions: - contents: read - pull-requests: write - actions: read - id-token: write - - steps: - - name: Analyze failure with Claude - uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34 - with: - claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} - prompt: | - A CI workflow has failed. Analyze the failure and help the developer fix it. - - ## Failed Workflow Details - - - **Workflow**: ${{ github.event.workflow_run.name }} - - **Run ID**: ${{ github.event.workflow_run.id }} - - **Run URL**: ${{ github.event.workflow_run.html_url }} - - **Commit SHA**: ${{ github.event.workflow_run.head_sha }} - - **Branch**: ${{ github.event.workflow_run.head_branch }} - - **Actor**: ${{ github.event.workflow_run.actor.login }} - - **Repository**: ${{ github.repository }} - - ## Instructions - - ### Step 1: Get the failure logs - - First, download and examine the workflow run logs: - - ```bash - gh run view ${{ github.event.workflow_run.id }} --log - ``` - - If that's too verbose, get the job summary first: - - ```bash - gh run view ${{ github.event.workflow_run.id }} --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name: .name, conclusion: .conclusion}' - ``` - - ### Step 2: Analyze the failure - - Based on which workflow failed, look for specific error patterns: - - **For "Markdown Lint" failures:** - - Look for lines like: `filename:line:column MD00X/rule-name message` - - Common issues: wrong list style (should use `-`), wrong header style (should use ATX `#`) - - **For "Check Links" (lychee) failures:** - - Look for broken URLs with HTTP status codes (404, 403, etc.) - - Check if the URL has moved or if it's a false positive - - **For "Validate Workflows" (actionlint) failures:** - - Look for YAML syntax errors or invalid workflow configurations - - Check for missing required fields, invalid expressions, or deprecated syntax - - ### Step 3: Find the associated PR - - Try to find the pull request associated with this commit: - - ```bash - gh pr list --search "${{ github.event.workflow_run.head_sha }}" --state open --json number,title,url --jq '.[0]' - ``` - - If no PR is found (e.g., push to main), note this - you won't be able to comment. - - ### Step 4: Post analysis comment - - If a PR was found, post a helpful comment with your analysis. The comment should include: - - 1. **Summary**: What failed and why (1-2 sentences) - 2. **Failures Found**: List each error with file, line, and explanation - 3. **How to Fix**: Specific commands or code changes - - Use this format for the comment: - - ```markdown - ## ❌ CI Failure Analysis: {Workflow Name} - - **Run**: [#{run_id}]({run_url}) - **Commit**: `{sha:7}` - - ### Summary - - {Brief explanation of what failed} - - ### Failures Found - - | File | Line | Issue | - |------|------|-------| - | `{file}` | {line} | {description} | - - ### How to Fix - - {For markdown failures} - **Option 1**: Auto-fix with markdownlint - ```bash - markdownlint "{file}" --fix - ``` - - **Option 2**: Manual fix - {Explain specific change needed} - - {For link failures} - - Check if URL has moved and update the link - - Or add to `.lycheeignore` if the link is expected to fail in CI - - {For workflow validation failures} - - Show corrected YAML syntax - - --- - 🤖 Analyzed by [Claude](https://claude.ai/code) - ``` - - Post the comment using: - ```bash - gh pr comment {pr_number} --body "..." - ``` - - ### Step 5: Report outcome - - After posting (or if no PR found), summarize what you found and what action was taken. - - claude_args: | - --allowedTools "Bash(gh run:*),Bash(gh pr:*)" diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml deleted file mode 100644 index 780cb4d..0000000 --- a/.github/workflows/claude-pr-review.yml +++ /dev/null @@ -1,127 +0,0 @@ -# yamllint disable rule:line-length -name: Claude Automated PR Review - -on: - # Using pull_request (not pull_request_target) for security: - # - pull_request_target exposes secrets to fork PRs, creating exfiltration risk - # - For fork PRs needing review, maintainers can manually @claude via claude.yml - pull_request: - types: [opened, synchronize, ready_for_review, reopened] - -# Cancel any in-progress review for the same PR when new commits are pushed -concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number }} - cancel-in-progress: true - -jobs: - review: - # Skip bots and draft PRs - if: | - github.actor != 'dependabot[bot]' && - github.actor != 'claude[bot]' && - github.event.pull_request.draft == false - runs-on: ubuntu-latest - timeout-minutes: 10 - permissions: - contents: read - pull-requests: write - issues: write # Required by claude-code-action for PR comments (GitHub API treats PR comments as issue comments) - id-token: write - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - fetch-depth: 1 - persist-credentials: false - - - name: Setup Node.js - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0 - with: - node-version-file: ".nvmrc" - - - name: Cache npm tools - uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2 - id: claude-pr-review-npm-tools-cache - with: - path: ~/.npm - key: ${{ runner.os }}-npm-lint-tools-v1 - - - name: Install linting tools - if: steps.claude-pr-review-npm-tools-cache.outputs.cache-hit != 'true' - run: npm install -g markdownlint-cli2 prettier - - - name: Review PR with Claude - uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34 - with: - claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} - track_progress: true - prompt: | - Review this pull request for the plugin-dev Claude Code plugin. - - ## Context - - Repository: ${{ github.repository }} - - PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }} - - Author: ${{ github.event.pull_request.user.login }} - - Base: ${{ github.event.pull_request.base.ref }} - - Dependencies: markdownlint-cli2 and prettier are pre-installed globally - - > **Note**: The `component-validation` workflow runs in parallel and validates plugin component - > structure (frontmatter fields, JSON schema, etc.). Focus your review on content quality, - > best practices, and issues beyond structural validation. - - ## Instructions - - ### Step 1: Run Quality Checks - Run these checks and note any failures: - - `markdownlint-cli2 ` - Markdown style issues - - `prettier --check ` - Formatting issues - - `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh` - Shell script issues (if scripts changed) - - ### Step 2: Review the Diff - Run `gh pr diff ${{ github.event.pull_request.number }}` to see all changes. - - ### Step 3: Provide Feedback - - **For specific line-level issues**, use inline comments. Target: - - Missing or invalid YAML frontmatter fields - - Imperative voice violations in commands ("You should" instead of "Do") - - Missing trigger phrases in skill descriptions - - `` block formatting issues in agents - - Shell script issues (shellcheck findings) - - Security concerns - - **For general observations**, post a summary comment. - - ## Review Criteria - - ### Plugin Components (if changed) - - **Commands** (`commands/*.md`): Verify YAML frontmatter has name, description, allowed-tools. Check for imperative voice ("Do X" not "You should do X"). - - **Skills** (`skills/*/SKILL.md`): Check trigger phrases in description, progressive disclosure pattern (name and description required in frontmatter; version is optional). - - **Agents** (`agents/*.md`): Verify blocks for triggering, appropriate tool restrictions. - - **Hooks** (`hooks/hooks.json`): Validate event types and matcher patterns. - - ### Shell Scripts (if changed) - - Run shellcheck on any changed `.sh` files in `plugins/plugin-dev/skills/*/scripts/` - - Flag any shellcheck errors or warnings - - ### Markdown Quality - Key markdown rules enforced: - - ATX-style headers (`#` not underlines) - - Dash-style lists (`-` not `*` or `+`) - - 2-space indentation for nested lists - - Fenced code blocks (not indented) - - ### Documentation - - README.md updates if user-facing changes - - CLAUDE.md updates if development process changes - - ## Output Format - 1. Post inline comments for specific issues found in the diff - 2. Post a summary comment with: - - **Verdict**: ✅ Looks good / ⚠️ Needs changes / 🔍 Has concerns - - **Quality Checks**: Results from markdownlint, prettier, shellcheck (pass/fail with details) - - **What's Good**: Positive aspects of the PR - - **Suggestions**: General improvements (not covered by inline comments) - - Be constructive and helpful. Focus on significant issues, not nitpicks. - claude_args: '--model claude-opus-4-5-20251101 --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr comment:*),Bash(markdownlint-cli2:*),Bash(prettier:*),Bash(shellcheck:*),Read,Glob,Grep"' diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 0117543..ba9ea73 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -72,7 +72,7 @@ jobs: - name: Install linting tools if: steps.at-claude-npm-tools-cache.outputs.cache-hit != 'true' - run: npm install -g markdownlint-cli2 prettier + run: npm install -g prettier - name: Run Claude Code id: claude @@ -85,4 +85,4 @@ jobs: actions: read claude_args: | --model claude-opus-4-5-20251101 - --allowedTools "Read,Edit,Write,Glob,Grep,Task,Bash(gh pr:*),Bash(gh issue:*),Bash(gh run:*),Bash(gh release:*),Bash(markdownlint-cli2:*),Bash(prettier:*),Bash(shellcheck:*),mcp__github_inline_comment__create_inline_comment,mcp__github_ci__get_ci_status,mcp__github_ci__download_job_log" + --allowedTools "Read,Edit,Write,Glob,Grep,Task,Bash(gh pr:*),Bash(gh issue:*),Bash(gh run:*),Bash(gh release:*),Bash(prettier:*),Bash(shellcheck:*),mcp__github_inline_comment__create_inline_comment,mcp__github_ci__get_ci_status,mcp__github_ci__download_job_log" diff --git a/.github/workflows/greet.yml b/.github/workflows/greet.yml deleted file mode 100644 index 1e289a4..0000000 --- a/.github/workflows/greet.yml +++ /dev/null @@ -1,45 +0,0 @@ -name: Greet First Time Contributors - -on: - pull_request_target: - types: [opened] - issues: - types: [opened] - -# Group by PR/issue number to prevent overlapping greetings for same item -# cancel-in-progress: false ensures all first-timers get greeted -concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number || github.ref }} - cancel-in-progress: false - -jobs: - greeting: - # Skip bot accounts to avoid greeting automated tools - if: github.actor != 'dependabot[bot]' && github.actor != 'claude[bot]' - runs-on: ubuntu-latest - timeout-minutes: 5 - permissions: - issues: write - pull-requests: write - steps: - - uses: actions/first-interaction@1c4688942c71f71d4f5502a26ea67c331730fa4d # v3.1.0 - with: - issue_message: | - Thanks for opening your first issue! 👋 We appreciate your contribution to plugin-dev. - - **Resources:** - - [Contributing Guide](CONTRIBUTING.md) - - [Code of Conduct](CODE_OF_CONDUCT.md) - - Please ensure you've provided all the requested information in the issue template. - Our maintainers will review this soon! - pr_message: | - Thanks for opening your first pull request! 🎉 We appreciate your contribution to plugin-dev. - - **Before merge, please ensure:** - - [ ] You've read our [Contributing Guide](CONTRIBUTING.md) - - [ ] All markdown is properly linted (`markdownlint '**/*.md' --ignore node_modules`) - - [ ] Shell scripts pass validation (`shellcheck plugins/plugin-dev/skills/*/scripts/*.sh`) - - [ ] You've tested the changes locally with `claude --plugin-dir plugins/plugin-dev` - - A maintainer will review your PR soon. Feel free to ask questions if you need help! diff --git a/.github/workflows/links.yml b/.github/workflows/links.yml index 1c5d576..47c868a 100644 --- a/.github/workflows/links.yml +++ b/.github/workflows/links.yml @@ -20,7 +20,6 @@ concurrency: permissions: contents: read - issues: write # Required for creating issue on failure jobs: linkChecker: @@ -62,37 +61,3 @@ jobs: with: path: .lycheecache key: cache-lychee-v1 - - # Check for existing issue to avoid duplicates, then create or comment - - name: Check for existing open issue - if: failure() - id: check-issue - run: | - issue=$(gh issue list --state open \ - --search "in:title Broken links detected" \ - --json number --jq '.[0].number // empty') - echo "issue_number=$issue" >> "$GITHUB_OUTPUT" - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - name: Create issue for broken links - if: failure() && steps.check-issue.outputs.issue_number == '' - run: gh issue create --title "Broken links detected" --body-file ./lychee/out.md - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - name: Comment on existing issue - if: failure() && steps.check-issue.outputs.issue_number != '' - run: | - run_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${RUN_ID}" - { - echo "## 🔄 Link check failed again" - echo "" - echo "**Run**: [${RUN_ID}](${run_url})" - echo "**Triggered by**: ${GITHUB_EVENT_NAME}" - echo "" - cat ./lychee/out.md - } | gh issue comment "${{ steps.check-issue.outputs.issue_number }}" --body-file - - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - RUN_ID: ${{ github.run_id }} diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml deleted file mode 100644 index a994602..0000000 --- a/.github/workflows/markdownlint.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: Markdown Lint - -on: - pull_request: - paths: - - "**.md" - - ".markdownlint.json" - push: - branches: - - main - paths: - - "**.md" - - ".markdownlint.json" - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read - -jobs: - lint: - name: Lint Markdown Files - runs-on: ubuntu-latest - timeout-minutes: 5 - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - persist-credentials: false - - - name: Run markdownlint - run: npx markdownlint-cli2@0.20.0 "**/*.md" "#node_modules" diff --git a/.github/workflows/semantic-labeler.yml b/.github/workflows/semantic-labeler.yml deleted file mode 100644 index e9f9b3f..0000000 --- a/.github/workflows/semantic-labeler.yml +++ /dev/null @@ -1,143 +0,0 @@ -# yamllint disable rule:line-length -name: Semantic Labeler - -# Claude-powered semantic labeling for both issues and PRs -# Replaces the path-based labeler with content-aware categorization - -on: - issues: - types: [opened, edited] - pull_request: - types: [opened, synchronize, edited] - -# Cancel in-progress runs on subsequent triggers -concurrency: - group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number }} - cancel-in-progress: true - -jobs: - label-issue: - name: Label Issue - # Skip bot-created issues to prevent potential loops - if: | - github.event_name == 'issues' && - github.actor != 'dependabot[bot]' && - github.actor != 'claude[bot]' - runs-on: ubuntu-latest - timeout-minutes: 5 - permissions: - contents: read - issues: write - id-token: write - actions: read - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - fetch-depth: 1 - persist-credentials: false - - - name: Label issue with Claude - id: labeler - uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34 - with: - claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} - prompt: | - Label GitHub issue #${{ github.event.issue.number }}. - - **Title**: ${{ github.event.issue.title }} - **Author**: ${{ github.event.issue.user.login }} - **Body**: - ${{ github.event.issue.body }} - - ## Instructions - - 1. **Get available labels**: `gh label list --json name,description -q '.[] | "\(.name): \(.description)"'` - 2. **Get current labels**: `gh issue view ${{ github.event.issue.number }} --json labels -q '.labels[].name'` - 3. **Analyze** the issue content and determine appropriate labels - 4. **Apply labels** using `gh issue edit`, removing conflicting mutually-exclusive labels first - - ## Label Rules (see .github/LABELS.md for full details) - - **Required (exactly ONE each):** - - TYPE: bug | enhancement | documentation | question | refactor | chore - - PRIORITY: priority:critical | priority:high | priority:medium | priority:low - - EFFORT: effort:small | effort:medium | effort:large - - **Contextual (apply only if clearly relevant):** - - COMPONENT: component:skill | component:agent | component:command | component:hook | component:docs | github-actions - - SPECIAL: breaking | security - - COMMUNITY: help wanted | good first issue (only if clearly appropriate) - - ## Execution - - For mutually exclusive categories (type, priority, effort), remove existing labels before adding new ones: - ```bash - gh issue edit ${{ github.event.issue.number }} --remove-label "priority:low" --add-label "priority:high,bug,effort:medium" - ``` - - After applying labels, briefly explain your reasoning. - claude_args: '--model claude-opus-4-5-20251101 --allowedTools "Bash(gh label:*),Bash(gh issue:*)"' - - label-pr: - name: Label Pull Request - if: | - github.event_name == 'pull_request' && - github.actor != 'dependabot[bot]' && - github.actor != 'claude[bot]' && - github.event.pull_request.draft == false - runs-on: ubuntu-latest - timeout-minutes: 5 - permissions: - contents: read - pull-requests: write - id-token: write - actions: read - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - fetch-depth: 1 - persist-credentials: false - - - name: Label PR with Claude - id: labeler - uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34 - with: - claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} - prompt: | - Label pull request #${{ github.event.pull_request.number }}. - - **Title**: ${{ github.event.pull_request.title }} - **Author**: ${{ github.event.pull_request.user.login }} - **Description**: - ${{ github.event.pull_request.body }} - - ## Instructions - - 1. **Get available labels**: `gh label list --json name,description -q '.[] | "\(.name): \(.description)"'` - 2. **Get current labels**: `gh pr view ${{ github.event.pull_request.number }} --json labels -q '.labels[].name'` - 3. **Get the PR diff** to understand what changed: `gh pr diff ${{ github.event.pull_request.number }}` - 4. **Read key modified files** to understand context - use Read and Glob tools to examine important changed files in detail - 5. **Analyze** the changes and determine appropriate labels - 6. **Apply labels** using `gh pr edit`, removing conflicting mutually-exclusive labels first - - ## Label Rules (see .github/LABELS.md for full details) - - **Required (exactly ONE each):** - - TYPE (based on nature of changes): bug | enhancement | documentation | refactor | chore - - EFFORT (based on diff size/complexity): effort:small | effort:medium | effort:large - - **Contextual (apply based on files changed):** - - COMPONENT: component:skill (skills/**) | component:agent (agents/**) | component:command (commands/**) | component:hook (hooks/**) | component:docs (*.md, .github/**/*.md) | github-actions (.github/workflows/**) - - SPECIAL: breaking | security - - ## Execution - - For mutually exclusive categories (type, effort), remove existing labels before adding new ones: - ```bash - gh pr edit ${{ github.event.pull_request.number }} --remove-label "effort:small" --add-label "effort:medium,enhancement,component:skill" - ``` - - After applying labels, briefly explain your reasoning. - claude_args: '--model claude-opus-4-5-20251101 --allowedTools "Bash(gh label:*),Bash(gh pr:*),Read,Glob"' diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml deleted file mode 100644 index bb70b89..0000000 --- a/.github/workflows/stale.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Manage Stale Issues and PRs - -on: - schedule: - - cron: "0 0 * * 1,3,5" # Mon/Wed/Fri at midnight UTC - workflow_dispatch: - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - issues: write - pull-requests: write - -jobs: - stale: - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1 - with: - stale-issue-message: >- - This issue has been automatically marked as stale because it has - not had recent activity. It will be closed if no further activity - occurs. Thank you for your contributions. - stale-pr-message: >- - This PR has been automatically marked as stale because it has not - had recent activity. It will be closed if no further activity - occurs. - close-issue-message: >- - This issue was closed because it has been stale for 7 days with - no activity. - close-pr-message: >- - This PR was closed because it has been stale for 7 days with no - activity. - days-before-stale: 60 - days-before-close: 7 - stale-issue-label: "stale" - stale-pr-label: "stale" - exempt-issue-labels: "pinned,security,roadmap,bug,priority:critical,status:in-progress,status:blocked" - exempt-pr-labels: "pinned,security,status:in-progress,status:blocked" - exempt-all-issue-assignees: true - exempt-draft-pr: true - operations-per-run: 100 - enable-statistics: true diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml index 19e1971..93ec5ec 100644 --- a/.github/workflows/upstream-sync.yml +++ b/.github/workflows/upstream-sync.yml @@ -32,22 +32,6 @@ jobs: repository: Piebald-AI/claude-code-system-prompts path: claude-code-system-prompts - - name: Setup Node.js - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0 - with: - node-version: 22 - - - name: Cache npm tools - uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2 - id: npm-tools-cache - with: - path: ~/.npm - key: ${{ runner.os }}-npm-lint-tools-v1 - - - name: Install linting tools - if: steps.npm-tools-cache.outputs.cache-hit != 'true' - run: npm install -g markdownlint-cli2 - - name: Run upstream sync uses: anthropics/claude-code-action@f64219702d7454cf29fe32a74104be6ed43dc637 # v1.0.34 with: diff --git a/.markdownlint.json b/.markdownlint.json deleted file mode 100644 index e6c0ae7..0000000 --- a/.markdownlint.json +++ /dev/null @@ -1,48 +0,0 @@ -{ - "default": true, - "MD001": true, - "MD003": { - "style": "atx" - }, - "MD004": { - "style": "dash" - }, - "MD007": { - "indent": 2 - }, - "MD013": false, - "MD024": { - "siblings_only": true - }, - "MD025": true, - "MD026": { - "punctuation": ".,;:!" - }, - "MD029": false, - "MD031": false, - "MD032": false, - "MD033": { - "allowed_elements": [ - "p", - "img", - "example", - "commentary", - "details", - "summary", - "strong" - ] - }, - "MD034": true, - "MD040": false, - "MD041": false, - "MD046": { - "style": "fenced" - }, - "MD049": { - "style": "underscore" - }, - "MD050": { - "style": "asterisk" - }, - "MD060": false -} diff --git a/.markdownlintignore b/.markdownlintignore deleted file mode 100644 index aa45660..0000000 --- a/.markdownlintignore +++ /dev/null @@ -1,7 +0,0 @@ -# Ignore - -node_modules/ -dist/ -build/ -.git/ -CODE_OF_CONDUCT.md diff --git a/CLAUDE.md b/CLAUDE.md index dadab38..f557ed9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,9 +50,6 @@ This repo has TWO `.claude-plugin/` directories: # Test plugin locally claude --plugin-dir plugins/plugin-dev -# Lint markdown -markdownlint '**/*.md' --ignore node_modules - # Lint shell scripts shellcheck plugins/plugin-dev/skills/*/scripts/*.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac79225..730291c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,10 +32,8 @@ Before contributing, ensure you have: gh auth login ``` - **Git**: For version control -- **markdownlint-cli2** and **prettier**: For linting (should be available globally) +- **prettier**: For formatting (should be available globally) ```bash - # Verify they're installed - markdownlint-cli2 --version prettier --version ``` @@ -138,9 +136,6 @@ gh auth status # Should show logged in with 'repo' and 'project' scopes All markdown files must follow the repository's style: ```bash -# Lint before committing -markdownlint-cli2 '**/*.md' - # Format with prettier prettier --check '**/*.md' prettier --write '**/*.md' # fix formatting issues @@ -155,7 +150,7 @@ GitHub Actions workflows must pass YAML linting: uvx yamllint .github/workflows/ ``` -**Style Rules** (see `.markdownlint.json`): +**Style Rules**: - Use ATX-style headers (`#`, `##`, `###`) - Use dash-style lists (`-`, not `*` or `+`) @@ -384,9 +379,6 @@ gh repo delete test-plugin-repo --yes ### 2. Lint Your Code ```bash -# Lint all markdown -markdownlint-cli2 '**/*.md' - # Format with prettier prettier --write '**/*.md' ``` @@ -424,7 +416,6 @@ See [pull_request_template.md](.github/pull_request_template.md) for the complet - [ ] Code follows style guidelines - [ ] Documentation updated -- [ ] Markdown linted - [ ] Tested locally - [ ] Component-specific checks completed - [ ] No breaking changes (or clearly documented) @@ -435,12 +426,10 @@ 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. diff --git a/README.md b/README.md index 38f618e..946826f 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,6 @@ # Plugin Development Toolkit [![CI](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/component-validation.yml/badge.svg)](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/component-validation.yml) -[![Markdown](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/markdownlint.yml/badge.svg)](https://github.com/kylesnowschwartz/plugin-dev/actions/workflows/markdownlint.yml) [![Version](https://img.shields.io/github/v/release/kylesnowschwartz/plugin-dev?label=version&color=blue)](https://github.com/kylesnowschwartz/plugin-dev/releases) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) @@ -392,7 +391,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-cli2 '**/*.md'` and `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh` +4. Run linters: `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh` 5. Create a PR with your changes ## Getting Help diff --git a/SECURITY.md b/SECURITY.md index ac4961e..168f427 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -73,8 +73,7 @@ When a security vulnerability is confirmed: 1. **No Secrets in Code**: Never commit API keys, tokens, or credentials 2. **Dependencies**: Keep dependencies minimal (this plugin has only GitHub CLI as external dependency) 3. **Code Review**: All changes go through pull request review -4. **Markdown Linting**: Run `markdownlint` before committing to catch potential issues -5. **Test Locally**: Always test with `claude --plugin-dir plugins/plugin-dev` before pushing +4. **Test Locally**: Always test with `claude --plugin-dir plugins/plugin-dev` before pushing ## Known Security Mitigations diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 5df53a4..c1e35e5 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -6,28 +6,22 @@ Documentation for GitHub Actions workflows, labels, and templates. | Workflow | Trigger | Purpose | | -------------------------- | ------------------------------ | -------------------------- | -| `markdownlint.yml` | `**.md` changed | Lint markdown files | | `links.yml` | `**.md` changed | Check for broken links | | `component-validation.yml` | Plugin components changed | Validate plugin components | | `version-check.yml` | Version files changed | Ensure version consistency | | `validate-workflows.yml` | `.github/workflows/**` changed | Lint GitHub Actions | | `yaml-lint.yml` | `.github/workflows/**` changed | Lint YAML files | -| `claude-pr-review.yml` | All PRs (non-draft) | AI-powered code review | ## Scheduled Workflows -| Workflow | Schedule | Purpose | -| --------------------- | ----------------- | ---------------------------------------------- | -| `upstream-sync.yml` | Every 3 days | Sync plugin-dev docs with Claude Code releases | -| `stale.yml` | Mon/Wed/Fri | Manages stale issues/PRs | +| Workflow | Schedule | Purpose | +| ------------------- | ------------ | --------------------------------------------- | +| `upstream-sync.yml` | Every 3 days | Sync plugin-dev docs with Claude Code releases | ## Other Workflows -- `claude.yml` - Main Claude Code workflow -- `semantic-labeler.yml` - Auto-labels issues/PRs -- `ci-failure-analysis.yml` - Analyzes CI failures +- `claude.yml` - On-demand `@claude` in issues/PRs - `sync-labels.yml` - Synchronizes repository labels -- `greet.yml` - Greets new contributors ## Labels @@ -40,8 +34,6 @@ Issues and PRs use a structured labeling system defined in `.github/labels.yml`: | Status | `status:*` | `status:blocked`, `status:in-progress`, `status:needs-review` | | Effort | `effort:*` | `effort:small` (<1h), `effort:medium` (1-4h), `effort:large` (>4h) | -The `semantic-labeler.yml` workflow auto-labels PRs based on file paths changed. - ## Issue & PR Templates The repository includes templates in `.github/`: From fd8715e74a976155467d93afcd9f540a00d6a937 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 4 Apr 2026 06:43:35 +0000 Subject: [PATCH 28/33] feat: sync plugin-dev with Claude Code v2.1.89-v2.1.92 Document new Claude Code features from versions 2.1.89 through 2.1.92: - hook-development: PreToolUse `defer` permission decision for pausing tool execution in headless sessions (CC 2.1.89) - mcp-integration: `_meta["anthropic/maxResultSizeChars"]` annotation for large MCP tool results up to 500K characters (CC 2.1.91) - skill-development/command-development: `disableSkillShellExecution` setting for organizations to disable inline shell execution (CC 2.1.91) - plugin-structure: Plugin `bin/` directory for shipping executables that can be invoked as bare commands (CC 2.1.91) Verified via four-stage update-from-upstream pipeline with independent verification agents. Co-Authored-By: Claude Opus 4.5 --- .agent-history/upstream-changes.md | 329 +++++++++--------- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 13 +- CLAUDE.md | 2 +- docs/claude-code-compatibility.md | 5 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../skills/command-development/SKILL.md | 2 + .../skills/hook-development/SKILL.md | 4 +- .../skills/mcp-integration/SKILL.md | 11 + .../skills/plugin-structure/SKILL.md | 37 ++ .../skills/skill-development/SKILL.md | 2 + 11 files changed, 231 insertions(+), 180 deletions(-) diff --git a/.agent-history/upstream-changes.md b/.agent-history/upstream-changes.md index 64483d3..a700dca 100644 --- a/.agent-history/upstream-changes.md +++ b/.agent-history/upstream-changes.md @@ -1,217 +1,202 @@ # Upstream Change Manifest -## CC Version Range: 2.1.87 - 2.1.88 -## Generated: 2026-03-31 -## Sources: changelog [x], system-prompts [x], claude-code-guide [skipped] - -Note: claude-code-guide subagent not available in this environment. Triangulation degraded to two sources. +## CC Version Range: 2.1.89 - 2.1.92 +## Generated: 2026-04-04 +## Sources: changelog [OK], system-prompts [OK], claude-code-guide [failed - agent not available in CI] --- ### Must Update -- [ ] **NEW: Config tool added** (CC 2.1.88) - - Source: system-prompts - - Confidence: high - - Affects: agent-development skill (tool references) - - Details: New tool for getting and setting Claude Code configuration settings. Plugin-dev documentation should be updated to include this new tool in tool references and agent toolset descriptions. - - Raw: "**NEW:** Tool Description: Config - Added tool for getting and setting Claude Code configuration settings." - -- [ ] **TeammateTool path changed** (CC 2.1.88) - - Source: system-prompts - - Confidence: high - - Affects: agent-development skill (teams section) - - Details: Team file path changed from `~/.claude/teams/{team-name}.json` to `~/.claude/teams/{team-name}/config.json`. Any documentation referencing team file locations needs updating. - - Raw: "Tool Description: TeammateTool - Updated the team file path from `~/.claude/teams/{team-name}.json` to `~/.claude/teams/{team-name}/config.json`." - -- [ ] **NEW: Partial compaction instructions** (CC 2.1.88) - - Source: system-prompts +- [ ] **PreToolUse hooks can return `"defer"` permission decision** (CC 2.1.89) + - Source: changelog, system-prompts (implied by deferred tool handling) - Confidence: high - - Affects: hook-development skill (PreCompact/PostCompact), skill-development skill (context management) - - Details: Added instructions for compacting only a portion of the conversation with a structured summary format. This is a new capability that may warrant documentation. - - Raw: "**NEW:** System Prompt: Partial compaction instructions - Added instructions for compacting only a portion of the conversation, with a structured summary format and analysis process." + - Affects: hook-development skill (SKILL.md line 322) + - Details: Headless sessions can now pause tool execution and resume later with `-p --resume`. The `defer` decision allows hooks to put tools on hold rather than immediately allowing or denying. This is a new permission decision type alongside `allow`, `deny`, and `ask`. + - Raw changelog: "Added `\"defer\"` permission decision to `PreToolUse` hooks -- headless sessions can pause and resume with `-p --resume`" + - Gap: SKILL.md line 322 shows `permissionDecision: "allow|deny|ask"` -- needs `defer` added -- [ ] **REMOVED: System section (tool permission mode)** (CC 2.1.88) - - Source: system-prompts +- [ ] **MCP tool result persistence override via `_meta` annotation** (CC 2.1.91) + - Source: changelog only - Confidence: high - - Affects: hook-development skill (terminology review) - - Details: Removed the system section describing tool permission mode behavior and denied tool call guidance. Any references to this in plugin-dev docs should be reviewed. - - Raw: "**REMOVED:** System Prompt: System section - Removed the system section describing tool permission mode behavior and denied tool call guidance." + - Affects: mcp-integration skill (SKILL.md MCP Output Limits section) + - Details: MCP servers can now return larger results (up to 500K characters) by setting `_meta["anthropic/maxResultSizeChars"]` in the tool result annotation. Useful for large database schemas or similar payloads. + - Raw changelog: "Added MCP tool result persistence override via `_meta[\"anthropic/maxResultSizeChars\"]` annotation (up to 500K)" + - Gap: Not documented in mcp-integration/SKILL.md -- [ ] **PreToolUse/PostToolUse file_path now absolute** (CC 2.1.88) - - Source: CC changelog (PROMOTED from No Action) +- [ ] **`disableSkillShellExecution` setting** (CC 2.1.91) + - Source: changelog only - Confidence: high - - Affects: hook-development skill (event-schemas.md, hook-input-schemas.md) - - Details: Fixed PreToolUse/PostToolUse hooks not providing `file_path` as an absolute path for Write/Edit/Read tools. Hook scripts that process file_path now receive absolute paths. This is a behavior change affecting hook script logic. - - Raw: "Fixed PreToolUse/PostToolUse hooks not providing `file_path` as an absolute path for Write/Edit/Read tools" + - Affects: skill-development skill (Dynamic Content section) and command-development skill + - Details: New setting that disables inline shell execution in skills, custom slash commands, and plugin commands. This is a security control for environments that want skills but not arbitrary shell execution. + - Raw changelog: "`disableSkillShellExecution` setting to disable inline shell execution in skills, custom slash commands, and plugin commands" + - Gap: Not documented in skill-development/SKILL.md or command-development/SKILL.md -- [ ] **NEW: PermissionDenied hook introduced** (CC 2.1.88) - - Source: CC changelog (PROMOTED from No Action) +- [ ] **Plugins can ship executables under `bin/` directory** (CC 2.1.91) + - Source: changelog only - Confidence: high - - Affects: hook-development skill (new hook event to document) - - Details: Introduced `PermissionDenied` hook that activates following auto mode classifier denials, allowing models to request retry via `{retry: true}` response. This is a NEW hook event (25th event) that must be added to hook-development documentation. - - Raw: "Introduced `PermissionDenied` hook that activates following auto mode classifier denials, allowing models to request retry via `{retry: true}` response" - -- [ ] **Hook `if` filtering fix for compound commands** (CC 2.1.88) - - Source: CC changelog (PROMOTED from No Action) - - Confidence: high - - Affects: hook-development skill (advanced.md, `if` field documentation) - - Details: Fixed hooks' `if` condition filtering to properly match compound commands like `ls && git push` and commands with environment variable prefixes such as `FOO=bar git push`. Existing documentation should note this behavior. - - Raw: "Fixed hooks' `if` condition filtering to properly match compound commands like `ls && git push` and commands with environment variable prefixes such as `FOO=bar git push`" + - Affects: plugin-structure skill (Directory Structure section) + - Details: Plugins can now include executables in a `bin/` subdirectory and invoke them as bare commands from the Bash tool. This enables plugins to ship compiled tools or scripts. + - Raw changelog: "Plugins can ship executables under `bin/` and invoke them as bare commands from Bash tool" + - Gap: Not documented in plugin-structure/SKILL.md --- ### May Update -- [ ] **Git status prompt simplified** (CC 2.1.88) - - Source: system-prompts - - Confidence: medium - - Affects: git-related skill examples - - Details: Stripped inline variable template (branch, status, recent commits); now contains only the introductory note that git status is a point-in-time snapshot. - - Raw: "System Prompt: Git status - Stripped the inline variable template (branch, status, recent commits); now contains only the introductory note that git status is a point-in-time snapshot." - -- [ ] **Fork usage guidelines updated** (CC 2.1.88) - - Source: system-prompts - - Confidence: medium - - Affects: agent documentation - - Details: Incorporated fork-specific prompt-writing guidance about writing directives that specify scope rather than re-explaining background. - - Raw: "System Prompt: Fork usage guidelines - Incorporated fork-specific prompt-writing guidance (previously in the subagent prompts section) about writing directives that specify scope rather than re-explaining background." - -- [ ] **Writing subagent prompts collapsed** (CC 2.1.88) - - Source: system-prompts - - Confidence: medium - - Affects: agent-creator skill - - Details: Collapsed separate context-inheriting vs fresh-agent sections into a single flow that defaults to fresh-agent briefing style with conditional notes for subagent types. - - Raw: "System Prompt: Writing subagent prompts - Collapsed the separate context-inheriting vs fresh-agent sections into a single flow that defaults to the fresh-agent briefing style, with conditional notes when a subagent type is present." - -- [ ] **Plan mode reminder conditional on agent availability** (CC 2.1.88) - - Source: system-prompts - - Confidence: medium - - Affects: plan-mode documentation - - Details: Subagent exploration suggestion is now conditional on whether agents are actually available. - - Raw: "System Reminder: Plan mode is active (iterative) - Made the subagent exploration suggestion conditional on whether agents are actually available, instead of always appending it." - -- [ ] **Agent tool prompt guidance moved** (CC 2.1.88) - - Source: system-prompts - - Confidence: medium - - Affects: agent-creator skill - - Details: Removed instruction to provide clear, detailed prompts for agents without subagent types (guidance now lives in fork/subagent prompt-writing sections). - - Raw: "Tool Description: Agent (usage notes) - Removed the instruction to provide clear, detailed prompts for agents without subagent types (guidance now lives in the fork/subagent prompt-writing sections)." +- [ ] **`MCP_CONNECTION_NONBLOCKING=true` env var** (CC 2.1.89) + - Source: changelog only + - Confidence: low + - Affects: mcp-integration skill (headless/CI mode patterns) + - Details: For `-p` mode, this env var skips waiting for MCP connections entirely. + - Raw changelog: "`MCP_CONNECTION_NONBLOCKING=true` for `-p` mode skips MCP connection wait entirely" -- [ ] **PowerShell tool description expanded** (CC 2.1.88) - - Source: system-prompts (DEMOTED from Must Update) +- [ ] **MCP tool truncation guidance updated** (CC 2.1.92) + - Source: system-prompts only - Confidence: medium - - Affects: Windows-specific documentation (none exists in plugin-dev) - - Details: Significantly expanded PowerShell syntax guidance. Windows-specific; no existing PowerShell documentation in plugin-dev to update. - - Raw: "Tool Description: PowerShell - Significantly expanded syntax guidance..." + - Affects: mcp-integration skill (subagent guidance) + - Details: Changed subagent file-reading guidance from "Read ALL of [file]" to instruct reading in sequential chunks using offset/limit until 100% of the file has been read, then summarizing. + - System-prompts: "System Prompt: MCP Tool Result Truncation -- Changed subagent file-reading guidance..." -- [ ] **NEW: PowerShell 5.1 system prompt** (CC 2.1.88) - - Source: system-prompts (DEMOTED from Must Update) - - Confidence: medium - - Affects: Windows-specific documentation (none exists in plugin-dev) - - Details: Added system prompt for Windows PowerShell 5.1. Windows-specific; no existing PowerShell documentation in plugin-dev. - - Raw: "**NEW:** System Prompt: PowerShell edition for 5.1..." +- [ ] **ReadFile tool supports relative paths** (CC 2.1.91) + - Source: system-prompts only + - Confidence: low + - Affects: skill script examples (minor style preference) + - Details: ReadFile now supports relative paths as a preferred alternative (for brevity) to absolute-path-only requirement. Line read limit and additional notes are now configurable. + - System-prompts: "Tool Description: ReadFile -- Added support for relative file paths (preferred for brevity)..." --- ### No Action -- v2.1.88: Flicker-free rendering via CLAUDE_CODE_NO_FLICKER=1 environment variable (UI/rendering) -- v2.1.88: Named subagents in mention suggestions (UI feature) -- v2.1.88: Fixed prompt cache issues in extended sessions (bug fix) -- v2.1.88: Fixed nested file re-injection in long conversations (bug fix) -- v2.1.88: Line-ending handling for Edit/Write tools on Windows (bug fix) -- v2.1.88: Structured output schema caching improvements (performance) -- v2.1.88: Memory leaks related to large JSON inputs (bug fix) -- v2.1.88: Rate-limit error messaging improvements (UX) -- v2.1.88: LSP server recovery after crashes (bug fix) -- v2.1.88: Voice mode fixes on macOS/Windows (platform-specific bug fix) -- v2.1.88: UI rendering artifacts and text truncation fixes (UI bug fix) -- v2.1.88: Prompt history corruption at 4KB boundaries fix (bug fix) -- v2.1.88: Statistics tracking historical data fix (bug fix) -- v2.1.88: Notification clearing and message synchronization (bug fix) -- v2.1.88: Verify skill substantially condensed (CC's built-in verify skill, not plugin-dev) -- v2.1.88: Ultraplan same-session implementation (internal CC feature, not plugin-dev relevant) -- v2.1.88: Plugin permission fix on macOS/Linux since v2.1.83 (bug fix) -- v2.1.87: No system prompt changes +**Demoted from Must Update (Stage 2 verification):** +- PermissionDenied hook fires after auto mode classifier denials (CC 2.1.89) -- already documented in hook-development/SKILL.md lines 385-423 +- `/tag` and `/vim` commands removed (CC 2.1.92) -- built-in commands, not plugin-dev scope +- Write tool guidance changed: always prefer Edit (CC 2.1.92) -- tool description, not plugin-dev scope +- Hook condition evaluator specialized for stop conditions (CC 2.1.92) -- internal implementation detail +- Sleep tool removed (CC 2.1.92) -- built-in tool, not plugin-dev scope +- Agent Design Patterns skill added (CC 2.1.91) -- built-in CC skill, not plugin-dev scope + +**Demoted from May Update (Stage 2 verification):** +- Named subagents in `@` mention typeahead (CC 2.1.89) -- UX feature, no plugin API impact +- `/powerup` command added (CC 2.1.90) -- built-in command, not plugin-dev scope +- `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` env var (CC 2.1.90) -- operational env var +- `.husky` added to protected directories (CC 2.1.90) -- permissions detail, not plugin-dev scope +- `forceRemoteSettingsRefresh` policy setting (CC 2.1.92) -- managed settings, not plugin-dev scope +- Edit tool guidelines made configurable (CC 2.1.91) -- not plugin-dev scope +- Computer Use MCP skill added (CC 2.1.89) -- built-in CC skill +- Remote plan mode (ultraplan) prompt added (CC 2.1.89) -- built-in CC feature +- Buddy Mode prompt added (CC 2.1.89) -- built-in CC feature +- Security monitor prompt significantly expanded (CC 2.1.89-2.1.90) -- internal security + +**Original No Action items:** +- Fix for rate-limit options dialog infinite loop (CC 2.1.90) +- Subagent spawning fix after tmux window changes (CC 2.1.92) +- Stop hooks fix for small fast model `ok:false` (CC 2.1.92) +- Tool input validation fixes for streaming (CC 2.1.92) +- API 400 error fix for whitespace-only thinking blocks (CC 2.1.92) +- Write tool diff computation 60% faster (CC 2.1.92) +- Bedrock setup wizard added (CC 2.1.92) +- Per-model cost breakdown in `/cost` (CC 2.1.92) +- `/release-notes` interactive version picker (CC 2.1.92) +- Remote Control session name improvements (CC 2.1.92) +- Footer hint for uncached tokens after cache expiration (CC 2.1.92) +- Linux sandbox `apply-seccomp` fix (CC 2.1.92) +- Transcript chain fix for `--resume` (CC 2.1.91) +- `cmd+delete` fix for various terminals (CC 2.1.91) +- Plan mode fix for remote sessions (CC 2.1.91) +- JSON schema validation fix for `permissions.defaultMode: "auto"` (CC 2.1.91) +- Edit tool using shorter anchors (CC 2.1.91) +- Faster `stripAnsi` on Bun (CC 2.1.91) +- Multi-line prompt support in deep links (CC 2.1.91) +- Various PreToolUse hook fixes for JSON stdout (CC 2.1.90) +- Auto mode boundary respect fixes (CC 2.1.90) +- PowerShell security hardening (CC 2.1.90) +- SSE transport performance fix (CC 2.1.90) +- `/resume` parallel session loading (CC 2.1.90) +- DNS cache commands removed from auto-allow (CC 2.1.90) +- CLAUDE_CODE_NO_FLICKER env var (CC 2.1.89) +- Edit/Read/Write symlink target checking fix (CC 2.1.89) +- Various voice mode fixes (CC 2.1.89) +- CRLF handling fixes (CC 2.1.89) +- StructuredOutput schema cache fix (CC 2.1.89) +- LSP server restart on crash (CC 2.1.89) +- Autocompact thrash loop detection (CC 2.1.89) +- Nested CLAUDE.md re-injection fix (CC 2.1.89) +- Hooks `if` condition fix for compound commands (CC 2.1.89) +- Thinking summaries disabled by default (CC 2.1.89) +- Team memory content display removed (CC 2.1.92) +- /pr-comments slash command removed (CC 2.1.91) +- Update Magic Docs agent prompt removed (CC 2.1.91) +- Memory attachment guidance updates (CC 2.1.90-2.1.91) +- Verification specialist prompt expansions (CC 2.1.89-2.1.90) +- Prompt caching documentation updates (CC 2.1.89) --- -## Summary +## Notes -**Versions analyzed:** 2.1.87, 2.1.88 +1. **Degraded triangulation**: The claude-code-guide agent was not available in this CI environment, so cross-referencing against official docs was not performed. Changes are confirmed via changelog and system-prompts sources only. -**Token delta (2.1.88):** -1,627 tokens (net reduction due to verify skill condensing and removed system section) +2. **High-priority items for plugin-dev**: + - The `defer` permission decision is a significant addition to the hooks system + - PermissionDenied hook expansion affects auto-mode integration + - Plugin `bin/` directory support is a new plugin capability + - `disableSkillShellExecution` setting affects how skills execute + - Write tool "always prefer Edit" guidance may affect our examples + - Sleep tool removal affects tool documentation -**Key themes in 2.1.88:** -1. New Config tool for settings management -2. New PermissionDenied hook event (ADDED by verification) -3. Team file path restructuring -4. PreToolUse/PostToolUse file_path now absolute (ADDED by verification) -5. Partial compaction feature -6. Enhanced Windows/PowerShell support (May Update) -7. Removed tool permission mode system section +3. **System-prompts changelog is more authoritative** for prompt/tool description changes, while the GitHub changelog captures user-facing features and settings. -**Risk assessment:** The PermissionDenied hook and file_path absolute path fix are the highest priority items as they directly affect hook development documentation. The team file path change and Config tool addition also require updates. +4. **Token delta summary**: + - 2.1.89: +3,986 tokens (MCP truncation, remote plan mode, buddy mode, computer use MCP skill) + - 2.1.90: +815 tokens (memory attachment, security monitor expansion) + - 2.1.91: +2,043 tokens (Agent Design Patterns skill, tool description updates) + - 2.1.92: -167 tokens (hook evaluator specialization, Sleep tool removal, Write tool guidance) --- ## Stage 2: Verification Results -### Verified: 2026-03-31 +### Verified: 2026-04-04 #### Must Update Verification -- [x] **NEW: Config tool added** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 13. Gap exists: no mention of Config tool in plugin-dev tool documentation. Affects: agent-development (tool references). -- [x] **TeammateTool path changed** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 23. Gap exists: plugin-dev agent-development skill does not document team file paths. Affects: agent-development (teams section). -- [x] **NEW: Partial compaction instructions** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 11. Gap exists: no documentation of partial compaction. Affects: hook-development (PreCompact/PostCompact), skill-development (context management). -- [x] **REMOVED: System section (tool permission mode)** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 14. Gap exists: hook-development references "tool permission mode" terminology. Review needed. -- [x] **Verify skill substantially condensed** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 15. This is an internal CC change to CC's built-in verify skill, NOT the plugin-dev verify skill. No gap exists in plugin-dev. **Reclassified to No Action** -- plugin-dev has no "verify skill" to align with. -- [x] **PowerShell tool description expanded** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 22. No existing PowerShell documentation in plugin-dev (grep returned no matches). This is a Windows-specific addition. **May Update** level -- only relevant for Windows users. -- [x] **NEW: PowerShell 5.1 system prompt** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 12. Same as above -- no existing PowerShell docs. **May Update** level. -- [x] **Ultraplan can now implement in same session** (CC 2.1.88) -- confirmed in system-prompts CHANGELOG line 20. No existing ultraplan documentation in plugin-dev. Low impact for plugin developers. **Demoted to No Action** -- ultraplan is an internal CC feature, not directly affecting plugin development. +- ✓ **PreToolUse hooks can return `"defer"` permission decision** (CC 2.1.89) -- confirmed in changelog, gap exists in hook-development/SKILL.md line 322 (only shows `allow|deny|ask`, missing `defer`) +- ✗ **PermissionDenied hook now fires after auto mode classifier denials** (CC 2.1.89) -- REJECTED: already documented at hook-development/SKILL.md lines 385-423 (added in previous 2.1.88 sync) +- ✓ **MCP tool result persistence override via `_meta` annotation** (CC 2.1.91) -- confirmed in changelog, gap exists in mcp-integration/SKILL.md (no mention of maxResultSizeChars) +- ✓ **`disableSkillShellExecution` setting** (CC 2.1.91) -- confirmed in changelog, gap exists in skill-development/SKILL.md (not documented) +- ✓ **Plugins can ship executables under `bin/` directory** (CC 2.1.91) -- confirmed in changelog, gap exists in plugin-structure/SKILL.md (not documented) +- ↓ **`/tag` and `/vim` commands removed** (CC 2.1.92) -- demoted to No Action: built-in commands not documented in plugin-dev +- ↓ **Write tool guidance changed: always prefer Edit** (CC 2.1.92) -- demoted to No Action: not plugin-dev scope (tool descriptions) +- ↓ **Hook condition evaluator specialized for stop conditions** (CC 2.1.92) -- demoted to No Action: internal implementation detail, no plugin API surface change +- ↓ **Sleep tool removed** (CC 2.1.92) -- demoted to No Action: not plugin-dev scope (built-in tools) +- ↓ **Agent Design Patterns skill added** (CC 2.1.91) -- demoted to No Action: built-in CC skill, not plugin-dev documentation scope + +#### Skill Mapping Corrections +- ! **skill-anatomy** -- INCORRECT: skill does not exist; should be `skill-development` +- ! **plugin-json-schema** -- INCORRECT: skill does not exist; should be `plugin-structure` +- ! **slash-commands** -- INCORRECT: skill does not exist; should be `command-development` +- ! **build-with-claude-api** -- INCORRECT: skill does not exist in plugin-dev (built-in CC skill) #### Missed Items (promoted from No Action) -- ! **PreToolUse/PostToolUse file_path now absolute** (CC 2.1.88) -- missed from changelog! CC changelog says "Fixed PreToolUse/PostToolUse hooks not providing `file_path` as an absolute path for Write/Edit/Read tools." This is directly relevant to hook-development docs. - - Affects: hook-development (tool input schemas, event-schemas.md) - - Details: Hook scripts that process file_path from Write/Edit/Read tools now receive absolute paths. This is a behavior change that affects hook script logic. - -- ! **PermissionDenied hook introduced** (CC 2.1.88) -- partially captured but listed as "No Action". The CC changelog states "Introduced `PermissionDenied` hook that activates following auto mode classifier denials, allowing models to request retry via `{retry: true}` response." This is a NEW hook event that should be documented. - - Affects: hook-development (new hook event) - - Details: New hook event PermissionDenied was introduced. The current hook-development skill lists 24 events; this adds a 25th. Must be documented. - -- ! **Plugin permission fix v2.1.83** (CC 2.1.86, 2.1.88) -- The CC changelog mentions "Official marketplace plugin scripts were failing with permission errors on macOS/Linux starting in v2.1.83; this is now resolved" in both 2.1.86 and 2.1.88. This is worth noting for compatibility but is a bug fix, not a documentation gap. - - Affects: None (bug fix) - - **Kept as No Action** -- bug fix, no docs needed - -- ! **Hook `if` filtering for compound commands** (CC 2.1.88) -- CC changelog: "Fixed hooks' `if` condition filtering to properly match compound commands like `ls && git push` and commands with environment variable prefixes such as `FOO=bar git push`." This is relevant to hook-development. - - Affects: hook-development (advanced.md, `if` field documentation) - - Details: The `if` field now properly handles compound commands. Existing docs may need clarification. - - **Promoted to Must Update** -- behavior clarification for existing feature +- None identified. Scanned changelog for: hook, plugin, agent, skill, command, MCP, LSP, tool, permission, subagent, frontmatter, manifest, plugin.json, PreToolUse, PostToolUse, SessionStart, Stop. All relevant items were captured. #### May Update Resolution -- = **Git status prompt simplified** (CC 2.1.88) -- kept as May Update. Internal CC change, no plugin-dev impact. -- = **Fork usage guidelines updated** (CC 2.1.88) -- kept as May Update. Could inform agent-development examples but not critical. -- = **Writing subagent prompts collapsed** (CC 2.1.88) -- kept as May Update. Could inform agent-creator agent but not critical. -- = **Plan mode reminder conditional** (CC 2.1.88) -- kept as May Update. Internal CC behavior. -- = **Agent tool prompt guidance moved** (CC 2.1.88) -- kept as May Update. Could inform agent-development but not critical. -- downarrow **PowerShell tool description expanded** -- demoted from Must Update to May Update. Windows-specific, no existing docs to update. -- downarrow **PowerShell 5.1 system prompt** -- demoted from Must Update to May Update. Windows-specific, no existing docs to update. +- ↓ **Named subagents in `@` mention typeahead** (CC 2.1.89) -- demoted to No Action: UX feature, no plugin API impact +- = **`MCP_CONNECTION_NONBLOCKING=true` env var** (CC 2.1.89) -- kept as May Update: could document in mcp-integration references +- ↓ **`/powerup` command added** (CC 2.1.90) -- demoted to No Action: built-in command, not plugin-dev scope +- ↓ **`CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` env var** (CC 2.1.90) -- demoted to No Action: operational env var, not plugin development +- ↓ **`.husky` added to protected directories** (CC 2.1.90) -- demoted to No Action: permissions detail, not plugin-dev scope +- ↓ **`forceRemoteSettingsRefresh` policy setting** (CC 2.1.92) -- demoted to No Action: managed settings, not plugin-dev scope +- = **MCP tool truncation guidance updated** (CC 2.1.92) -- kept as May Update: could document in mcp-integration subagent guidance +- = **ReadFile tool supports relative paths** (CC 2.1.91) -- kept as May Update: could affect skill script examples +- ↓ **Edit tool guidelines made configurable** (CC 2.1.91) -- demoted to No Action: not plugin-dev scope +- ↓ **Computer Use MCP skill added** (CC 2.1.89) -- demoted to No Action: built-in CC skill, not plugin-dev scope +- ↓ **Remote plan mode (ultraplan) prompt added** (CC 2.1.89) -- demoted to No Action: built-in CC feature +- ↓ **Buddy Mode prompt added** (CC 2.1.89) -- demoted to No Action: built-in CC feature +- ↓ **Security monitor prompt significantly expanded** (CC 2.1.89-2.1.90) -- demoted to No Action: internal security, not plugin API #### Summary -- Must Update: 7 items (4 confirmed original, 3 promoted from No Action, 2 demoted to May Update) - - Config tool added - - TeammateTool path changed - - Partial compaction instructions - - REMOVED: System section (tool permission mode) - - PreToolUse/PostToolUse file_path now absolute (NEW) - - PermissionDenied hook introduced (NEW) - - Hook `if` filtering for compound commands (NEW) -- May Update: 7 items (5 original, 2 demoted from Must Update) -- Confidence: HIGH -- sources independently verified, all changelog entries cross-referenced - -#### Notes -- The manifest correctly identified the version range 2.1.87-2.1.88 -- v2.1.87 had no system prompt changes (confirmed) -- The "Verify skill" item was incorrectly classified -- it refers to CC's built-in verify skill, not a plugin-dev skill -- Two significant plugin-relevant changes were in the CC changelog "No Action" section that should have been flagged: - 1. PreToolUse/PostToolUse file_path absolute path fix - 2. PermissionDenied hook introduction -- The `if` field compound command fix enhances existing documented feature +- Must Update: 4 items confirmed (defer decision, MCP maxResultSizeChars, disableSkillShellExecution, plugin bin/) +- Must Update: 6 items demoted to No Action (not plugin-dev scope) +- May Update: 3 items remaining (MCP_CONNECTION_NONBLOCKING, MCP truncation guidance, ReadFile relative paths) +- Skill Mapping: 4 corrections needed (skill names were incorrect in original manifest) +- Confidence: HIGH -- Changes verified against primary sources; skill file gaps confirmed by reading actual SKILL.md files diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index edac973..ec461a7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.9.0" + "version": "0.10.0" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.9.0", + "version": "0.10.0", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a2b5ac..a6f1263 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.0] - 2026-04-04 + +### Added + +- **hook-development**: Documented PreToolUse `defer` permission decision for pausing tool execution in headless sessions (CC 2.1.89) +- **mcp-integration**: Documented `_meta["anthropic/maxResultSizeChars"]` annotation for large MCP tool results up to 500K characters (CC 2.1.91) +- **skill-development**: Documented `disableSkillShellExecution` setting that organizations can use to disable inline shell execution (CC 2.1.91) +- **command-development**: Documented `disableSkillShellExecution` setting for command shell execution (CC 2.1.91) +- **plugin-structure**: Documented plugin `bin/` directory for shipping executables that can be invoked as bare commands (CC 2.1.91) + ## [0.9.0] - 2026-03-31 ### Added @@ -334,7 +344,8 @@ 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/kylesnowschwartz/plugin-dev/compare/v0.9.0...HEAD +[Unreleased]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.0...HEAD +[0.10.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.9.0...v0.10.0 [0.9.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.8.0...v0.9.0 [0.8.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.7.0...v0.8.0 [0.7.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.6.1...v0.7.0 diff --git a/CLAUDE.md b/CLAUDE.md index f557ed9..4602b05 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 11 skills, 7 agents, 3 slash commands. -**Version**: v0.9.0 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.10.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md index ff6c2ba..1b58778 100644 --- a/docs/claude-code-compatibility.md +++ b/docs/claude-code-compatibility.md @@ -1,12 +1,13 @@ # Claude Code Compatibility -Last audited: Claude Code 2.1.88 (2026-03-31) -Plugin-dev version: 0.9.0 +Last audited: Claude Code 2.1.92 (2026-04-04) +Plugin-dev version: 0.10.0 ## Audit Log | plugin-dev | CC version range | Date | Notes | |---|---|---|---| +| v0.10.0 | 2.1.89-2.1.92 | 2026-04-04 | PreToolUse `defer` decision, MCP maxResultSizeChars (500K), disableSkillShellExecution setting, plugin bin/ directory | | v0.9.0 | 2.1.87-2.1.88 | 2026-03-31 | PermissionDenied hook (25th event), file_path absolute paths, `if` compound command fix, partial compaction, Config tool | | v0.8.0 | 2.1.85-2.1.86 | 2026-03-29 | Hook `if` field, AskUserQuestion via updatedInput, skill 250-char cap, alphabetical /skills, org plugin blocking, MCP env vars, agent prompt change, fork naming, Production Reads | | v0.5.0 | ≤2.1.84 | 2026-03-27 | Initial compatibility baseline (initialPrompt, CwdChanged, FileChanged, userConfig, paths) | diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index fa3ea6f..b0b0150 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.9.0", + "version": "0.10.0", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/skills/command-development/SKILL.md b/plugins/plugin-dev/skills/command-development/SKILL.md index 610860d..1c782ab 100644 --- a/plugins/plugin-dev/skills/command-development/SKILL.md +++ b/plugins/plugin-dev/skills/command-development/SKILL.md @@ -398,6 +398,8 @@ For advanced patterns, environment-specific configurations, and plugin integrati 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. +**Disable shell execution (CC 2.1.91):** Organizations can disable inline shell execution in skills, custom slash commands, and plugin commands via the `disableSkillShellExecution` setting. When enabled, `[BANG]`command`` blocks are not executed. Design commands to work gracefully when shell execution is unavailable. + ### Commands and Skills: Same Mechanism, Different Complexity Commands and skills are both invoked via the same **Skill tool**. The difference is organizational complexity: diff --git a/plugins/plugin-dev/skills/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md index f95b776..9ddad48 100644 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ b/plugins/plugin-dev/skills/hook-development/SKILL.md @@ -319,7 +319,7 @@ Execute before any tool runs. Use to approve, deny, or modify tool calls. { "hookSpecificOutput": { "hookEventName": "PreToolUse", - "permissionDecision": "allow|deny|ask", + "permissionDecision": "allow|deny|ask|defer", "permissionDecisionReason": "Explanation", "updatedInput": { "file_path": "/modified/path" }, "additionalContext": "Extra context for Claude" @@ -330,6 +330,8 @@ Execute before any tool runs. Use to approve, deny, or modify tool calls. > **Deprecated:** The old top-level `decision: "approve|block"` fields still work but are superseded by `hookSpecificOutput.permissionDecision`. Use `permissionDecision` for new hooks. > > **AskUserQuestion pattern (CC 2.1.85):** PreToolUse hooks can satisfy `AskUserQuestion` tool calls by returning `updatedInput` alongside `permissionDecision: "allow"`. This enables headless integrations that collect answers via their own UI rather than requiring interactive user input. +> +> **Defer pattern (CC 2.1.89):** Return `permissionDecision: "defer"` to pause tool execution in headless sessions. The session can be resumed later with `-p --resume`. Use `defer` when you need external approval or want to batch decisions for later processing. #### PermissionRequest diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index dab3e1f..7303a86 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -666,6 +666,17 @@ MCP servers can notify Claude Code of tool changes at runtime via `list_changed` - Default maximum: 25,000 tokens - Configure with `MAX_MCP_OUTPUT_TOKENS` environment variable +**Large result override (CC 2.1.91):** MCP servers can return larger results (up to 500K characters) by setting `_meta["anthropic/maxResultSizeChars"]` in the tool result annotation. Useful for large database schemas or similar payloads: + +```json +{ + "content": [...], + "_meta": { + "anthropic/maxResultSizeChars": 500000 + } +} +``` + Design plugin MCP tools to return concise results. Paginate or summarize large outputs. ### MCP Description Limits diff --git a/plugins/plugin-dev/skills/plugin-structure/SKILL.md b/plugins/plugin-dev/skills/plugin-structure/SKILL.md index b0a26be..47e9b33 100644 --- a/plugins/plugin-dev/skills/plugin-structure/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-structure/SKILL.md @@ -34,6 +34,7 @@ plugin-name/ ├── hooks/ │ └── hooks.json # Event handler configuration ├── .mcp.json # MCP server definitions +├── bin/ # Plugin executables (CC 2.1.91) └── scripts/ # Helper scripts and utilities ``` @@ -369,6 +370,42 @@ For detailed LSP configuration, see the `lsp-integration` skill. **Usage**: Plugins can define consistent output formatting for their domain. See `references/output-styles.md` for detailed style file format. +### Plugin Executables (bin/) + +**Location**: `bin/` directory at plugin root +**Format**: Executable files (compiled binaries, scripts with shebang) +**Auto-discovery**: Executables in `bin/` can be invoked as bare commands from the Bash tool +**Added**: CC 2.1.91 + +**Example structure**: + +``` +plugin-name/ +├── bin/ +│ ├── my-tool # Compiled binary +│ └── helper.sh # Shell script with #!/bin/bash +``` + +**Usage**: + +```bash +# In hooks, MCP servers, or when Claude uses Bash tool: +my-tool --flag value +helper.sh arg1 arg2 +``` + +**Requirements**: + +- Files must have execute permissions (`chmod +x`) +- Scripts must have proper shebang (`#!/bin/bash`, `#!/usr/bin/env python3`, etc.) +- Binaries must be compatible with target platform + +**Use cases**: + +- Ship compiled tools (formatters, linters, converters) +- Provide standalone utilities without requiring dependencies +- Bundle platform-specific binaries + ## Portable Path References ### ${CLAUDE_PLUGIN_ROOT} diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index fbf4a3a..5fa9ce9 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -296,6 +296,8 @@ Recent commits: **Security note:** Commands execute in the user's environment. Only use trusted commands. +**Disable shell execution (CC 2.1.91):** Organizations can disable inline shell execution in skills, custom slash commands, and plugin commands via the `disableSkillShellExecution` setting. When enabled, `[BANG]`command`` blocks are not executed. Design skills to work gracefully when shell execution is unavailable. + ### Progressive Disclosure Design Principle Skills use a three-level loading system to manage context efficiently: From ded460c4d6f68c0633723f8187275371c0d8aef1 Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Tue, 7 Apr 2026 14:23:09 +1200 Subject: [PATCH 29/33] fix: release v0.10.1 Fix YAML frontmatter parse error in plugin-dev-guide agent by adding missing block scalar indicator on description field. --- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 9 ++- CLAUDE.md | 2 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- plugins/plugin-dev/agents/plugin-dev-guide.md | 75 ++++++++++--------- 5 files changed, 50 insertions(+), 42 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ec461a7..6b20e1b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.10.0" + "version": "0.10.1" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.10.0", + "version": "0.10.1", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index a6f1263..55fd8c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.1] - 2026-04-07 + +### Fixed + +- **plugin-dev-guide agent**: Fixed YAML frontmatter parse error — added missing block scalar indicator (`|`) on description field + ## [0.10.0] - 2026-04-04 ### Added @@ -344,7 +350,8 @@ 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/kylesnowschwartz/plugin-dev/compare/v0.10.0...HEAD +[Unreleased]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.1...HEAD +[0.10.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.0...v0.10.1 [0.10.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.9.0...v0.10.0 [0.9.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.8.0...v0.9.0 [0.8.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.7.0...v0.8.0 diff --git a/CLAUDE.md b/CLAUDE.md index 4602b05..ead9923 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 11 skills, 7 agents, 3 slash commands. -**Version**: v0.10.0 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.10.1 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index b0b0150..f8e3875 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.10.0", + "version": "0.10.1", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/agents/plugin-dev-guide.md b/plugins/plugin-dev/agents/plugin-dev-guide.md index 8efa771..c7c0c78 100644 --- a/plugins/plugin-dev/agents/plugin-dev-guide.md +++ b/plugins/plugin-dev/agents/plugin-dev-guide.md @@ -1,42 +1,43 @@ --- name: plugin-dev-guide -description: Use this agent when the user asks about "Claude Code plugins", "plugin development", "how to build a plugin", "what plugin components exist", "plugin architecture", "extending Claude Code", or needs help with a specific plugin component (hooks, MCP, LSP, skills, agents, commands, settings, marketplace). Also use when troubleshooting plugin issues. Examples: - - -Context: User is new to plugin development -user: "How do I build a Claude Code plugin?" -assistant: "I'll use the plugin-dev-guide agent to find the right skill for this." - -General plugin development question triggers the guide agent for triage. - - - - -Context: User needs help with a specific component -user: "How do hooks work in Claude Code plugins?" -assistant: "I'll use the plugin-dev-guide agent to identify the right skill." - -Specific component question — agent matches to hook-development skill. - - - - -Context: User wants to understand capabilities -user: "What can plugins do in Claude Code?" -assistant: "I'll use the plugin-dev-guide agent to provide an overview." - -Overview question — agent returns OVERVIEW so main agent summarizes. - - - - -Context: User is troubleshooting -user: "My skill isn't being loaded when I ask about PDF processing" -assistant: "I'll use the plugin-dev-guide agent to find the right troubleshooting skill." - -Troubleshooting often maps to skill-development or plugin-structure. - - +description: | + Use this agent when the user asks about "Claude Code plugins", "plugin development", "how to build a plugin", "what plugin components exist", "plugin architecture", "extending Claude Code", or needs help with a specific plugin component (hooks, MCP, LSP, skills, agents, commands, settings, marketplace). Also use when troubleshooting plugin issues. Examples: + + + Context: User is new to plugin development + user: "How do I build a Claude Code plugin?" + assistant: "I'll use the plugin-dev-guide agent to find the right skill for this." + + General plugin development question triggers the guide agent for triage. + + + + + Context: User needs help with a specific component + user: "How do hooks work in Claude Code plugins?" + assistant: "I'll use the plugin-dev-guide agent to identify the right skill." + + Specific component question — agent matches to hook-development skill. + + + + + Context: User wants to understand capabilities + user: "What can plugins do in Claude Code?" + assistant: "I'll use the plugin-dev-guide agent to provide an overview." + + Overview question — agent returns OVERVIEW so main agent summarizes. + + + + + Context: User is troubleshooting + user: "My skill isn't being loaded when I ask about PDF processing" + assistant: "I'll use the plugin-dev-guide agent to find the right troubleshooting skill." + + Troubleshooting often maps to skill-development or plugin-structure. + + model: haiku color: blue From febe621456b5ddd2f98e1631a0cfda6d077ae800 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 10 Apr 2026 06:58:24 +0000 Subject: [PATCH 30/33] docs: sync plugin-dev with Claude Code v2.1.94-v2.1.98 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sync plugin-dev documentation with upstream Claude Code changes: - agent-development: Document Monitor tool for streaming background events (CC 2.1.98) - agent-development: Document agent absolute file path requirement (CC 2.1.97) - skill-development: Document skill invocation name change (CC 2.1.94) - claude-code-compatibility: Update audit log with CC 2.1.94-2.1.98 changes Version bump: 0.10.1 → 0.10.2 Co-Authored-By: Claude Opus 4.5 --- .agent-history/upstream-changes.md | 400 +++++++++++------- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 15 +- CLAUDE.md | 2 +- docs/claude-code-compatibility.md | 5 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../skills/agent-development/SKILL.md | 5 + .../skills/skill-development/SKILL.md | 2 + 8 files changed, 274 insertions(+), 161 deletions(-) diff --git a/.agent-history/upstream-changes.md b/.agent-history/upstream-changes.md index a700dca..39415bc 100644 --- a/.agent-history/upstream-changes.md +++ b/.agent-history/upstream-changes.md @@ -1,135 +1,235 @@ # Upstream Change Manifest -## CC Version Range: 2.1.89 - 2.1.92 -## Generated: 2026-04-04 +## CC Version Range: 2.1.93 - 2.1.98 +## Generated: 2026-04-10 ## Sources: changelog [OK], system-prompts [OK], claude-code-guide [failed - agent not available in CI] --- ### Must Update -- [ ] **PreToolUse hooks can return `"defer"` permission decision** (CC 2.1.89) - - Source: changelog, system-prompts (implied by deferred tool handling) +- [ ] **Monitor tool for streaming background events** (CC 2.1.98) + - Source: changelog, system-prompts (NEW: Tool Description: Background monitor) - Confidence: high - - Affects: hook-development skill (SKILL.md line 322) - - Details: Headless sessions can now pause tool execution and resume later with `-p --resume`. The `defer` decision allows hooks to put tools on hold rather than immediately allowing or denying. This is a new permission decision type alongside `allow`, `deny`, and `ask`. - - Raw changelog: "Added `\"defer\"` permission decision to `PreToolUse` hooks -- headless sessions can pause and resume with `-p --resume`" - - Gap: SKILL.md line 322 shows `permissionDecision: "allow|deny|ask"` -- needs `defer` added + - Affects: agent-development skill (Available Tools section), tool documentation + - Details: New tool that streams stdout events from long-running scripts as chat notifications. System prompts include guidelines on script quality, output volume, and selective filtering. + - Raw changelog: "Monitor tool for streaming background events to foreground session" + - System-prompts: "NEW: Tool Description: Background monitor (streaming events) -- Added description for a background monitor tool that streams stdout events from long-running scripts as chat notifications" + - Gap: New tool not documented in agent-development or tool references -- [ ] **MCP tool result persistence override via `_meta` annotation** (CC 2.1.91) - - Source: changelog only +- [ ] **Agent threads now always require absolute file paths** (CC 2.1.97) + - Source: system-prompts only - Confidence: high - - Affects: mcp-integration skill (SKILL.md MCP Output Limits section) - - Details: MCP servers can now return larger results (up to 500K characters) by setting `_meta["anthropic/maxResultSizeChars"]` in the tool result annotation. Useful for large database schemas or similar payloads. - - Raw changelog: "Added MCP tool result persistence override via `_meta[\"anthropic/maxResultSizeChars\"]` annotation (up to 500K)" - - Gap: Not documented in mcp-integration/SKILL.md + - Affects: agent-development skill (Agent Best Practices section) + - Details: Removed conditional logic for relative vs. absolute paths in agent threads. Agents must now always use absolute file paths unconditionally. This reverses/clarifies the 2.1.91 change that added relative path support. + - System-prompts: "System Prompt: Agent thread notes -- Removed the conditional logic for relative vs. absolute file paths; agent threads now always require absolute file paths unconditionally" + - Gap: agent-development skill may need to clarify absolute path requirement for agents -- [ ] **`disableSkillShellExecution` setting** (CC 2.1.91) - - Source: changelog only +- [ ] **Plugin skill hooks and CLAUDE_PLUGIN_ROOT fixes** (CC 2.1.94) + - Source: changelog - Confidence: high - - Affects: skill-development skill (Dynamic Content section) and command-development skill - - Details: New setting that disables inline shell execution in skills, custom slash commands, and plugin commands. This is a security control for environments that want skills but not arbitrary shell execution. - - Raw changelog: "`disableSkillShellExecution` setting to disable inline shell execution in skills, custom slash commands, and plugin commands" - - Gap: Not documented in skill-development/SKILL.md or command-development/SKILL.md + - Affects: docs/claude-code-compatibility.md, hook-development skill (bug fixes note) + - Details: Three critical bug fixes: (1) Plugin skill hooks in YAML frontmatter were silently ignored - now fixed; (2) Plugin hooks failed with "No such file or directory" when CLAUDE_PLUGIN_ROOT was not set - now fixed; (3) ${CLAUDE_PLUGIN_ROOT} resolved to marketplace source instead of installed cache for local-marketplace plugins - now fixed. + - Raw changelog: "Fixed plugin skill hooks defined in YAML frontmatter being silently ignored", "Fixed plugin hooks failing with 'No such file or directory' when CLAUDE_PLUGIN_ROOT was not set", "Fixed ${CLAUDE_PLUGIN_ROOT} resolving to marketplace source instead of installed cache for local-marketplace plugins" + - Gap: Compatibility tracker needs update; hook-development may note these were fixed -- [ ] **Plugins can ship executables under `bin/` directory** (CC 2.1.91) - - Source: changelog only +- [ ] **Skill invocation name change** (CC 2.1.94) + - Source: changelog - Confidence: high - - Affects: plugin-structure skill (Directory Structure section) - - Details: Plugins can now include executables in a `bin/` subdirectory and invoke them as bare commands from the Bash tool. This enables plugins to ship compiled tools or scripts. - - Raw changelog: "Plugins can ship executables under `bin/` and invoke them as bare commands from Bash tool" - - Gap: Not documented in plugin-structure/SKILL.md + - Affects: skill-development skill (naming section) + - Details: Plugin skills declared via "skills": ["./"] now use the skill's frontmatter `name` for invocation instead of directory basename. This changes how skills are discovered and invoked. + - Raw changelog: "Plugin skills declared via 'skills': ['./'] now use the skill's frontmatter name for invocation instead of directory basename" + - Gap: skill-development should note that frontmatter `name` is used for invocation, not directory name --- ### May Update -- [ ] **`MCP_CONNECTION_NONBLOCKING=true` env var** (CC 2.1.89) - - Source: changelog only - - Confidence: low - - Affects: mcp-integration skill (headless/CI mode patterns) - - Details: For `-p` mode, this env var skips waiting for MCP connections entirely. - - Raw changelog: "`MCP_CONNECTION_NONBLOCKING=true` for `-p` mode skips MCP connection wait entirely" +- [ ] **Communication style system prompts added** (CC 2.1.98) + - Source: system-prompts only + - Confidence: medium + - Affects: skill-development skill (skill writing best practices) + - Details: New system prompts for communication style guidelines. May be useful context for skill writing guidance but not a direct plugin API change. -- [ ] **MCP tool truncation guidance updated** (CC 2.1.92) +- [ ] **Exploratory questions system prompt** (CC 2.1.98) - Source: system-prompts only - Confidence: medium - - Affects: mcp-integration skill (subagent guidance) - - Details: Changed subagent file-reading guidance from "Read ALL of [file]" to instruct reading in sequential chunks using offset/limit until 100% of the file has been read, then summarizing. - - System-prompts: "System Prompt: MCP Tool Result Truncation -- Changed subagent file-reading guidance..." + - Affects: skill-development skill (trigger design best practices) + - Details: Claude now analyzes before implementing on open-ended questions. May inform skill design but not a documentation gap. -- [ ] **ReadFile tool supports relative paths** (CC 2.1.91) +- [ ] **Managed Agents API replaces Agent SDK** (CC 2.1.97) + - Source: system-prompts + - Confidence: high + - Affects: potential future plugin-dev integration + - Details: Major architectural change in Claude Code's built-in API documentation. Plugin-dev does not currently reference Agent SDK, so no stale references exist. Informational only for now. + +- [ ] **CLAUDE_CODE_PERFORCE_MODE environment variable** (CC 2.1.98) + - Source: changelog only + - Confidence: medium + - Affects: potential environment variable documentation + - Details: New env var for read-only file handling in Perforce environments. + - Raw changelog: "`CLAUDE_CODE_PERFORCE_MODE` environment variable for read-only file handling" + +- [ ] **CLAUDE_CODE_USE_MANTLE=1 for Amazon Bedrock via Mantle** (CC 2.1.94) + - Source: changelog only + - Confidence: medium + - Affects: potential environment variable documentation + - Details: New env var enabling Amazon Bedrock support via Mantle. + - Raw changelog: "Added Amazon Bedrock support via Mantle with `CLAUDE_CODE_USE_MANTLE=1` environment variable" + +- [ ] **Default effort level changed from medium to high** (CC 2.1.94) + - Source: changelog, system-prompts (Build with Claude API skill update) + - Confidence: medium + - Affects: agent-development references (if any mention effort levels) + - Details: Changed default effort level from medium to high for API-key and Team/Enterprise users. System prompts updated effort parameter guidance. + - Raw changelog: "Changed default effort level from medium to high for API-key and Team/Enterprise users" + +- [ ] **Worker fork agent metadata changes** (CC 2.1.97) + - Source: system-prompts only + - Confidence: low + - Affects: agent-development skill (fork/subagent patterns) + - Details: Added agent metadata specifying model inheritance, permission bubbling, max turns, full tool access, and description of when forks are triggered. Minor documentation alignment opportunity. + - System-prompts: "Agent Prompt: Worker fork -- Added agent metadata specifying model inheritance, permission bubbling, max turns, full tool access" + +- [ ] **Dream team memory handling** (CC 2.1.98) - Source: system-prompts only - Confidence: low - - Affects: skill script examples (minor style preference) - - Details: ReadFile now supports relative paths as a preferred alternative (for brevity) to absolute-path-only requirement. Line read limit and additional notes are now configurable. - - System-prompts: "Tool Description: ReadFile -- Added support for relative file paths (preferred for brevity)..." + - Affects: potential memory-related skill references + - Details: New system prompt for handling shared team memories during dream consolidation, including deduplication and conservative pruning rules. + +- [ ] **Focus view toggle (Ctrl+O) for NO_FLICKER mode** (CC 2.1.97) + - Source: changelog only + - Confidence: low + - Affects: potential UI/keybinding documentation + - Details: New keyboard shortcut for focus view displaying prompt and tool summaries. + +- [ ] **refreshInterval status line setting** (CC 2.1.97) + - Source: changelog only + - Confidence: low + - Affects: potential configuration documentation + - Details: New setting for controlling status line refresh interval. --- ### No Action -**Demoted from Must Update (Stage 2 verification):** -- PermissionDenied hook fires after auto mode classifier denials (CC 2.1.89) -- already documented in hook-development/SKILL.md lines 385-423 -- `/tag` and `/vim` commands removed (CC 2.1.92) -- built-in commands, not plugin-dev scope -- Write tool guidance changed: always prefer Edit (CC 2.1.92) -- tool description, not plugin-dev scope -- Hook condition evaluator specialized for stop conditions (CC 2.1.92) -- internal implementation detail -- Sleep tool removed (CC 2.1.92) -- built-in tool, not plugin-dev scope -- Agent Design Patterns skill added (CC 2.1.91) -- built-in CC skill, not plugin-dev scope - -**Demoted from May Update (Stage 2 verification):** -- Named subagents in `@` mention typeahead (CC 2.1.89) -- UX feature, no plugin API impact -- `/powerup` command added (CC 2.1.90) -- built-in command, not plugin-dev scope -- `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` env var (CC 2.1.90) -- operational env var -- `.husky` added to protected directories (CC 2.1.90) -- permissions detail, not plugin-dev scope -- `forceRemoteSettingsRefresh` policy setting (CC 2.1.92) -- managed settings, not plugin-dev scope -- Edit tool guidelines made configurable (CC 2.1.91) -- not plugin-dev scope -- Computer Use MCP skill added (CC 2.1.89) -- built-in CC skill -- Remote plan mode (ultraplan) prompt added (CC 2.1.89) -- built-in CC feature -- Buddy Mode prompt added (CC 2.1.89) -- built-in CC feature -- Security monitor prompt significantly expanded (CC 2.1.89-2.1.90) -- internal security - -**Original No Action items:** -- Fix for rate-limit options dialog infinite loop (CC 2.1.90) -- Subagent spawning fix after tmux window changes (CC 2.1.92) -- Stop hooks fix for small fast model `ok:false` (CC 2.1.92) -- Tool input validation fixes for streaming (CC 2.1.92) -- API 400 error fix for whitespace-only thinking blocks (CC 2.1.92) -- Write tool diff computation 60% faster (CC 2.1.92) -- Bedrock setup wizard added (CC 2.1.92) -- Per-model cost breakdown in `/cost` (CC 2.1.92) -- `/release-notes` interactive version picker (CC 2.1.92) -- Remote Control session name improvements (CC 2.1.92) -- Footer hint for uncached tokens after cache expiration (CC 2.1.92) -- Linux sandbox `apply-seccomp` fix (CC 2.1.92) -- Transcript chain fix for `--resume` (CC 2.1.91) -- `cmd+delete` fix for various terminals (CC 2.1.91) -- Plan mode fix for remote sessions (CC 2.1.91) -- JSON schema validation fix for `permissions.defaultMode: "auto"` (CC 2.1.91) -- Edit tool using shorter anchors (CC 2.1.91) -- Faster `stripAnsi` on Bun (CC 2.1.91) -- Multi-line prompt support in deep links (CC 2.1.91) -- Various PreToolUse hook fixes for JSON stdout (CC 2.1.90) -- Auto mode boundary respect fixes (CC 2.1.90) -- PowerShell security hardening (CC 2.1.90) -- SSE transport performance fix (CC 2.1.90) -- `/resume` parallel session loading (CC 2.1.90) -- DNS cache commands removed from auto-allow (CC 2.1.90) -- CLAUDE_CODE_NO_FLICKER env var (CC 2.1.89) -- Edit/Read/Write symlink target checking fix (CC 2.1.89) -- Various voice mode fixes (CC 2.1.89) -- CRLF handling fixes (CC 2.1.89) -- StructuredOutput schema cache fix (CC 2.1.89) -- LSP server restart on crash (CC 2.1.89) -- Autocompact thrash loop detection (CC 2.1.89) -- Nested CLAUDE.md re-injection fix (CC 2.1.89) -- Hooks `if` condition fix for compound commands (CC 2.1.89) -- Thinking summaries disabled by default (CC 2.1.89) -- Team memory content display removed (CC 2.1.92) -- /pr-comments slash command removed (CC 2.1.91) -- Update Magic Docs agent prompt removed (CC 2.1.91) -- Memory attachment guidance updates (CC 2.1.90-2.1.91) -- Verification specialist prompt expansions (CC 2.1.89-2.1.90) -- Prompt caching documentation updates (CC 2.1.89) +**Rejected from Must Update:** +- `keep-coding-instructions` frontmatter field (CC 2.1.94) — REJECTED: This field is for OUTPUT STYLES, not skills. Plugin-dev already correctly documents this in `plugins/plugin-dev/skills/plugin-structure/references/output-styles.md`. No gap exists. + +**Version 2.1.98:** +- Interactive Google Vertex AI setup wizard -- infrastructure/setup feature +- Subprocess sandboxing with PID namespace isolation on Linux -- internal security +- Bash tool permission bypass security fix (backslash-escaped flags) -- security fix +- Bash tool compound command vulnerability fix -- security fix +- Stalled streaming responses fix -- bug fix +- 429 retry logic improvements -- infrastructure +- MCP OAuth configuration handling fix -- bug fix +- xterm keyboard protocol issues fix -- terminal compatibility +- macOS text replacements fix -- bug fix +- managed-settings persistence fix -- bug fix +- Permission rule matching for wildcards and piped commands fix -- bug fix +- UI issues in fullscreen mode fix -- bug fix +- `/resume` picker functionality fix -- bug fix + +**Version 2.1.97:** +- Cedar policy file syntax highlighting -- IDE feature +- Permission bypass fixes -- security fixes +- Bash tool security hardening (env-var prefixes) -- internal security +- MCP HTTP/SSE buffer management fix -- infrastructure +- 429 retry exponential backoff fix -- infrastructure +- MCP OAuth token refresh fix -- bug fix +- `/resume` picker cache miss and lost input fixes -- bug fix +- NO_FLICKER mode UI artifacts fixes -- bug fix +- Build with Claude API skill replaced with new routing version -- built-in CC skill change +- Buddy Mode removed -- built-in CC feature removal +- git_worktree field added to status line setup -- internal telemetry +- Verify skill restructured with probe strategies -- built-in CC skill change + +**Version 2.1.96:** +- Bedrock 403 Authorization header hotfix -- bug fix + +**Version 2.1.94:** +- Compact Slack headers with clickable channel links -- notification formatting +- Plugin hook execution issues fix -- bug fix (operational) +- Marketplace update problems with git submodules fix -- bug fix (operational) +- Console login failures on macOS fix -- bug fix +- Agents appearing stuck after rate-limit responses fix -- bug fix +- Scrollback duplication and multiline prompt indentation UI crashes -- bug fix +- Dream memory consolidation changes -- built-in CC memory system +- Dream memory pruning agent added -- built-in CC memory system +- Memory synthesis agent added -- built-in CC memory system +- Onboarding guide generator agent added -- built-in CC onboarding +- Session search agent (lightweight replacement) -- built-in CC feature +- Memory staleness verification system prompt -- built-in CC memory system +- Memory description of user details prompt -- built-in CC memory system +- Team onboarding guide skill -- built-in CC skill +- Worker fork prompt streamlined -- built-in CC agent change +- Build with Claude API subcommand dispatch -- built-in CC skill change +- Verify skill CI assumption relaxation -- built-in CC skill change +- Agent tool usage notes streamlined -- tool description change +- Worker fork execution prompt removed (replaced) -- internal refactor +- Session Search Assistant prompt removed (replaced) -- internal refactor +- Agent "when to launch" tool description folded into main -- internal refactor + +**Version 2.1.97 (system-prompts):** +- /dream nightly schedule skill -- built-in CC skill +- Live documentation sources updated (Managed Agents URLs) -- built-in CC docs +- Build with Claude API reference guide routing updated -- built-in CC skill +- Verify skill "Get a handle" and "Push on it" sections -- built-in CC skill +- ReadFile tool simplified to always require absolute paths (agent context) -- aligns with agent thread note change +- Write tool "prefer Edit" guidance made unconditional -- tool description change + +--- + +## Stage 2: Verification Results +### Verified: 2026-04-10 + +#### Must Update Verification + +- X **`keep-coding-instructions` frontmatter field for skills** (CC 2.1.94) — **REJECTED**: This field is for OUTPUT STYLES, not skills. The changelog entry mentions it alongside "compact Slack headers", and the system-prompts changelog for 2.1.94 does not mention this field at all. Plugin-dev already documents `keep-coding-instructions` correctly in `plugins/plugin-dev/skills/plugin-structure/references/output-styles.md` as an output style frontmatter field. No gap exists. + +- CHECK **Monitor tool for streaming background events** (CC 2.1.98) — confirmed in changelog and system-prompts ("NEW: Tool Description: Background monitor"). Gap exists in agent-development skill (Available Tools section does not mention Monitor tool). + +- INFO **Managed Agents API replaces Agent SDK** (CC 2.1.97) — confirmed in system-prompts (massive +23,865 token addition). However, plugin-dev does not reference Agent SDK anywhere. This is informational for potential future integration. **Reclassify to No Action** - no current gap exists in plugin-dev documentation. + +- CHECK **Agent threads now always require absolute file paths** (CC 2.1.97) — confirmed in system-prompts: "System Prompt: Agent thread notes -- Removed the conditional logic for relative vs. absolute file paths; agent threads now always require absolute file paths unconditionally." Gap exists - agent-development skill should note this requirement for agents. + +- ARROW_DOWN **Communication style system prompts** (CC 2.1.98) — confirmed in system-prompts. **Demote to May Update**: These are Claude Code behavioral guidelines, not plugin API changes. May be useful context for skill writing but not a direct gap. + +- ARROW_DOWN **Exploratory questions system prompt** (CC 2.1.98) — confirmed in system-prompts. **Demote to May Update**: This is Claude Code behavior, not plugin-specific. May inform skill design but not a documentation gap. + +#### Missed Items (promoted from No Action) + +- ! **Plugin skill hooks fixed in CC 2.1.94** — The changelog states "Fixed plugin skill hooks defined in YAML frontmatter being silently ignored" and "Fixed plugin hooks failing with 'No such file or directory' when CLAUDE_PLUGIN_ROOT was not set" and "Fixed ${CLAUDE_PLUGIN_ROOT} resolving to marketplace source instead of installed cache for local-marketplace plugins". These are CRITICAL bug fixes for plugin developers. While they don't require doc updates (bugs are now fixed), they should be noted in the compatibility tracker. + - Affects: docs/claude-code-compatibility.md + - Details: These fixes resolve issues with scoped hooks in skill frontmatter and CLAUDE_PLUGIN_ROOT path resolution that affected plugin developers. + +- ! **Skill invocation names changed (CC 2.1.94)** — "Plugin skills declared via 'skills': ['./'] now use the skill's frontmatter `name` for invocation instead of directory basename". This affects how skills are invoked. + - Affects: skill-development skill (skill naming section) + - Details: Skills now use frontmatter `name` for invocation, not directory name. This is relevant for skill naming guidance. + +#### May Update Resolution + +- = **CLAUDE_CODE_PERFORCE_MODE** — kept as May Update: Environment variable for read-only file handling. Not directly plugin-related but could be mentioned in environment variables reference if one exists. + +- = **CLAUDE_CODE_USE_MANTLE=1** — kept as May Update: Amazon Bedrock support env var. Not directly plugin-related. + +- = **Default effort level changed from medium to high** — kept as May Update: Affects API-key and Team/Enterprise users. May be relevant if agent-development mentions effort levels (it does not currently). + +- = **Worker fork agent metadata changes** — kept as May Update: Internal agent system changes. Minor documentation alignment opportunity. + +- = **Dream team memory handling** — kept as May Update: Built-in CC memory system, not plugin-related. + +- = **Focus view toggle (Ctrl+O)** — kept as May Update: UI feature, not plugin-related. + +- = **refreshInterval status line setting** — kept as May Update: Configuration setting, not directly plugin-related. + +#### Summary + +- Must Update: 6 items originally -> 2 confirmed, 1 rejected, 2 demoted, 2 added = **4 items total** + - Confirmed: Monitor tool, Agent absolute paths + - Promoted: Plugin hook fixes (compatibility note), Skill invocation names +- May Update: 7 items originally + 2 demoted = **9 items remaining** +- Confidence: **HIGH** — The manifest's main error was misattributing `keep-coding-instructions` to skills when it's an output style field. Plugin-dev already documents this correctly. --- @@ -137,66 +237,58 @@ 1. **Degraded triangulation**: The claude-code-guide agent was not available in this CI environment, so cross-referencing against official docs was not performed. Changes are confirmed via changelog and system-prompts sources only. -2. **High-priority items for plugin-dev**: - - The `defer` permission decision is a significant addition to the hooks system - - PermissionDenied hook expansion affects auto-mode integration - - Plugin `bin/` directory support is a new plugin capability - - `disableSkillShellExecution` setting affects how skills execute - - Write tool "always prefer Edit" guidance may affect our examples - - Sleep tool removal affects tool documentation +2. **High-priority items for plugin-dev** (verified): + - The Monitor tool is a new tool that agents can use (CC 2.1.98) + - Agent threads now unconditionally require absolute file paths (CC 2.1.97) + - Plugin skill hooks and CLAUDE_PLUGIN_ROOT fixes are critical bug fixes (CC 2.1.94) + - Skill invocation now uses frontmatter `name` instead of directory basename (CC 2.1.94) + - Note: `keep-coding-instructions` is for output styles, NOT skills (already documented correctly) 3. **System-prompts changelog is more authoritative** for prompt/tool description changes, while the GitHub changelog captures user-facing features and settings. 4. **Token delta summary**: - - 2.1.89: +3,986 tokens (MCP truncation, remote plan mode, buddy mode, computer use MCP skill) - - 2.1.90: +815 tokens (memory attachment, security monitor expansion) - - 2.1.91: +2,043 tokens (Agent Design Patterns skill, tool description updates) - - 2.1.92: -167 tokens (hook evaluator specialization, Sleep tool removal, Write tool guidance) + - 2.1.94: +2,000 tokens (Dream agents, memory synthesis, onboarding guide, session search) + - 2.1.96: +0 tokens (hotfix only) + - 2.1.97: +23,865 tokens (Managed Agents documentation - massive addition) + - 2.1.98: +2,045 tokens (Communication style, dream team memory, exploratory questions, background monitor) + +5. **Note on version 2.1.93/2.1.95**: Neither the upstream changelog nor the system-prompts changelog show entries for versions 2.1.93 or 2.1.95. These versions may have been internal releases, skipped, or contained only infrastructure changes not reflected in public changelogs. --- -## Stage 2: Verification Results -### Verified: 2026-04-04 +## Raw Changelog Excerpts -#### Must Update Verification -- ✓ **PreToolUse hooks can return `"defer"` permission decision** (CC 2.1.89) -- confirmed in changelog, gap exists in hook-development/SKILL.md line 322 (only shows `allow|deny|ask`, missing `defer`) -- ✗ **PermissionDenied hook now fires after auto mode classifier denials** (CC 2.1.89) -- REJECTED: already documented at hook-development/SKILL.md lines 385-423 (added in previous 2.1.88 sync) -- ✓ **MCP tool result persistence override via `_meta` annotation** (CC 2.1.91) -- confirmed in changelog, gap exists in mcp-integration/SKILL.md (no mention of maxResultSizeChars) -- ✓ **`disableSkillShellExecution` setting** (CC 2.1.91) -- confirmed in changelog, gap exists in skill-development/SKILL.md (not documented) -- ✓ **Plugins can ship executables under `bin/` directory** (CC 2.1.91) -- confirmed in changelog, gap exists in plugin-structure/SKILL.md (not documented) -- ↓ **`/tag` and `/vim` commands removed** (CC 2.1.92) -- demoted to No Action: built-in commands not documented in plugin-dev -- ↓ **Write tool guidance changed: always prefer Edit** (CC 2.1.92) -- demoted to No Action: not plugin-dev scope (tool descriptions) -- ↓ **Hook condition evaluator specialized for stop conditions** (CC 2.1.92) -- demoted to No Action: internal implementation detail, no plugin API surface change -- ↓ **Sleep tool removed** (CC 2.1.92) -- demoted to No Action: not plugin-dev scope (built-in tools) -- ↓ **Agent Design Patterns skill added** (CC 2.1.91) -- demoted to No Action: built-in CC skill, not plugin-dev documentation scope - -#### Skill Mapping Corrections -- ! **skill-anatomy** -- INCORRECT: skill does not exist; should be `skill-development` -- ! **plugin-json-schema** -- INCORRECT: skill does not exist; should be `plugin-structure` -- ! **slash-commands** -- INCORRECT: skill does not exist; should be `command-development` -- ! **build-with-claude-api** -- INCORRECT: skill does not exist in plugin-dev (built-in CC skill) +### Version 2.1.98 +``` +- Interactive Google Vertex AI setup wizard +- CLAUDE_CODE_PERFORCE_MODE environment variable for read-only file handling +- Monitor tool for streaming background events to foreground session +- Subprocess sandboxing with PID namespace isolation on Linux +- Security: Bash tool permission bypass (backslash-escaped flags, compound commands) +- Fixes: stalled streaming, 429 retry, MCP OAuth, xterm keyboard, macOS text replacements, + managed-settings persistence, permission rules, fullscreen UI, /resume picker +``` -#### Missed Items (promoted from No Action) -- None identified. Scanned changelog for: hook, plugin, agent, skill, command, MCP, LSP, tool, permission, subagent, frontmatter, manifest, plugin.json, PreToolUse, PostToolUse, SessionStart, Stop. All relevant items were captured. +### Version 2.1.97 +``` +- Focus view toggle (Ctrl+O) for NO_FLICKER mode +- refreshInterval status line setting +- Cedar policy file syntax highlighting +- Security: Permission bypass fixes, Bash tool env-var prefix hardening +- Fixes: MCP HTTP/SSE buffer, 429 retry, OAuth token refresh, /resume picker, NO_FLICKER UI +``` -#### May Update Resolution -- ↓ **Named subagents in `@` mention typeahead** (CC 2.1.89) -- demoted to No Action: UX feature, no plugin API impact -- = **`MCP_CONNECTION_NONBLOCKING=true` env var** (CC 2.1.89) -- kept as May Update: could document in mcp-integration references -- ↓ **`/powerup` command added** (CC 2.1.90) -- demoted to No Action: built-in command, not plugin-dev scope -- ↓ **`CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` env var** (CC 2.1.90) -- demoted to No Action: operational env var, not plugin development -- ↓ **`.husky` added to protected directories** (CC 2.1.90) -- demoted to No Action: permissions detail, not plugin-dev scope -- ↓ **`forceRemoteSettingsRefresh` policy setting** (CC 2.1.92) -- demoted to No Action: managed settings, not plugin-dev scope -- = **MCP tool truncation guidance updated** (CC 2.1.92) -- kept as May Update: could document in mcp-integration subagent guidance -- = **ReadFile tool supports relative paths** (CC 2.1.91) -- kept as May Update: could affect skill script examples -- ↓ **Edit tool guidelines made configurable** (CC 2.1.91) -- demoted to No Action: not plugin-dev scope -- ↓ **Computer Use MCP skill added** (CC 2.1.89) -- demoted to No Action: built-in CC skill, not plugin-dev scope -- ↓ **Remote plan mode (ultraplan) prompt added** (CC 2.1.89) -- demoted to No Action: built-in CC feature -- ↓ **Buddy Mode prompt added** (CC 2.1.89) -- demoted to No Action: built-in CC feature -- ↓ **Security monitor prompt significantly expanded** (CC 2.1.89-2.1.90) -- demoted to No Action: internal security, not plugin API +### Version 2.1.96 +``` +- Hotfix: Bedrock requests failing with 403 Authorization header is missing +``` -#### Summary -- Must Update: 4 items confirmed (defer decision, MCP maxResultSizeChars, disableSkillShellExecution, plugin bin/) -- Must Update: 6 items demoted to No Action (not plugin-dev scope) -- May Update: 3 items remaining (MCP_CONNECTION_NONBLOCKING, MCP truncation guidance, ReadFile relative paths) -- Skill Mapping: 4 corrections needed (skill names were incorrect in original manifest) -- Confidence: HIGH -- Changes verified against primary sources; skill file gaps confirmed by reading actual SKILL.md files +### Version 2.1.94 +``` +- Amazon Bedrock support via Mantle (CLAUDE_CODE_USE_MANTLE=1) +- Default effort level changed from medium to high +- Compact Slack headers with clickable channel links +- keep-coding-instructions frontmatter field support +- Fixes: agents stuck after rate-limit, Console login on macOS, plugin hook execution, + marketplace updates with git submodules, scrollback duplication, multiline prompt indentation +``` diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6b20e1b..005f24e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.10.1" + "version": "0.10.2" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.10.1", + "version": "0.10.2", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index 55fd8c8..abc2df5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.2] - 2026-04-10 + +### Added + +- **agent-development**: Documented Monitor tool for streaming background events as chat notifications (CC 2.1.98) +- **agent-development**: Documented that agent threads always require absolute file paths unconditionally (CC 2.1.97) +- **skill-development**: Documented that plugin skills use frontmatter `name` for invocation instead of directory basename (CC 2.1.94) + +### Changed + +- **claude-code-compatibility**: Updated to CC 2.1.98 with notes on plugin skill hooks and CLAUDE_PLUGIN_ROOT fixes (CC 2.1.94) + ## [0.10.1] - 2026-04-07 ### Fixed @@ -350,7 +362,8 @@ 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/kylesnowschwartz/plugin-dev/compare/v0.10.1...HEAD +[Unreleased]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.2...HEAD +[0.10.2]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.1...v0.10.2 [0.10.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.0...v0.10.1 [0.10.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.9.0...v0.10.0 [0.9.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.8.0...v0.9.0 diff --git a/CLAUDE.md b/CLAUDE.md index ead9923..439ad18 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 11 skills, 7 agents, 3 slash commands. -**Version**: v0.10.1 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.10.2 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md index 1b58778..93583c3 100644 --- a/docs/claude-code-compatibility.md +++ b/docs/claude-code-compatibility.md @@ -1,12 +1,13 @@ # Claude Code Compatibility -Last audited: Claude Code 2.1.92 (2026-04-04) -Plugin-dev version: 0.10.0 +Last audited: Claude Code 2.1.98 (2026-04-10) +Plugin-dev version: 0.10.2 ## Audit Log | plugin-dev | CC version range | Date | Notes | |---|---|---|---| +| v0.10.2 | 2.1.94-2.1.98 | 2026-04-10 | Monitor tool for background events, agent absolute path requirement, skill invocation name change, plugin skill hook/CLAUDE_PLUGIN_ROOT fixes | | v0.10.0 | 2.1.89-2.1.92 | 2026-04-04 | PreToolUse `defer` decision, MCP maxResultSizeChars (500K), disableSkillShellExecution setting, plugin bin/ directory | | v0.9.0 | 2.1.87-2.1.88 | 2026-03-31 | PermissionDenied hook (25th event), file_path absolute paths, `if` compound command fix, partial compaction, Config tool | | v0.8.0 | 2.1.85-2.1.86 | 2026-03-29 | Hook `if` field, AskUserQuestion via updatedInput, skill 250-char cap, alphabetical /skills, org plugin blocking, MCP env vars, agent prompt change, fork naming, Production Reads | diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index f8e3875..ce4a2d8 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.10.1", + "version": "0.10.2", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 3707cac..e4a742b 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -248,6 +248,7 @@ tools: Read, Write, Grep, Bash - Code generation: `Read, Write, Grep` - Testing: `Read, Bash, Grep` - Configuration: `Config` (CC 2.1.88) - get/set Claude Code settings +- Background monitoring: `Monitor` (CC 2.1.98) - stream stdout events from long-running scripts as chat notifications - Full access: Omit field entirely > **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. @@ -520,6 +521,10 @@ Run the validation script at `${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh` This variable resolves to the plugin's installation directory at runtime, ensuring paths work regardless of where the plugin is installed. +### Absolute File Paths Required (CC 2.1.97) + +Agent threads always require absolute file paths unconditionally. When agents use file operations (Read, Write, Edit, etc.), all paths must be absolute—relative paths are not supported in agent contexts. Use `${CLAUDE_PLUGIN_ROOT}` or construct absolute paths from known locations. + ### Namespacing Agents are namespaced automatically: diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index 5fa9ce9..50414de 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -50,6 +50,8 @@ Skills follow precedence: Enterprise > Personal (`~/.claude/skills/`) > Project **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). +**Skill Invocation Name (CC 2.1.94):** Plugin skills declared via `"skills": ["./"]` now use the skill's frontmatter `name` for invocation instead of the directory basename. Ensure the `name` field in frontmatter matches how users should invoke the skill. + #### Optional Frontmatter Fields ##### allowed-tools From 7edf90e89e6f152ee9d34f8836b91c6f43f0e68b Mon Sep 17 00:00:00 2001 From: kylesnowschwartz Date: Sat, 11 Apr 2026 23:21:08 +1200 Subject: [PATCH 31/33] docs: document skill/agent composition model and prompt ownership Clarify that when a skill uses `context: fork` with `agent:`, the agent definition provides the system prompt and the skill body provides the task prompt. Add comparison table for declarative skill+agent vs direct Agent tool calls. Cross-reference between both skill-development and agent-development docs. --- .../skills/agent-development/SKILL.md | 13 +++++++- .../skills/skill-development/SKILL.md | 30 +++++++++++++++++-- 2 files changed, 39 insertions(+), 4 deletions(-) diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index e4a742b..7947900 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -400,7 +400,18 @@ Some frontmatter fields are specific to skills and do not apply to agents: | `disable-model-invocation` | Block programmatic Skill tool usage | Agents use Task tool, not Skill tool | | `allowed-tools` | Restrict tool access (skill syntax) | Agents use `tools` field instead (different field name) | -**Key distinction:** Skills provide knowledge and guidance that loads into context. Agents are autonomous subprocesses that execute independently. This architectural difference explains why context-forking options don't apply to agents—they're already isolated processes. +**Key distinction:** Skills provide knowledge and guidance that loads into context. Agents are autonomous subprocesses that execute independently. This architectural difference explains why context-forking options don't apply to agents — they're already isolated processes. + +### How Agents Compose with Skills + +A skill with `context: fork` and `agent: your-agent-name` creates a clean separation: + +- **Agent definition** (the `.md` file in `agents/`) → becomes the **system prompt**. This controls behavior, tools, MCP servers, and hooks. +- **Skill body** (the SKILL.md content) → becomes the **task prompt**. This is the work the agent receives. + +The forked agent does not inherit conversation history. One agent can serve many skills, each providing a different task. This is the declarative alternative to spawning agents directly via the Agent tool — use it when the task instructions are stable and you want automatic trigger matching with prompt cache sharing. For dynamic prompts or parallel orchestration, use direct Agent tool calls instead. + +See the `skill-development` skill for the full comparison table. ## System Prompt Design diff --git a/plugins/plugin-dev/skills/skill-development/SKILL.md b/plugins/plugin-dev/skills/skill-development/SKILL.md index 50414de..274bed2 100644 --- a/plugins/plugin-dev/skills/skill-development/SKILL.md +++ b/plugins/plugin-dev/skills/skill-development/SKILL.md @@ -99,7 +99,7 @@ Use `context: fork` for: ##### agent -Specify which agent type handles the skill when `context: fork` is set: +Specify which agent type handles the forked skill. The agent provides the **execution environment** (system prompt, tools, behavioral rules). The skill body provides the **task** (what to do). The forked agent does not inherit your conversation history. ```yaml --- @@ -108,16 +108,40 @@ description: Explore codebase patterns... context: fork agent: Explore --- +Find all React components that accept a `userId` prop and trace how they fetch user data. ``` +In this example, the `Explore` agent's system prompt controls behavior and available tools. The skill body ("Find all React components...") becomes the task prompt the agent receives. + **Values:** -- `Explore` - Fast agent for codebase exploration +- `Explore` - Fast, read-only agent for codebase exploration - `Plan` - Architect agent for implementation planning -- `general` - General-purpose agent (default if `context: fork`) +- `general-purpose` - Full-capability agent (default when `context: fork` is set) +- Custom agent name - Any agent defined in `.claude/agents/` or by a plugin + +When using a custom agent, you control both sides: the agent definition sets the system prompt, tools, MCP servers, and hooks. The skill sets the task and triggering conditions. This lets one agent serve many skills, and the same skill shape could target different agents. + +**Design guidance:** Put *what to do* in the skill. Put *how to behave* in the agent definition. Requires `context: fork` to be set. +##### Skill + Agent vs. Direct Agent Tool Call + +Both approaches delegate work to a sub-agent, but they serve different design needs: + +| Dimension | Skill `context: fork` | Direct Agent tool call | +|---|---|---| +| **Interface** | Declarative YAML + markdown body | Imperative prompt string | +| **Triggering** | Automatic (description matching) | Manual (caller decides when) | +| **Context** | Inherits parent context, shares prompt cache | Fresh start, no inherited context | +| **Task prompt** | SKILL.md body (static) | Whatever you pass at runtime (dynamic) | +| **System prompt** | From agent type or agent definition | From `subagent_type` | + +**Use skill `context: fork`** when the task instructions are stable, the trigger is predictable, and you want automatic invocation with cache sharing. + +**Use direct Agent calls** when you need dynamic prompts computed at runtime, parallel orchestration (spawning N agents from a loop), or worktree isolation for parallel git branches. + ##### skills Load other skills into the forked agent's context: From f78c5c60e311edf7f356da9d18ad3f8b55893b10 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 16 Apr 2026 07:02:01 +0000 Subject: [PATCH 32/33] docs: sync plugin-dev with Claude Code v2.1.99-v2.1.110 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BREAKING: Update allowed-tools syntax from colon-separated to space-separated - Update all `Bash(X:*)` patterns to `Bash(X *)` per CC 2.1.108 - Add PreCompact hook blocking capability (exit 2, CC 2.1.105) - Add monitors manifest key documentation (CC 2.1.105) - Version bump: 0.10.2 → 0.10.3 Files updated: - command-development skill and references - plugin-structure references (github-actions, headless-ci-mode, manifest-reference) - hook-development SKILL.md and event-schemas - /create-plugin and /create-marketplace commands - docs (workflow-security.md, CONTRIBUTING.md) Note: CI workflow files excluded (require workflows permission to update) Co-Authored-By: Claude Opus 4.5 --- .agent-history/upstream-changes.md | 493 +++++++++--------- .claude-plugin/marketplace.json | 4 +- CHANGELOG.md | 22 +- CLAUDE.md | 2 +- CONTRIBUTING.md | 2 +- docs/claude-code-compatibility.md | 5 +- docs/workflow-security.md | 6 +- plugins/plugin-dev/.claude-plugin/plugin.json | 2 +- .../plugin-dev/commands/create-marketplace.md | 2 +- plugins/plugin-dev/commands/create-plugin.md | 2 +- .../skills/command-development/SKILL.md | 16 +- .../examples/plugin-commands.md | 4 +- .../examples/simple-commands.md | 12 +- .../references/advanced-workflows.md | 12 +- .../references/documentation-patterns.md | 2 +- .../references/frontmatter-reference.md | 22 +- .../references/plugin-features-reference.md | 10 +- .../references/plugin-integration.md | 4 +- .../references/skill-tool.md | 14 +- .../references/testing-strategies.md | 4 +- .../scripts/check-frontmatter.sh | 2 +- .../skills/hook-development/SKILL.md | 6 +- .../references/event-schemas.md | 8 +- .../references/github-actions.md | 2 +- .../references/headless-ci-mode.md | 2 +- .../references/manifest-reference.md | 36 ++ 26 files changed, 381 insertions(+), 315 deletions(-) diff --git a/.agent-history/upstream-changes.md b/.agent-history/upstream-changes.md index 39415bc..9240cf7 100644 --- a/.agent-history/upstream-changes.md +++ b/.agent-history/upstream-changes.md @@ -1,294 +1,299 @@ # Upstream Change Manifest -## CC Version Range: 2.1.93 - 2.1.98 -## Generated: 2026-04-10 -## Sources: changelog [OK], system-prompts [OK], claude-code-guide [failed - agent not available in CI] +## CC Version Range: 2.1.99 - 2.1.110 +## Generated: 2026-04-16 +## Sources: changelog [Y], system-prompts [Y], claude-code-guide [skipped] --- -### Must Update - -- [ ] **Monitor tool for streaming background events** (CC 2.1.98) - - Source: changelog, system-prompts (NEW: Tool Description: Background monitor) - - Confidence: high - - Affects: agent-development skill (Available Tools section), tool documentation - - Details: New tool that streams stdout events from long-running scripts as chat notifications. System prompts include guidelines on script quality, output volume, and selective filtering. - - Raw changelog: "Monitor tool for streaming background events to foreground session" - - System-prompts: "NEW: Tool Description: Background monitor (streaming events) -- Added description for a background monitor tool that streams stdout events from long-running scripts as chat notifications" - - Gap: New tool not documented in agent-development or tool references - -- [ ] **Agent threads now always require absolute file paths** (CC 2.1.97) - - Source: system-prompts only - - Confidence: high - - Affects: agent-development skill (Agent Best Practices section) - - Details: Removed conditional logic for relative vs. absolute paths in agent threads. Agents must now always use absolute file paths unconditionally. This reverses/clarifies the 2.1.91 change that added relative path support. - - System-prompts: "System Prompt: Agent thread notes -- Removed the conditional logic for relative vs. absolute file paths; agent threads now always require absolute file paths unconditionally" - - Gap: agent-development skill may need to clarify absolute path requirement for agents - -- [ ] **Plugin skill hooks and CLAUDE_PLUGIN_ROOT fixes** (CC 2.1.94) - - Source: changelog - - Confidence: high - - Affects: docs/claude-code-compatibility.md, hook-development skill (bug fixes note) - - Details: Three critical bug fixes: (1) Plugin skill hooks in YAML frontmatter were silently ignored - now fixed; (2) Plugin hooks failed with "No such file or directory" when CLAUDE_PLUGIN_ROOT was not set - now fixed; (3) ${CLAUDE_PLUGIN_ROOT} resolved to marketplace source instead of installed cache for local-marketplace plugins - now fixed. - - Raw changelog: "Fixed plugin skill hooks defined in YAML frontmatter being silently ignored", "Fixed plugin hooks failing with 'No such file or directory' when CLAUDE_PLUGIN_ROOT was not set", "Fixed ${CLAUDE_PLUGIN_ROOT} resolving to marketplace source instead of installed cache for local-marketplace plugins" - - Gap: Compatibility tracker needs update; hook-development may note these were fixed - -- [ ] **Skill invocation name change** (CC 2.1.94) - - Source: changelog - - Confidence: high - - Affects: skill-development skill (naming section) - - Details: Plugin skills declared via "skills": ["./"] now use the skill's frontmatter `name` for invocation instead of directory basename. This changes how skills are discovered and invoked. - - Raw changelog: "Plugin skills declared via 'skills': ['./'] now use the skill's frontmatter name for invocation instead of directory basename" - - Gap: skill-development should note that frontmatter `name` is used for invocation, not directory name +### Must Update (Stage 2 Verified) ---- - -### May Update +- [ ] **CRITICAL: Allowed-tools syntax change: colon-separated to space-separated** (CC 2.1.108) + - Source: system-prompts + - Confidence: HIGH - verified by Stage 2 + - Affects: skill-development, command-development, permission examples + - Details: All `allowed-tools` examples updated from colon-separated (`Bash(npm:*)`, `git diff:*`) to space-separated (`Bash(npm *)`, `git diff *`) Bash pattern syntax. This is a breaking change for skill authors. + - Files requiring update: + - `skills/command-development/SKILL.md` line 534 + - `skills/command-development/references/frontmatter-reference.md` line 104 + - `skills/command-development/references/advanced-workflows.md` lines 121, 148 + - `skills/command-development/examples/simple-commands.md` line 100 + - `skills/plugin-structure/references/github-actions.md` line 118 + +- [ ] **PreCompact hook blocking capability** (CC 2.1.105) + - Source: changelog, system-prompts + - Confidence: HIGH - verified by Stage 2 + - Affects: hook-development + - Details: PreCompact hooks can now block compaction by returning exit code 2 or `{"decision":"block"}`. The PreCompact event already exists in docs but blocking capability is new. + - Action: Add blocking capability to PreCompact documentation in hook-development/SKILL.md + +- [ ] **Background monitor "silence is not success" guidance** (CC 2.1.105) + - Source: changelog, system-prompts + - Confidence: HIGH - verified by Stage 2 + - Affects: hook-development, agent-development + - Details: Updated guidance requiring monitors to match all terminal states (failures, crashes, OOM), not just happy path. Top-level `monitors` manifest key added for plugin support. + - Action: Update existing Monitor tool mention in agent-development and add guidance to hook-development or plugin-structure -- [ ] **Communication style system prompts added** (CC 2.1.98) - - Source: system-prompts only - - Confidence: medium - - Affects: skill-development skill (skill writing best practices) - - Details: New system prompts for communication style guidelines. May be useful context for skill writing guidance but not a direct plugin API change. +--- -- [ ] **Exploratory questions system prompt** (CC 2.1.98) - - Source: system-prompts only - - Confidence: medium - - Affects: skill-development skill (trigger design best practices) - - Details: Claude now analyzes before implementing on open-ended questions. May inform skill design but not a documentation gap. +### May Update (Stage 2 Verified) -- [ ] **Managed Agents API replaces Agent SDK** (CC 2.1.97) +- [ ] **Agent tool "trust but verify" guidance** (CC 2.1.105) - Source: system-prompts - - Confidence: high - - Affects: potential future plugin-dev integration - - Details: Major architectural change in Claude Code's built-in API documentation. Plugin-dev does not currently reference Agent SDK, so no stale references exist. Informational only for now. - -- [ ] **CLAUDE_CODE_PERFORCE_MODE environment variable** (CC 2.1.98) - - Source: changelog only - Confidence: medium - - Affects: potential environment variable documentation - - Details: New env var for read-only file handling in Perforce environments. - - Raw changelog: "`CLAUDE_CODE_PERFORCE_MODE` environment variable for read-only file handling" + - Affects: agent-development best practices + - Details: New guidance instructing Claude to check actual code changes from agents before reporting work as done, rather than relying solely on agent summaries. + - Stage 2 note: Could enhance agent-development skill with verification guidance. Keep as May Update. -- [ ] **CLAUDE_CODE_USE_MANTLE=1 for Amazon Bedrock via Mantle** (CC 2.1.94) - - Source: changelog only +- [ ] **Verify skill restructured** (CC 2.1.97, updates through 2.1.105) + - Source: system-prompts - Confidence: medium - - Affects: potential environment variable documentation - - Details: New env var enabling Amazon Bedrock support via Mantle. - - Raw changelog: "Added Amazon Bedrock support via Mantle with `CLAUDE_CODE_USE_MANTLE=1` environment variable" + - Affects: testing/verification patterns + - Details: Major restructure emphasizing checking `.claude/skills/` for verifier skills first, new "Push on it" section with probing strategies by change type. + - Stage 2 note: Could inform testing patterns in plugin development. Keep as May Update. -- [ ] **Default effort level changed from medium to high** (CC 2.1.94) - - Source: changelog, system-prompts (Build with Claude API skill update) +- [ ] **Heredoc piping guidance for REPL/Bash** (CC 2.1.110) + - Source: system-prompts - Confidence: medium - - Affects: agent-development references (if any mention effort levels) - - Details: Changed default effort level from medium to high for API-key and Team/Enterprise users. System prompts updated effort parameter guidance. - - Raw changelog: "Changed default effort level from medium to high for API-key and Team/Enterprise users" - -- [ ] **Worker fork agent metadata changes** (CC 2.1.97) - - Source: system-prompts only - - Confidence: low - - Affects: agent-development skill (fork/subagent patterns) - - Details: Added agent metadata specifying model inheritance, permission bubbling, max turns, full tool access, and description of when forks are triggered. Minor documentation alignment opportunity. - - System-prompts: "Agent Prompt: Worker fork -- Added agent metadata specifying model inheritance, permission bubbling, max turns, full tool access" - -- [ ] **Dream team memory handling** (CC 2.1.98) - - Source: system-prompts only - - Confidence: low - - Affects: potential memory-related skill references - - Details: New system prompt for handling shared team memories during dream consolidation, including deduplication and conservative pruning rules. - -- [ ] **Focus view toggle (Ctrl+O) for NO_FLICKER mode** (CC 2.1.97) - - Source: changelog only - - Confidence: low - - Affects: potential UI/keybinding documentation - - Details: New keyboard shortcut for focus view displaying prompt and tool summaries. - -- [ ] **refreshInterval status line setting** (CC 2.1.97) - - Source: changelog only - - Confidence: low - - Affects: potential configuration documentation - - Details: New setting for controlling status line refresh interval. + - Affects: command-development, script execution + - Details: Added guidance to pipe via heredoc instead of writing temp files for shell commands, warning that generic temp paths get clobbered by parallel agents. + - Stage 2 note: Relevant to script execution patterns in hooks and commands. Keep as May Update. --- -### No Action - -**Rejected from Must Update:** -- `keep-coding-instructions` frontmatter field (CC 2.1.94) — REJECTED: This field is for OUTPUT STYLES, not skills. Plugin-dev already correctly documents this in `plugins/plugin-dev/skills/plugin-structure/references/output-styles.md`. No gap exists. - -**Version 2.1.98:** -- Interactive Google Vertex AI setup wizard -- infrastructure/setup feature -- Subprocess sandboxing with PID namespace isolation on Linux -- internal security -- Bash tool permission bypass security fix (backslash-escaped flags) -- security fix -- Bash tool compound command vulnerability fix -- security fix -- Stalled streaming responses fix -- bug fix -- 429 retry logic improvements -- infrastructure -- MCP OAuth configuration handling fix -- bug fix -- xterm keyboard protocol issues fix -- terminal compatibility -- macOS text replacements fix -- bug fix -- managed-settings persistence fix -- bug fix -- Permission rule matching for wildcards and piped commands fix -- bug fix -- UI issues in fullscreen mode fix -- bug fix -- `/resume` picker functionality fix -- bug fix - -**Version 2.1.97:** -- Cedar policy file syntax highlighting -- IDE feature -- Permission bypass fixes -- security fixes -- Bash tool security hardening (env-var prefixes) -- internal security -- MCP HTTP/SSE buffer management fix -- infrastructure -- 429 retry exponential backoff fix -- infrastructure -- MCP OAuth token refresh fix -- bug fix -- `/resume` picker cache miss and lost input fixes -- bug fix -- NO_FLICKER mode UI artifacts fixes -- bug fix -- Build with Claude API skill replaced with new routing version -- built-in CC skill change -- Buddy Mode removed -- built-in CC feature removal -- git_worktree field added to status line setup -- internal telemetry -- Verify skill restructured with probe strategies -- built-in CC skill change - -**Version 2.1.96:** -- Bedrock 403 Authorization header hotfix -- bug fix - -**Version 2.1.94:** -- Compact Slack headers with clickable channel links -- notification formatting -- Plugin hook execution issues fix -- bug fix (operational) -- Marketplace update problems with git submodules fix -- bug fix (operational) -- Console login failures on macOS fix -- bug fix -- Agents appearing stuck after rate-limit responses fix -- bug fix -- Scrollback duplication and multiline prompt indentation UI crashes -- bug fix -- Dream memory consolidation changes -- built-in CC memory system -- Dream memory pruning agent added -- built-in CC memory system -- Memory synthesis agent added -- built-in CC memory system -- Onboarding guide generator agent added -- built-in CC onboarding -- Session search agent (lightweight replacement) -- built-in CC feature -- Memory staleness verification system prompt -- built-in CC memory system -- Memory description of user details prompt -- built-in CC memory system -- Team onboarding guide skill -- built-in CC skill -- Worker fork prompt streamlined -- built-in CC agent change -- Build with Claude API subcommand dispatch -- built-in CC skill change -- Verify skill CI assumption relaxation -- built-in CC skill change -- Agent tool usage notes streamlined -- tool description change -- Worker fork execution prompt removed (replaced) -- internal refactor -- Session Search Assistant prompt removed (replaced) -- internal refactor -- Agent "when to launch" tool description folded into main -- internal refactor - -**Version 2.1.97 (system-prompts):** -- /dream nightly schedule skill -- built-in CC skill -- Live documentation sources updated (Managed Agents URLs) -- built-in CC docs -- Build with Claude API reference guide routing updated -- built-in CC skill -- Verify skill "Get a handle" and "Push on it" sections -- built-in CC skill -- ReadFile tool simplified to always require absolute paths (agent context) -- aligns with agent thread note change -- Write tool "prefer Edit" guidance made unconditional -- tool description change +### No Action (Stage 2 Verified) + +**Demoted from Must Update by Stage 2:** +- NEW REPL tool (CC 2.1.108) - Optional low-priority; no tool-reference skill exists in plugin-dev +- NEW PushNotification tool (CC 2.1.110) - Optional low-priority; no tool-reference skill exists +- EnterWorktree tool path parameter (CC 2.1.105) - Minor tool enhancement, low priority +- Agent tool renamed "Agent" to "R4" (CC 2.1.105) - Internal naming in disallowedTools, not user-facing +- /tui command (CC 2.1.110) - Built-in CC feature, not plugin development +- /team-onboarding command and skill (CC 2.1.101) - Built-in CC feature +- /insights command and skill (CC 2.1.101) - Built-in CC feature +- /loop dynamic mode and self-pacing (CC 2.1.101) - Built-in CC autonomous loop features +- /dream nightly schedule skill (CC 2.1.97) - Built-in CC memory feature +- Managed Agents documentation overhaul (CC 2.1.97+) - Anthropic API docs, not CC plugin dev +- Prompt caching TTL configuration (CC 2.1.108) - Internal env vars for API + +**Demoted from May Update by Stage 2:** +- Fork usage guidelines simplified (CC 2.1.105) - Internal CC guidance +- Communication style heading renamed (CC 2.1.104) - Internal naming +- Sleep duration guidance relaxed (CC 2.1.108) - Minor internal change +- Session recap feature (CC 2.1.108) - User feature, not plugin dev +- Sandbox Network Callback threat definition (CC 2.1.110) - Internal security +- Model catalog formatting (CC 2.1.108) - Cosmetic change + +**Original No Action (unchanged):** +- Thinking hints shown sooner during long operations (CC 2.1.107) +- Rotating progress hint for extended-thinking indicator (CC 2.1.109) +- OS CA certificate store trust by default (CC 2.1.101) +- Improved brief and focus modes (CC 2.1.101) +- Fixed paste functionality, session resume problems, terminal escape handling (CC 2.1.101) +- MCP tool call hang fixes (CC 2.1.110) +- Session cleanup fixes (CC 2.1.110) +- Permission rule enforcement fixes (CC 2.1.110) +- Stalled API stream handling improvements (CC 2.1.105) +- File write display improvements (CC 2.1.105) +- Improved error messaging for rate limits and server issues (CC 2.1.108) +- Thinking frequency tuning system reminder (CC 2.1.107) - internal behavior +- Memory synthesis restructured to fact-extraction format (CC 2.1.105) - internal agent +- Managed Agents SDK version requirements updates (CC 2.1.105) - API reference only +- Dream memory consolidation/pruning refinements (CC 2.1.97-2.1.105) - internal memory system +- Session search agent lightweight rewrite (CC 2.1.94) - internal agent +- Worker fork prompt streamlined (CC 2.1.94) - internal agent +- Status line git_worktree field (CC 2.1.97) - internal display +- Communication style tightened (CC 2.1.100) - internal behavior +- Exploratory questions prompt removed (CC 2.1.100) - internal behavior +- Output efficiency prompt removed (CC 2.1.100) - internal behavior +- User-facing communication style prompt removed (CC 2.1.100) - internal behavior +- Hook condition evaluator specialized for stop conditions (CC 2.1.92) - internal +- Sleep tool removed (CC 2.1.92) - replaced by Snooze +- MCP Tool Result Truncation guidance changes (CC 2.1.92) - internal behavior +- Remote plan mode diagram guidance rewritten (CC 2.1.92) - internal behavior +- Runtime-verification alias for Verify skill (CC 2.1.105) - internal alias +- Build Claude API and SDK apps skill trigger updates (CC 2.1.101-2.1.108) - built-in skill +- Autonomous loop check system prompt (CC 2.1.101) - internal loop behavior +- Schedule recurring cron skills (CC 2.1.101) - built-in scheduling skills +- Managed Agents onboarding flow agent prompt (CC 2.1.97/2.1.105) - API onboarding +- Managed Agents data files updates (CC 2.1.105) - API reference updates --- -## Stage 2: Verification Results -### Verified: 2026-04-10 - -#### Must Update Verification - -- X **`keep-coding-instructions` frontmatter field for skills** (CC 2.1.94) — **REJECTED**: This field is for OUTPUT STYLES, not skills. The changelog entry mentions it alongside "compact Slack headers", and the system-prompts changelog for 2.1.94 does not mention this field at all. Plugin-dev already documents `keep-coding-instructions` correctly in `plugins/plugin-dev/skills/plugin-structure/references/output-styles.md` as an output style frontmatter field. No gap exists. +## Summary (Stage 2 Corrected) -- CHECK **Monitor tool for streaming background events** (CC 2.1.98) — confirmed in changelog and system-prompts ("NEW: Tool Description: Background monitor"). Gap exists in agent-development skill (Available Tools section does not mention Monitor tool). +**3 Must Update items** (verified by Stage 2): +1. **CRITICAL: Allowed-tools syntax change** (colon to space-separated) - breaking change affecting 6+ files +2. PreCompact hook blocking capability (exit code 2 / decision:block) +3. Background monitor "silence is not success" guidance and plugin support -- INFO **Managed Agents API replaces Agent SDK** (CC 2.1.97) — confirmed in system-prompts (massive +23,865 token addition). However, plugin-dev does not reference Agent SDK anywhere. This is informational for potential future integration. **Reclassify to No Action** - no current gap exists in plugin-dev documentation. +**3 May Update items** (verified by Stage 2): +1. Agent tool "trust but verify" guidance +2. Verify skill restructured (probing strategies) +3. Heredoc piping guidance for REPL/Bash -- CHECK **Agent threads now always require absolute file paths** (CC 2.1.97) — confirmed in system-prompts: "System Prompt: Agent thread notes -- Removed the conditional logic for relative vs. absolute file paths; agent threads now always require absolute file paths unconditionally." Gap exists - agent-development skill should note this requirement for agents. +**40+ No Action items** - includes 11 demoted from original Must Update (built-in CC features, API docs, internal changes) and 6 demoted from May Update -- ARROW_DOWN **Communication style system prompts** (CC 2.1.98) — confirmed in system-prompts. **Demote to May Update**: These are Claude Code behavioral guidelines, not plugin API changes. May be useful context for skill writing but not a direct gap. +## Notes -- ARROW_DOWN **Exploratory questions system prompt** (CC 2.1.98) — confirmed in system-prompts. **Demote to May Update**: This is Claude Code behavior, not plugin-specific. May inform skill design but not a documentation gap. +1. **Degraded triangulation**: The claude-code-guide agent was skipped due to CI environment limitations. Changes are confirmed via changelog and system-prompts sources only. -#### Missed Items (promoted from No Action) +2. **Critical: Allowed-tools syntax change** - The change from colon-separated to space-separated patterns (`Bash(npm:*)` -> `Bash(npm *)`) is significant and may affect existing skills that use permissions. This should be verified and updated in the skill-authoring documentation immediately. -- ! **Plugin skill hooks fixed in CC 2.1.94** — The changelog states "Fixed plugin skill hooks defined in YAML frontmatter being silently ignored" and "Fixed plugin hooks failing with 'No such file or directory' when CLAUDE_PLUGIN_ROOT was not set" and "Fixed ${CLAUDE_PLUGIN_ROOT} resolving to marketplace source instead of installed cache for local-marketplace plugins". These are CRITICAL bug fixes for plugin developers. While they don't require doc updates (bugs are now fixed), they should be noted in the compatibility tracker. - - Affects: docs/claude-code-compatibility.md - - Details: These fixes resolve issues with scoped hooks in skill frontmatter and CLAUDE_PLUGIN_ROOT path resolution that affected plugin developers. +3. **New tools requiring documentation**: + - REPL: JavaScript programming interface for composing tool calls + - PushNotification: Desktop/mobile notifications + - Snooze: Delay tool for loop scheduling (replaces Sleep) + - ScheduleWakeup: Loop iteration scheduling -- ! **Skill invocation names changed (CC 2.1.94)** — "Plugin skills declared via 'skills': ['./'] now use the skill's frontmatter `name` for invocation instead of directory basename". This affects how skills are invoked. - - Affects: skill-development skill (skill naming section) - - Details: Skills now use frontmatter `name` for invocation, not directory name. This is relevant for skill naming guidance. +4. **New hooks**: PreCompact hook added for plugins to intercept before context compaction. -#### May Update Resolution +5. **Managed Agents documentation overhaul** is extensive but may only affect the claude-api skill's references if plugin-dev references the Agent SDK. -- = **CLAUDE_CODE_PERFORCE_MODE** — kept as May Update: Environment variable for read-only file handling. Not directly plugin-related but could be mentioned in environment variables reference if one exists. +6. **Token delta summary** (from system-prompts): + - 2.1.100: -845 tokens (communication style prompts removed) + - 2.1.101: +4,676 tokens (loop/scheduling skills, autonomous loop) + - 2.1.104: +8 tokens (heading rename) + - 2.1.105: +4,895 tokens (verify skill alias, monitor updates, worktree updates) + - 2.1.107: +119 tokens (thinking frequency) + - 2.1.108: +885 tokens (REPL tool, allowed-tools syntax) + - 2.1.109: +0 tokens (no prompt changes) + - 2.1.110: +590 tokens (PushNotification, heredoc guidance) -- = **CLAUDE_CODE_USE_MANTLE=1** — kept as May Update: Amazon Bedrock support env var. Not directly plugin-related. +--- -- = **Default effort level changed from medium to high** — kept as May Update: Affects API-key and Team/Enterprise users. May be relevant if agent-development mentions effort levels (it does not currently). +## Raw Changelog Excerpts -- = **Worker fork agent metadata changes** — kept as May Update: Internal agent system changes. Minor documentation alignment opportunity. +### Version 2.1.110 +``` +- new `/tui` command for flicker-free rendering +- push notification capabilities +- improved plugin management +- MCP tool call hangs fixes +- session cleanup fixes +- permission rule enforcement fixes +``` -- = **Dream team memory handling** — kept as May Update: Built-in CC memory system, not plugin-related. +### Version 2.1.109 +``` +- rotating progress hint for extended-thinking indicator +``` -- = **Focus view toggle (Ctrl+O)** — kept as May Update: UI feature, not plugin-related. +### Version 2.1.108 +``` +- prompt caching TTL configuration (ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M) +- recap feature for returning to sessions +- improved error messaging for rate limits and server issues +``` -- = **refreshInterval status line setting** — kept as May Update: Configuration setting, not directly plugin-related. +### Version 2.1.107 +``` +- thinking hints shown sooner during long operations +``` -#### Summary +### Version 2.1.105 +``` +- `path` parameter added to EnterWorktree tool +- PreCompact hook support +- background monitor support for plugins +- stalled API stream handling improvements +- file write display improvements +``` -- Must Update: 6 items originally -> 2 confirmed, 1 rejected, 2 demoted, 2 added = **4 items total** - - Confirmed: Monitor tool, Agent absolute paths - - Promoted: Plugin hook fixes (compatibility note), Skill invocation names -- May Update: 7 items originally + 2 demoted = **9 items remaining** -- Confidence: **HIGH** — The manifest's main error was misattributing `keep-coding-instructions` to skills when it's an output style field. Plugin-dev already documents this correctly. +### Version 2.1.101 +``` +- `/team-onboarding` command +- OS CA certificate store trust by default +- improved brief and focus modes +- paste functionality fixes +- session resume fixes +- terminal escape code handling fixes +``` --- -## Notes - -1. **Degraded triangulation**: The claude-code-guide agent was not available in this CI environment, so cross-referencing against official docs was not performed. Changes are confirmed via changelog and system-prompts sources only. - -2. **High-priority items for plugin-dev** (verified): - - The Monitor tool is a new tool that agents can use (CC 2.1.98) - - Agent threads now unconditionally require absolute file paths (CC 2.1.97) - - Plugin skill hooks and CLAUDE_PLUGIN_ROOT fixes are critical bug fixes (CC 2.1.94) - - Skill invocation now uses frontmatter `name` instead of directory basename (CC 2.1.94) - - Note: `keep-coding-instructions` is for output styles, NOT skills (already documented correctly) +## Stage 2: Verification Results +### Verified: 2026-04-16 -3. **System-prompts changelog is more authoritative** for prompt/tool description changes, while the GitHub changelog captures user-facing features and settings. +#### Must Update Verification -4. **Token delta summary**: - - 2.1.94: +2,000 tokens (Dream agents, memory synthesis, onboarding guide, session search) - - 2.1.96: +0 tokens (hotfix only) - - 2.1.97: +23,865 tokens (Managed Agents documentation - massive addition) - - 2.1.98: +2,045 tokens (Communication style, dream team memory, exploratory questions, background monitor) +- ! **NEW REPL tool** (CC 2.1.108) -- RECLASSIFIED: "tool-reference skill" does not exist in plugin-dev. Should update `plugin-structure` (available tools list) or `command-development` (tool descriptions). Note: REPL is a new tool for JavaScript scripting, confirmed in system-prompts. +- ! **NEW PushNotification tool** (CC 2.1.110) -- RECLASSIFIED: Same issue - "tool-reference skill" does not exist. Update `plugin-structure` or create a new reference doc for tools. +- ! **EnterWorktree tool: new `path` parameter** (CC 2.1.105) -- RECLASSIFIED: No "tool-reference skill" exists. This is for worktree entry, which relates to `agent-development` (worktree isolation) more than a tool reference. Low priority - minor tool enhancement. +- X **Allowed-tools syntax change: colon-separated to space-separated** (CC 2.1.108) -- CONFIRMED and CRITICAL. Found 8+ files still using old `Bash(npm:*)` syntax that need updating to `Bash(npm *)`: + - `skills/command-development/SKILL.md` line 534 + - `skills/command-development/references/frontmatter-reference.md` line 104 + - `skills/command-development/references/advanced-workflows.md` lines 121, 148 + - `skills/command-development/examples/simple-commands.md` line 100 + - `skills/plugin-structure/references/github-actions.md` line 118 + - Note: `skills/agent-development/references/permission-modes-rules.md` already uses correct space-separated syntax (`Bash(npm *)`) +- X **Agent tool renamed from "Agent" to "R4"** (CC 2.1.105) -- DEMOTED to No Action. This is internal naming only, shown in disallowedTools context of Explore/Plan agents. Not relevant to plugin development documentation. +- X **/tui command** (CC 2.1.110) -- DEMOTED to No Action. Internal CLI feature, not relevant to plugin development. +- X **/team-onboarding command and skill** (CC 2.1.101) -- DEMOTED to No Action. Built-in CC command, not plugin development related. +- X **/insights command and skill** (CC 2.1.101) -- DEMOTED to No Action. Built-in CC command for usage reports. +- X **/loop dynamic mode and self-pacing** (CC 2.1.101) -- DEMOTED to No Action. Built-in CC autonomous loop features. +- X **PreCompact hook support** (CC 2.1.105) -- ALREADY DOCUMENTED. PreCompact hook exists in `hook-development/SKILL.md` lines 606+. However, CC 2.1.105 adds ability to block compaction via exit code 2 or `{"decision":"block"}` - this specific capability is NOT documented. +- X **Background monitor for plugins** (CC 2.1.105) -- PARTIALLY DOCUMENTED. `agent-development/SKILL.md` line 251 mentions "Monitor (CC 2.1.98)" tool. The CC 2.1.105 "silence is not success" guidance and plugin support is new. +- X **/dream nightly schedule skill** (CC 2.1.97, visible in 2.1.101) -- DEMOTED to No Action. Built-in CC memory feature. +- X **Managed Agents documentation overhaul** (CC 2.1.97, visible in 2.1.101+) -- DEMOTED to No Action. This is Anthropic API documentation, not Claude Code plugin development. +- X **Prompt caching TTL configuration** (CC 2.1.108) -- DEMOTED to No Action. Internal env vars for API usage, not plugin development. -5. **Note on version 2.1.93/2.1.95**: Neither the upstream changelog nor the system-prompts changelog show entries for versions 2.1.93 or 2.1.95. These versions may have been internal releases, skipped, or contained only infrastructure changes not reflected in public changelogs. +#### Missed Items (promoted from No Action) ---- +- ! **PreCompact hook blocking capability** (CC 2.1.105) -- PROMOTED from partial documentation + - Affects: hook-development + - Details: Hooks can now block compaction with exit code 2 or `{"decision":"block"}`. The PreCompact event already exists but blocking capability is new. -## Raw Changelog Excerpts +- ! **Sleep tool removed / Snooze tool replaces Sleep** (CC 2.1.92) -- Already in No Action but should be noted. Sleep tool removed is documented as CC 2.1.92, but that predates the version range (starts at 2.1.99). No action needed. -### Version 2.1.98 -``` -- Interactive Google Vertex AI setup wizard -- CLAUDE_CODE_PERFORCE_MODE environment variable for read-only file handling -- Monitor tool for streaming background events to foreground session -- Subprocess sandboxing with PID namespace isolation on Linux -- Security: Bash tool permission bypass (backslash-escaped flags, compound commands) -- Fixes: stalled streaming, 429 retry, MCP OAuth, xterm keyboard, macOS text replacements, - managed-settings persistence, permission rules, fullscreen UI, /resume picker -``` +#### May Update Resolution -### Version 2.1.97 -``` -- Focus view toggle (Ctrl+O) for NO_FLICKER mode -- refreshInterval status line setting -- Cedar policy file syntax highlighting -- Security: Permission bypass fixes, Bash tool env-var prefix hardening -- Fixes: MCP HTTP/SSE buffer, 429 retry, OAuth token refresh, /resume picker, NO_FLICKER UI -``` +- = **Agent tool "trust but verify" guidance** (CC 2.1.105) -- kept as May Update. Good practice guidance but not critical for plugin development. +- ↓ **Fork usage guidelines simplified** (CC 2.1.105) -- demoted to No Action. Internal CC guidance. +- ↓ **Communication style heading renamed** (CC 2.1.104) -- demoted to No Action. Internal naming. +- = **Verify skill restructured** (CC 2.1.97, updates through 2.1.105) -- kept as May Update. Could inform testing/verification patterns. +- ↓ **Sleep duration guidance relaxed** (CC 2.1.108) -- demoted to No Action. Minor internal change. +- = **Heredoc piping guidance for REPL/Bash** (CC 2.1.110) -- kept as May Update. Relevant to script execution patterns. +- ↓ **Session recap feature** (CC 2.1.108) -- demoted to No Action. User feature, not plugin dev. +- ↓ **Sandbox Network Callback threat definition** (CC 2.1.110) -- demoted to No Action. Internal security monitoring. +- ↓ **Model catalog formatting** (CC 2.1.108) -- demoted to No Action. Cosmetic change. -### Version 2.1.96 -``` -- Hotfix: Bedrock requests failing with 403 Authorization header is missing -``` +#### Summary -### Version 2.1.94 -``` -- Amazon Bedrock support via Mantle (CLAUDE_CODE_USE_MANTLE=1) -- Default effort level changed from medium to high -- Compact Slack headers with clickable channel links -- keep-coding-instructions frontmatter field support -- Fixes: agents stuck after rate-limit, Console login on macOS, plugin hook execution, - marketplace updates with git submodules, scrollback duplication, multiline prompt indentation -``` +- Must Update: 3 items remaining (1 CRITICAL - allowed-tools syntax, 2 reclassified for correct skill targets) + - 3 confirmed (allowed-tools syntax, REPL tool, PushNotification tool - but skill targets corrected) + - 11 rejected/demoted (built-in commands, internal features, API docs) + - 1 added (PreCompact blocking capability) +- May Update: 3 items remaining +- Confidence: MEDIUM-HIGH + - Stage 1 correctly identified the allowed-tools syntax change as critical + - Stage 1 incorrectly referenced "tool-reference skill" which does not exist + - Several items were built-in CC features, not plugin development items + - PreCompact blocking capability was partially missed + +#### Corrected Must Update Items for Stage 3 + +1. **CRITICAL: Allowed-tools syntax change** (CC 2.1.108) + - Affects: skill-development, command-development, all files using permission examples + - Action: Update all `Bash(npm:*)` to `Bash(npm *)`, `Bash(git:*)` to `Bash(git *)`, etc. + - Files to update: + - `skills/command-development/SKILL.md` + - `skills/command-development/references/frontmatter-reference.md` + - `skills/command-development/references/advanced-workflows.md` + - `skills/command-development/examples/simple-commands.md` + - `skills/plugin-structure/references/github-actions.md` + +2. **PreCompact hook blocking capability** (CC 2.1.105) + - Affects: hook-development + - Action: Add note that PreCompact hooks can return `{"decision":"block"}` or exit code 2 to block compaction + +3. **Background monitor plugin support - "silence is not success"** (CC 2.1.105) + - Affects: hook-development, agent-development + - Action: Add guidance that monitors should capture failure states, not just success. Add top-level `monitors` manifest key documentation if needed. + +4. **REPL tool** (CC 2.1.108) - Optional/Low Priority + - Affects: plugin-structure (tool list) or new reference doc + - Action: Mention REPL as new tool for JavaScript scripting in any tool listings + +5. **PushNotification tool** (CC 2.1.110) - Optional/Low Priority + - Affects: plugin-structure (tool list) or new reference doc + - Action: Mention PushNotification tool for desktop/mobile notifications diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 005f24e..6d29c0b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", - "version": "0.10.2" + "version": "0.10.3" }, "plugins": [ { "name": "plugin-dev", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", - "version": "0.10.2", + "version": "0.10.3", "author": { "name": "Kyle Snow Schwartz", "url": "https://github.com/kylesnowschwartz" diff --git a/CHANGELOG.md b/CHANGELOG.md index abc2df5..b3d69d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.3] - 2026-04-16 + +### Changed + +- **BREAKING: Allowed-tools syntax change** - Updated all documentation to use space-separated format (`Bash(git *)`) instead of colon-separated format (`Bash(git:*)`) per Claude Code 2.1.108 +- **command-development**: Updated allowed-tools examples across SKILL.md, references, and examples +- **plugin-structure**: Updated allowed-tools examples in github-actions.md and headless-ci-mode.md +- **/create-plugin, /create-marketplace**: Updated allowed-tools frontmatter +- **docs**: Updated allowed-tools examples in workflow-security.md and CONTRIBUTING.md + +### Note + +- CI workflow files (`.github/workflows/claude.yml`, `.github/workflows/component-validation.yml`) still use old colon-separated syntax. Update these manually if the repository has `workflows` write permission configured. + +### Added + +- **hook-development**: Documented PreCompact hook blocking capability with exit code 2 or `{"decision":"block"}` (CC 2.1.105) +- **plugin-structure**: Documented `monitors` manifest key for background monitoring scripts with "silence is not success" guidance (CC 2.1.105) + ## [0.10.2] - 2026-04-10 ### Added @@ -362,7 +381,8 @@ 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/kylesnowschwartz/plugin-dev/compare/v0.10.2...HEAD +[Unreleased]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.3...HEAD +[0.10.3]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.2...v0.10.3 [0.10.2]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.1...v0.10.2 [0.10.1]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.10.0...v0.10.1 [0.10.0]: https://github.com/kylesnowschwartz/plugin-dev/compare/v0.9.0...v0.10.0 diff --git a/CLAUDE.md b/CLAUDE.md index 439ad18..0dc3a32 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Guidance for Claude Code working in this repository. Plugin marketplace containing the **plugin-dev** plugin - a toolkit for developing Claude Code plugins. Provides 11 skills, 7 agents, 3 slash commands. -**Version**: v0.10.2 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.10.3 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 730291c..68b9e0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -221,7 +221,7 @@ When creating or modifying commands: --- description: Brief description argument-hint: [optional-argument] - allowed-tools: AskUserQuestion, Bash(gh:*), Read + allowed-tools: AskUserQuestion, Bash(gh *), Read --- ``` diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md index 93583c3..e923365 100644 --- a/docs/claude-code-compatibility.md +++ b/docs/claude-code-compatibility.md @@ -1,12 +1,13 @@ # Claude Code Compatibility -Last audited: Claude Code 2.1.98 (2026-04-10) -Plugin-dev version: 0.10.2 +Last audited: Claude Code 2.1.110 (2026-04-16) +Plugin-dev version: 0.10.3 ## Audit Log | plugin-dev | CC version range | Date | Notes | |---|---|---|---| +| v0.10.3 | 2.1.99-2.1.110 | 2026-04-16 | Allowed-tools syntax change (colon to space), PreCompact hook blocking capability, monitors manifest key | | v0.10.2 | 2.1.94-2.1.98 | 2026-04-10 | Monitor tool for background events, agent absolute path requirement, skill invocation name change, plugin skill hook/CLAUDE_PLUGIN_ROOT fixes | | v0.10.0 | 2.1.89-2.1.92 | 2026-04-04 | PreToolUse `defer` decision, MCP maxResultSizeChars (500K), disableSkillShellExecution setting, plugin bin/ directory | | v0.9.0 | 2.1.87-2.1.88 | 2026-03-31 | PermissionDenied hook (25th event), file_path absolute paths, `if` compound command fix, partial compaction, Config tool | diff --git a/docs/workflow-security.md b/docs/workflow-security.md index 86485c5..46e4a01 100644 --- a/docs/workflow-security.md +++ b/docs/workflow-security.md @@ -7,14 +7,14 @@ Security considerations for the plugin creation workflows. The workflow commands (`/plugin-dev:create-plugin` and `/plugin-dev:create-marketplace`) require broad file system access to perform their scaffolding functions: ```yaml -allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:*), Bash(git init:*), ... +allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir *), Bash(git init *), ... ``` **Why this access is needed:** -- Creating plugin directory structures requires `Write` and `Bash(mkdir:*)` +- Creating plugin directory structures requires `Write` and `Bash(mkdir *)` - Generating manifest files and component templates requires `Write` and `Edit` -- Initializing git repositories requires `Bash(git init:*)` +- Initializing git repositories requires `Bash(git init *)` - Exploring existing code for patterns requires `Read`, `Grep`, `Glob` ## Security Considerations diff --git a/plugins/plugin-dev/.claude-plugin/plugin.json b/plugins/plugin-dev/.claude-plugin/plugin.json index ce4a2d8..fd70207 100644 --- a/plugins/plugin-dev/.claude-plugin/plugin.json +++ b/plugins/plugin-dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-dev", - "version": "0.10.2", + "version": "0.10.3", "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 11 expert skills covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, upstream sync, and best practices, plus a guide skill for navigation. AI-assisted plugin creation and validation.", "author": { "name": "Kyle Snow Schwartz", diff --git a/plugins/plugin-dev/commands/create-marketplace.md b/plugins/plugin-dev/commands/create-marketplace.md index 7648985..8d153e3 100644 --- a/plugins/plugin-dev/commands/create-marketplace.md +++ b/plugins/plugin-dev/commands/create-marketplace.md @@ -1,7 +1,7 @@ --- description: Create plugin marketplaces with guided workflow argument-hint: [marketplace-description] -allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:*), Bash(git init:*), TaskCreate, TaskGet, TaskUpdate, TaskList, AskUserQuestion, Skill, Task +allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir *), Bash(git init *), TaskCreate, TaskGet, TaskUpdate, TaskList, AskUserQuestion, Skill, Task model: sonnet --- diff --git a/plugins/plugin-dev/commands/create-plugin.md b/plugins/plugin-dev/commands/create-plugin.md index a4fb35f..6d2ccc0 100644 --- a/plugins/plugin-dev/commands/create-plugin.md +++ b/plugins/plugin-dev/commands/create-plugin.md @@ -1,7 +1,7 @@ --- description: Create plugins with guided 8-phase workflow argument-hint: [plugin-description] -allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:*), Bash(git init:*), TaskCreate, TaskGet, TaskUpdate, TaskList, AskUserQuestion, Skill, Task +allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir *), Bash(git init *), TaskCreate, TaskGet, TaskUpdate, TaskList, AskUserQuestion, Skill, Task model: sonnet --- diff --git a/plugins/plugin-dev/skills/command-development/SKILL.md b/plugins/plugin-dev/skills/command-development/SKILL.md index 1c782ab..1b5a681 100644 --- a/plugins/plugin-dev/skills/command-development/SKILL.md +++ b/plugins/plugin-dev/skills/command-development/SKILL.md @@ -114,7 +114,7 @@ Add configuration using YAML frontmatter: ```markdown --- description: Review code for security issues -allowed-tools: Read, Grep, Bash(git:*) +allowed-tools: Read, Grep, Bash(git *) model: sonnet --- @@ -145,14 +145,14 @@ description: Review pull request for code quality ```yaml --- -allowed-tools: Read, Write, Edit, Bash(git:*) +allowed-tools: Read, Write, Edit, Bash(git *) --- ``` **Patterns:** - `Read, Write, Edit` - Specific tools -- `Bash(git:*)` - Bash with git commands only +- `Bash(git *)` - Bash with git commands only - `*` - All tools (rarely needed) **Use when:** Command requires specific tool access @@ -498,7 +498,7 @@ Please provide a PR number. Usage: /review-pr [number] ### Bash Commands -1. **Limit scope:** Use `Bash(git:*)` not `Bash(*)` +1. **Limit scope:** Use `Bash(git *)` not `Bash(*)` 2. **Safe commands:** Avoid destructive operations 3. **Handle errors:** Consider command failures 4. **Keep fast:** Long-running commands slow invocation @@ -517,7 +517,7 @@ Please provide a PR number. Usage: /review-pr [number] ```markdown --- description: Review code changes -allowed-tools: Read, Bash(git:*) +allowed-tools: Read, Bash(git *) --- Files changed: `git diff --name-only` @@ -531,7 +531,7 @@ Review each file for code quality, bugs, test coverage, documentation needs. --- description: Run tests for specific file argument-hint: [test-file] -allowed-tools: Bash(npm:*) +allowed-tools: Bash(npm *) --- Run tests: `npm test $1` @@ -544,7 +544,7 @@ Analyze results and suggest fixes for failures. --- description: Complete PR workflow argument-hint: [pr-number] -allowed-tools: Bash(gh:*), Read +allowed-tools: Bash(gh *), Read --- PR #$1 Workflow: @@ -602,7 +602,7 @@ Plugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable ```markdown --- description: Analyze using plugin script -allowed-tools: Bash(node:*) +allowed-tools: Bash(node *) --- Run analysis: `node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1` diff --git a/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md b/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md index dd24a9b..205b012 100644 --- a/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md +++ b/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md @@ -27,7 +27,7 @@ Practical examples of commands designed for Claude Code plugins, demonstrating p --- description: Analyze code quality using plugin tools argument-hint: [file-path] -allowed-tools: Bash(node:*), Read +allowed-tools: Bash(node *), Read --- Analyze @$1 using plugin's quality checker: @@ -312,7 +312,7 @@ Generate production-ready API documentation. --- description: Comprehensive review using all plugin components argument-hint: [file-path] -allowed-tools: Bash(node:*), Read +allowed-tools: Bash(node *), Read --- Target file: @$1 diff --git a/plugins/plugin-dev/skills/command-development/examples/simple-commands.md b/plugins/plugin-dev/skills/command-development/examples/simple-commands.md index 24cc145..c1fbc90 100644 --- a/plugins/plugin-dev/skills/command-development/examples/simple-commands.md +++ b/plugins/plugin-dev/skills/command-development/examples/simple-commands.md @@ -11,7 +11,7 @@ Basic slash command patterns for common use cases. ```markdown --- description: Review code for quality and issues -allowed-tools: Read, Bash(git:*) +allowed-tools: Read, Bash(git *) --- Review the code in this repository for: @@ -97,7 +97,7 @@ Prioritize issues by severity. --- description: Run tests for specific file argument-hint: [test-file] -allowed-tools: Bash(npm:*), Bash(jest:*) +allowed-tools: Bash(npm *), Bash(jest *) --- Run tests for $1: @@ -179,7 +179,7 @@ Format as Markdown suitable for project documentation. ```markdown --- description: Summarize Git repository status -allowed-tools: Bash(git:*) +allowed-tools: Bash(git *) --- Repository Status Summary: @@ -215,7 +215,7 @@ Provide: --- description: Deploy to specified environment argument-hint: [environment] [version] -allowed-tools: Bash(kubectl:*), Read +allowed-tools: Bash(kubectl *), Read --- Deploy to $1 environment using version $2 @@ -448,7 +448,7 @@ Analyze but don't modify... ```markdown --- -allowed-tools: Bash(git:*) +allowed-tools: Bash(git *) --- `git status` @@ -505,7 +505,7 @@ Compare @$1 with @$2... ```markdown --- -allowed-tools: Bash(git:*), Read +allowed-tools: Bash(git *), Read --- Context: `git status` diff --git a/plugins/plugin-dev/skills/command-development/references/advanced-workflows.md b/plugins/plugin-dev/skills/command-development/references/advanced-workflows.md index 423776c..c592f1a 100644 --- a/plugins/plugin-dev/skills/command-development/references/advanced-workflows.md +++ b/plugins/plugin-dev/skills/command-development/references/advanced-workflows.md @@ -16,7 +16,7 @@ Commands that guide users through multi-step processes: --- description: Complete PR review workflow argument-hint: [pr-number] -allowed-tools: Bash(gh:*), Read, Grep +allowed-tools: Bash(gh *), Read, Grep --- # PR Review Workflow for #$1 @@ -76,7 +76,7 @@ Commands that maintain state between invocations: ```markdown --- description: Initialize deployment workflow -allowed-tools: Write, Bash(git:*) +allowed-tools: Write, Bash(git *) --- # Initialize Deployment @@ -118,7 +118,7 @@ State saved. Run `/deploy-test` to continue. ```markdown --- description: Run deployment tests -allowed-tools: Read, Bash(npm:*) +allowed-tools: Read, Bash(npm *) --- Reading deployment state from `.claude/deployment-state.local.md`... @@ -145,7 +145,7 @@ Commands that adapt based on conditions: --- description: Smart deployment workflow argument-hint: [environment] -allowed-tools: Bash(git:*), Bash(npm:*), Read +allowed-tools: Bash(git *), Bash(npm *), Read --- # Deploy to $1 @@ -418,7 +418,7 @@ Feature marked complete. ```markdown --- description: Generate release notes -allowed-tools: Read, Bash(git:*) +allowed-tools: Read, Bash(git *) --- Checking for completed features... @@ -679,7 +679,7 @@ If any step fails, resume with: --- description: Initialize deployment argument-hint: [environment] -allowed-tools: Write, Bash(git:*) +allowed-tools: Write, Bash(git *) --- # Initialize Deployment to $1 diff --git a/plugins/plugin-dev/skills/command-development/references/documentation-patterns.md b/plugins/plugin-dev/skills/command-development/references/documentation-patterns.md index c975c7d..a5d1fbe 100644 --- a/plugins/plugin-dev/skills/command-development/references/documentation-patterns.md +++ b/plugins/plugin-dev/skills/command-development/references/documentation-patterns.md @@ -14,7 +14,7 @@ Well-documented commands are easier to use, maintain, and distribute. Documentat --- description: Clear, actionable description under 60 chars argument-hint: [arg1] [arg2] [optional-arg] -allowed-tools: Read, Bash(git:*) +allowed-tools: Read, Bash(git *) model: sonnet --- diff --git a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md index ceb2189..3314609 100644 --- a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md +++ b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md @@ -86,7 +86,7 @@ allowed-tools: Read, Write, Edit ``` ```yaml -allowed-tools: Read, Write, Bash(git:*) +allowed-tools: Read, Write, Bash(git *) ``` **Tool Patterns:** @@ -100,9 +100,9 @@ allowed-tools: Read, Grep, Edit **Bash with command filter:** ```yaml -allowed-tools: Bash(git:*) # Only git commands -allowed-tools: Bash(npm:*) # Only npm commands -allowed-tools: Bash(docker:*) # Only docker commands +allowed-tools: Bash(git *) # Only git commands +allowed-tools: Bash(npm *) # Only npm commands +allowed-tools: Bash(docker *) # Only docker commands ``` **All tools (not recommended):** @@ -122,18 +122,18 @@ allowed-tools: "*" 2. **Clarity:** Document required tools ```yaml - allowed-tools: Bash(git:*), Read + allowed-tools: Bash(git *), Read ``` 3. **Bash execution:** Enable bash command output ```yaml - allowed-tools: Bash(git status:*), Bash(git diff:*) + allowed-tools: Bash(git status *), Bash(git diff *) ``` **Best practices:** - Be as restrictive as possible -- Use command filters for Bash (e.g., `git:*` not `*`) +- Use command filters for Bash (e.g., `git *` not `*`) - Only specify when different from conversation permissions - Document why specific tools are needed @@ -388,7 +388,7 @@ Description and tools: ```markdown --- description: Review Git changes -allowed-tools: Bash(git:*), Read +allowed-tools: Bash(git *), Read --- Current changes: `git diff --name-only` @@ -408,7 +408,7 @@ All common fields: --- description: Deploy application to environment argument-hint: [app-name] [environment] [version] -allowed-tools: Bash(kubectl:*), Bash(helm:*), Read +allowed-tools: Bash(kubectl *), Bash(helm *), Read model: sonnet --- @@ -432,7 +432,7 @@ Restricted invocation: description: Approve production deployment argument-hint: [deployment-id] disable-model-invocation: true -allowed-tools: Bash(gh:*) +allowed-tools: Bash(gh *) ---