diff --git a/.agent-history/upstream-changes.md b/.agent-history/upstream-changes.md new file mode 100644 index 0000000..9240cf7 --- /dev/null +++ b/.agent-history/upstream-changes.md @@ -0,0 +1,299 @@ +# Upstream Change Manifest +## 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 (Stage 2 Verified) + +- [ ] **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 + +--- + +### May Update (Stage 2 Verified) + +- [ ] **Agent tool "trust but verify" guidance** (CC 2.1.105) + - Source: system-prompts + - Confidence: medium + - 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. + +- [ ] **Verify skill restructured** (CC 2.1.97, updates through 2.1.105) + - Source: system-prompts + - Confidence: medium + - 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. + +- [ ] **Heredoc piping guidance for REPL/Bash** (CC 2.1.110) + - Source: system-prompts + - Confidence: medium + - 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 (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 + +--- + +## Summary (Stage 2 Corrected) + +**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 + +**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 + +**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 + +## Notes + +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. + +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. + +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 + +4. **New hooks**: PreCompact hook added for plugins to intercept before context compaction. + +5. **Managed Agents documentation overhaul** is extensive but may only affect the claude-api skill's references if plugin-dev references the Agent SDK. + +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) + +--- + +## Raw Changelog Excerpts + +### 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 +``` + +### Version 2.1.109 +``` +- rotating progress hint for extended-thinking indicator +``` + +### 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 +``` + +### Version 2.1.107 +``` +- thinking hints shown sooner during long operations +``` + +### 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 +``` + +### 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 +``` + +--- + +## Stage 2: Verification Results +### Verified: 2026-04-16 + +#### Must Update Verification + +- ! **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. + +#### 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. + +- ! **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. + +#### May Update Resolution + +- = **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. + +#### Summary + +- 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 7571296..c857d0b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,23 +1,23 @@ { "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.", - "version": "0.3.2" + "description": "Unofficial plugin-dev plugin marketplace. Originally created by Daisy Hollman at Anthropic, forked and maintained by Kyle Snow Schwartz.", + "version": "0.11.0" }, "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.", - "version": "0.3.2", + "description": "Comprehensive toolkit for developing Claude Code plugins. Single consolidated skill covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, plugin settings, and best practices with progressive disclosure. Includes upstream sync, AI-assisted plugin creation, and validation.", + "version": "0.11.0", "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/.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/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/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/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 74897a9..47c868a 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: @@ -21,7 +20,6 @@ concurrency: permissions: contents: read - issues: write # Required for creating issue on failure jobs: linkChecker: @@ -63,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 new file mode 100644 index 0000000..93ec5ec --- /dev/null +++ b/.github/workflows/upstream-sync.yml @@ -0,0 +1,81 @@ +# 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: 60 + 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: 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 + show_full_output: 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 150 + --allowedTools "Read,Write,Edit,Bash,Grep,Glob,WebFetch,Agent" 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/.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/CHANGELOG.md b/CHANGELOG.md index 8d2a7d1..ee206ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,168 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.11.0] - 2026-04-16 + +### Changed + +- **BREAKING: Consolidated 9 teaching skills + plugin-dev-guide into single `plugin-dev` skill** with routing index and progressive disclosure. Eval showed 57.9% vs 47.4% trigger rate (strict superset, zero false positives). The consolidated skill uses a topic index table that routes to `references//overview.md` files preserving the same content. +- **Removed `plugin-dev-guide` agent** — replaced by the routing index in the consolidated skill +- **Updated agent frontmatter**: `plugin-validator`, `agent-creator`, `skill-reviewer` now reference `skills: plugin-dev` instead of individual skill names +- `update-from-upstream` remains a separate skill (workflow, not reference) + +### Migration + +- If you referenced individual skills by name (e.g., `hook-development`, `skill-development`), use `plugin-dev` instead. The content is identical, reorganized under `references//`. + +## [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 + +- **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 + +- **plugin-dev-guide agent**: Fixed YAML frontmatter parse error — added missing block scalar indicator (`|`) on description field + +## [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 + +- **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 + +- **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 + +- **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 + +- **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 + +- **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 + +- **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 + +- **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,10 +394,22 @@ 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 -[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 +[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 +[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 +[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/CLAUDE.md b/CLAUDE.md index 35b4477..449eb0c 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 2 skills (1 consolidated + upstream sync), 6 agents, 3 slash commands. -**Version**: v0.3.2 | [CHANGELOG.md](CHANGELOG.md) +**Version**: v0.11.0 | [CHANGELOG.md](CHANGELOG.md) ## MCP Tool Requirements (CRITICAL) @@ -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 @@ -90,3 +87,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/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 b2f09f1..68b9e0f 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 @@ -32,9 +32,9 @@ Before contributing, ensure you have: gh auth login ``` - **Git**: For version control -- **Node.js**: For markdownlint (optional but recommended) +- **prettier**: For formatting (should be available globally) ```bash - npm install -g markdownlint-cli + prettier --version ``` ### Understanding the Project @@ -48,15 +48,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 @@ -71,7 +71,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 @@ -136,11 +136,9 @@ 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 '**/*.md' --ignore node_modules - -# Auto-fix issues -markdownlint '**/*.md' --ignore node_modules --fix +# Format with prettier +prettier --check '**/*.md' +prettier --write '**/*.md' # fix formatting issues ``` ### YAML Linting @@ -152,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 `+`) @@ -223,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 --- ``` @@ -381,11 +379,8 @@ gh repo delete test-plugin-repo --yes ### 2. Lint Your Code ```bash -# Lint all markdown -markdownlint '**/*.md' --ignore node_modules --fix - -# Check specific files -markdownlint plugins/plugin-dev/commands/your-command.md +# Format with prettier +prettier --write '**/*.md' ``` ### 3. Commit Your Changes @@ -409,7 +404,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 @@ -421,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) @@ -432,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. @@ -479,14 +471,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 @@ -510,9 +502,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 d80e545..946826f 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,8 @@ # 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) +[![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. @@ -33,7 +32,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 @@ -45,7 +44,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 +73,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: @@ -130,7 +129,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,14 +391,14 @@ 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: `shellcheck plugins/plugin-dev/skills/*/scripts/*.sh` 5. Create a PR with your changes ## 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 +407,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 f47a6e9..168f427 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: | @@ -18,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 @@ -26,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: @@ -72,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 @@ -146,9 +146,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/ci-cd.md b/docs/ci-cd.md index 5cce2ac..c1e35e5 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -6,22 +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 | ## 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 +- `claude.yml` - On-demand `@claude` in issues/PRs - `sync-labels.yml` - Synchronizes repository labels -- `greet.yml` - Greets new contributors ## Labels @@ -34,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/`: diff --git a/docs/claude-code-compatibility.md b/docs/claude-code-compatibility.md new file mode 100644 index 0000000..e923365 --- /dev/null +++ b/docs/claude-code-compatibility.md @@ -0,0 +1,15 @@ +# Claude Code Compatibility + +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 | +| 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/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..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,18 +38,15 @@ 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 @@ -66,67 +55,17 @@ 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. 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/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..39cc35f --- /dev/null +++ b/docs/superpowers/specs/2026-03-29-update-from-upstream-design.md @@ -0,0 +1,257 @@ +# 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 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 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 +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 fetches its own copy of the CC changelog (fresh WebFetch, not reading from Stage 1's output) to ensure true independence: + +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? + +**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. + +**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) + +| 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 | +|---|---| +| `.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 | 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 + +**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). + +## 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, 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/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/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/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 01cd82a..ed85310 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.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.", + "version": "0.11.0", + "description": "Comprehensive toolkit for developing Claude Code plugins. Single consolidated skill covering hooks, MCP integration, LSP servers, commands, agents, marketplaces, plugin settings, and best practices with progressive disclosure. Includes upstream sync, 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", diff --git a/plugins/plugin-dev/agents/agent-creator.md b/plugins/plugin-dev/agents/agent-creator.md index df43b88..f000822 100644 --- a/plugins/plugin-dev/agents/agent-creator.md +++ b/plugins/plugin-dev/agents/agent-creator.md @@ -1,48 +1,47 @@ --- 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 -skills: agent-development +skills: plugin-dev --- You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability. diff --git a/plugins/plugin-dev/agents/changelog-differ.md b/plugins/plugin-dev/agents/changelog-differ.md new file mode 100644 index 0000000..b494a5e --- /dev/null +++ b/plugins/plugin-dev/agents/changelog-differ.md @@ -0,0 +1,116 @@ +--- +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, 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. + +## 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. Check these paths in order: +``` +./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 + +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. + +Only if the dispatch fails with an error should you note degraded triangulation in the manifest. + +### 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/plugin-validator.md b/plugins/plugin-dev/agents/plugin-validator.md index 9b50a11..ccd936c 100644 --- a/plugins/plugin-dev/agents/plugin-validator.md +++ b/plugins/plugin-dev/agents/plugin-validator.md @@ -1,47 +1,48 @@ --- 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 tools: Read, Grep, Glob, Bash -skills: plugin-structure, hook-development, command-development, skill-development, agent-development, lsp-integration, mcp-integration +skills: plugin-dev --- You are an expert plugin and marketplace validator specializing in comprehensive validation of Claude Code plugin structure, configuration, components, and plugin marketplaces. diff --git a/plugins/plugin-dev/agents/skill-reviewer.md b/plugins/plugin-dev/agents/skill-reviewer.md index fc81775..67f4548 100644 --- a/plugins/plugin-dev/agents/skill-reviewer.md +++ b/plugins/plugin-dev/agents/skill-reviewer.md @@ -1,47 +1,48 @@ --- 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 tools: Read, Grep, Glob -skills: skill-development +skills: plugin-dev --- You are an expert skill architect specializing in reviewing and improving Claude Code skills for maximum effectiveness and reliability. 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..dbca081 --- /dev/null +++ b/plugins/plugin-dev/agents/update-manifest-verifier.md @@ -0,0 +1,108 @@ +--- +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 (first 200 lines only — versions are newest-first, full file is 30k+ tokens): +``` +./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 + +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/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/hook-development/SKILL.md b/plugins/plugin-dev/skills/hook-development/SKILL.md deleted file mode 100644 index 1626ddb..0000000 --- a/plugins/plugin-dev/skills/hook-development/SKILL.md +++ /dev/null @@ -1,809 +0,0 @@ ---- -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. ---- - -# 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. - -**Key capabilities:** - -- 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 - -## Hook Types - -### Prompt-Based Hooks (Recommended) - -Use LLM-driven decision making for context-aware validation: - -```json -{ - "type": "prompt", - "prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT", - "timeout": 30 -} -``` - -**Supported events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse - -**Benefits:** - -- Context-aware decisions based on natural language reasoning -- Flexible evaluation logic without bash scripting -- Better edge case handling -- Easier to maintain and extend - -### Command Hooks - -Execute bash commands for deterministic checks: - -```json -{ - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh", - "timeout": 60 -} -``` - -**Use for:** - -- Fast deterministic validations -- File system operations -- External tool integrations -- Performance-critical checks - -## Hook Configuration Formats - -### Plugin hooks.json Format - -**For plugin hooks** in `hooks/hooks.json`, use wrapper format: - -```json -{ - "description": "Brief explanation of hooks (optional)", - "hooks": { - "PreToolUse": [...], - "Stop": [...], - "SessionStart": [...] - } -} -``` - -**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: - -```json -{ - "PreToolUse": [...], - "Stop": [...], - "SessionStart": [...] -} -``` - -**Key points:** - -- No wrapper - events directly at top level -- No description field -- This is the **settings format** - -**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 - -Execute before any tool runs. Use to approve, deny, or modify tool calls. - -**Example (prompt-based):** - -```json -{ - "PreToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [ - { - "type": "prompt", - "prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'." - } - ] - } - ] -} -``` - -**Output for PreToolUse:** - -```json -{ - "hookSpecificOutput": { - "permissionDecision": "allow|deny|ask", - "updatedInput": { "field": "modified_value" } - }, - "systemMessage": "Explanation for Claude" -} -``` - -### PermissionRequest - -Execute when user is shown a permission dialog. Use to automatically allow or deny permissions. - -**Example:** - -```json -{ - "PermissionRequest": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-permission.sh" - } - ] - } - ] -} -``` - -**Output for PermissionRequest:** - -```json -{ - "hookSpecificOutput": { - "decision": { - "behavior": "allow|deny", - "updatedInput": { "command": "modified command" }, - "message": "Reason for denial", - "interrupt": false - } - } -} -``` - -- `behavior`: "allow" to approve, "deny" to reject -- `updatedInput`: Optional modified tool parameters (only with "allow") -- `message`: Explanation shown to user (only with "deny") -- `interrupt`: If true with "deny", stops the current operation - -**Use cases:** - -- Auto-approve safe commands matching patterns -- Block dangerous operations with explanations -- Modify tool inputs before execution - -### PostToolUse - -Execute after tool completes. Use to react to results, provide feedback, or log. - -**Example:** - -```json -{ - "PostToolUse": [ - { - "matcher": "Edit", - "hooks": [ - { - "type": "prompt", - "prompt": "Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback." - } - ] - } - ] -} -``` - -**Output behavior:** - -- Exit 0: stdout shown in transcript -- Exit 2: stderr fed back to Claude -- systemMessage included in context - -### PostToolUseFailure - -Execute when a tool fails after PostToolUse hooks have run. Use to handle errors or provide fallback actions. - -**Example:** - -```json -{ - "PostToolUseFailure": [ - { - "matcher": "Edit", - "hooks": [ - { - "type": "prompt", - "prompt": "Error occurred during edit. Provide fallback action or ask for user input." - } - ] - } - ] -} -``` - -**Output behavior:** - -- Exit 2: stderr fed back to Claude -- systemMessage included in context - -### Stop - -Execute when main agent considers stopping. Use to validate completeness. - -**Example:** - -```json -{ - "Stop": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue." - } - ] - } - ] -} -``` - -**Decision output:** - -```json -{ - "decision": "approve|block", - "reason": "Explanation", - "systemMessage": "Additional context" -} -``` - -### SubagentStop - -Execute when subagent considers stopping. Use to ensure subagent completed its task. - -Similar to Stop hook, but for subagents. - -### SubagentStart - -Execute when a subagent is started. Use to initialize subagent state or perform setup. - -**Example:** - -```json -{ - "SubagentStart": [ - { - "matcher": "mcp__subagent_name", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/subagent-init.sh" - } - ] - } - ] -} -``` - -### Setup - -Execute once at session start to perform global setup or initialize resources. - -**Example:** - -```json -{ - "Setup": [ - { - "matcher": "*", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-setup.sh" - } - ] - } - ] -} -``` - -### UserPromptSubmit - -Execute when user submits a prompt. Use to add context, validate, or block prompts. - -**Example:** - -```json -{ - "UserPromptSubmit": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings." - } - ] - } - ] -} -``` - -### SessionStart - -Execute when Claude Code session begins. Use to load context and set environment. - -**Example:** - -```json -{ - "SessionStart": [ - { - "matcher": "*", - "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 complete example. - -### SessionEnd - -Execute when session ends. Use for cleanup, logging, and state preservation. - -### PreCompact - -Execute before context compaction. Use to add critical information to preserve. - -### Notification - -Execute when Claude sends notifications. Use to react to user notifications. - -## Hook Output Format - -### Standard Output (All Hooks) - -```json -{ - "continue": true, - "suppressOutput": false, - "systemMessage": "Message for Claude" -} -``` - -- `continue`: If false, halt processing (default true) -- `suppressOutput`: Hide output from transcript (default false) -- `systemMessage`: Message shown to Claude - -### Exit Codes - -- `0` - Success (stdout shown in transcript) -- `2` - Blocking error (stderr fed back to Claude) -- Other - Non-blocking error - -## Hook Input Format - -All hooks receive JSON via stdin with common fields: - -```json -{ - "session_id": "abc123", - "transcript_path": "/path/to/transcript.txt", - "cwd": "/current/working/dir", - "permission_mode": "ask|allow", - "hook_event_name": "PreToolUse" -} -``` - -**Event-specific fields:** - -- **PreToolUse/PermissionRequest/PostToolUse:** `tool_name`, `tool_input`, `tool_result` -- **UserPromptSubmit:** `user_prompt` -- **Stop/SubagentStop:** `reason` - -Access fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc. - -## 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 - -**Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:** - -```json -{ - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh" -} -``` - -## 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 - } - ] - } - ] - } -} -``` - -**Note:** Plugin hooks use the `{"hooks": {...}}` wrapper format, not the direct settings format. Plugin hooks merge with user's hooks and run in parallel. - -## Matchers - -### Tool Name Matching - -**Exact match:** - -```json -"matcher": "Write" -``` - -**Multiple tools:** - -```json -"matcher": "Read|Write|Edit" -``` - -**Wildcard (all tools):** - -```json -"matcher": "*" -``` - -**Regex patterns:** - -```json -"matcher": "mcp__.*__delete.*" // All MCP delete tools -``` - -**Note:** Matchers are case-sensitive. - -### Common Patterns - -```json -// All MCP tools -"matcher": "mcp__.*" - -// Specific plugin's MCP tools -"matcher": "mcp__plugin_asana_.*" - -// All file operations -"matcher": "Read|Write|Edit" - -// Bash commands only -"matcher": "Bash" -``` - -## Security Best Practices - -### Input Validation - -Always validate inputs in command hooks: - -```bash -#!/bin/bash -set -euo pipefail - -input=$(cat) -tool_name=$(echo "$input" | jq -r '.tool_name') - -# Validate tool name format -if [[ ! "$tool_name" =~ ^[a-zA-Z0-9_]+$ ]]; then - echo '{"decision": "deny", "reason": "Invalid tool name"}' >&2 - exit 2 -fi -``` - -### Path Safety - -Check for path traversal and sensitive files: - -```bash -file_path=$(echo "$input" | jq -r '.tool_input.file_path') - -# Deny path traversal -if [[ "$file_path" == *".."* ]]; then - echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2 - exit 2 -fi - -# Deny sensitive files -if [[ "$file_path" == *".env"* ]]; then - echo '{"decision": "deny", "reason": "Sensitive file"}' >&2 - exit 2 -fi -``` - -See `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples. - -### Quote All Variables - -```bash -# GOOD: Quoted -echo "$file_path" -cd "$CLAUDE_PROJECT_DIR" - -# BAD: Unquoted (injection risk) -echo $file_path -cd $CLAUDE_PROJECT_DIR -``` - -### Set Appropriate Timeouts - -```json -{ - "type": "command", - "command": "bash script.sh", - "timeout": 10 -} -``` - -**Defaults:** Command hooks (60s), Prompt hooks (30s) - -## Performance Considerations - -### Parallel Execution - -All matching hooks run **in parallel**: - -```json -{ - "PreToolUse": [ - { - "matcher": "Write", - "hooks": [ - { "type": "command", "command": "check1.sh" }, // Parallel - { "type": "command", "command": "check2.sh" }, // Parallel - { "type": "prompt", "prompt": "Validate..." } // Parallel - ] - } - ] -} -``` - -**Design implications:** - -- Hooks don't see each other's output -- Non-deterministic ordering -- Design for independence - -### Optimization - -1. Use command hooks for quick deterministic checks -2. Use prompt hooks for complex reasoning -3. Cache validation results in temp files -4. Minimize I/O in hot paths - -## Hook Lifecycle and Limitations - -### Hooks Load at Session Start - -**Important:** Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code. - -**Cannot hot-swap hooks:** - -- Editing `hooks/hooks.json` won't affect 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:** - -1. Edit hook configuration or scripts -2. Exit Claude Code session -3. Restart: `claude` -4. New hook configuration loads -5. Test hooks with `claude --debug` - -### Hook Validation at Startup - -Hooks are validated when Claude Code starts: - -- Invalid JSON in hooks.json causes loading failure -- Missing scripts cause warnings -- Syntax errors reported in debug mode - -Use `/hooks` command to review loaded hooks in current session. - -## Debugging Hooks - -### Enable Debug Mode - -```bash -claude --debug -``` - -Look for hook registration, execution logs, input/output JSON, and timing information. - -### Test Hook Scripts - -Test command hooks directly: - -```bash -echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' | \ - bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh - -echo "Exit code: $?" -``` - -### Validate JSON Output - -Ensure hooks output valid JSON: - -```bash -output=$(./your-hook.sh < test-input.json) -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 - -## Additional Resources - -### Reference Files - -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 - -### Example Hook Scripts - -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 - -### Utility Scripts - -> **Prerequisites**: These scripts require `jq` for JSON validation. See the [main README](../../../../README.md#for-utility-scripts) for setup. - -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 - -### External Resources - -- **Official Docs**: -- **Examples**: See security-guidance plugin in marketplace -- **Testing**: Use `claude --debug` for detailed logs -- **Validation**: Use `jq` to validate hook JSON output - -## Implementation Workflow - -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 -3. Write hook configuration in `hooks/hooks.json` -4. For command hooks, create hook scripts -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/advanced.md b/plugins/plugin-dev/skills/hook-development/references/advanced.md deleted file mode 100644 index 01f5cfe..0000000 --- a/plugins/plugin-dev/skills/hook-development/references/advanced.md +++ /dev/null @@ -1,486 +0,0 @@ -# Advanced Hook Use Cases - -This reference covers advanced hook patterns and techniques for sophisticated automation workflows. - -## Multi-Stage Validation - -Combine command and prompt hooks for layered validation: - -```json -{ - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/quick-check.sh", - "timeout": 5 - }, - { - "type": "prompt", - "prompt": "Deep analysis of bash command: $TOOL_INPUT", - "timeout": 15 - } - ] - } - ] -} -``` - -**Use case:** Fast deterministic checks followed by intelligent analysis - -**Example quick-check.sh:** - -```bash -#!/bin/bash -input=$(cat) -command=$(echo "$input" | jq -r '.tool_input.command') - -# Immediate approval for safe commands -if [[ "$command" =~ ^(ls|pwd|echo|date|whoami)$ ]]; then - exit 0 -fi - -# Let prompt hook handle complex cases -exit 0 -``` - -The command hook quickly approves obviously safe commands, while the prompt hook analyzes everything else. - -## Conditional Hook Execution - -Execute hooks based on environment or context: - -```bash -#!/bin/bash -# Only run in CI environment -if [ -z "$CI" ]; then - echo '{"continue": true}' # Skip in non-CI - exit 0 -fi - -# Run validation logic in CI -input=$(cat) -# ... validation code ... -``` - -**Use cases:** - -- Different behavior in CI vs local development -- Project-specific validation -- User-specific rules - -**Example: Skip certain checks for trusted users:** - -```bash -#!/bin/bash -# Skip detailed checks for admin users -if [ "$USER" = "admin" ]; then - exit 0 -fi - -# Full validation for other users -input=$(cat) -# ... validation code ... -``` - -## Hook Chaining via State - -Share state between hooks using temporary files: - -```bash -# Hook 1: Analyze and save state -#!/bin/bash -input=$(cat) -command=$(echo "$input" | jq -r '.tool_input.command') - -# Analyze command -risk_level=$(calculate_risk "$command") -echo "$risk_level" > /tmp/hook-state-$$ - -exit 0 -``` - -```bash -# Hook 2: Use saved state -#!/bin/bash -risk_level=$(cat /tmp/hook-state-$$ 2>/dev/null || echo "unknown") - -if [ "$risk_level" = "high" ]; then - echo "High risk operation detected" >&2 - exit 2 -fi -``` - -**Important:** This only works for sequential hook events (e.g., PreToolUse then PostToolUse), not parallel hooks. - -## Dynamic Hook Configuration - -Modify hook behavior based on project configuration: - -```bash -#!/bin/bash -cd "$CLAUDE_PROJECT_DIR" || exit 1 - -# Read project-specific config -if [ -f ".claude-hooks-config.json" ]; then - strict_mode=$(jq -r '.strict_mode' .claude-hooks-config.json) - - if [ "$strict_mode" = "true" ]; then - # Apply strict validation - # ... - else - # Apply lenient validation - # ... - fi -fi -``` - -**Example .claude-hooks-config.json:** - -```json -{ - "strict_mode": true, - "allowed_commands": ["ls", "pwd", "grep"], - "forbidden_paths": ["/etc", "/sys"] -} -``` - -## Context-Aware Prompt Hooks - -Use transcript and session context for intelligent decisions: - -```json -{ - "Stop": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "Review the full transcript at $TRANSCRIPT_PATH. Check: 1) Were tests run after code changes? 2) Did the build succeed? 3) Were all user questions answered? 4) Is there any unfinished work? Return 'approve' only if everything is complete." - } - ] - } - ] -} -``` - -The LLM can read the transcript file and make context-aware decisions. - -## Performance Optimization - -### Caching Validation Results - -```bash -#!/bin/bash -input=$(cat) -file_path=$(echo "$input" | jq -r '.tool_input.file_path') -cache_key=$(echo -n "$file_path" | md5sum | cut -d' ' -f1) -cache_file="/tmp/hook-cache-$cache_key" - -# Check cache -if [ -f "$cache_file" ]; then - cache_age=$(($(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file"))) - if [ "$cache_age" -lt 300 ]; then # 5 minute cache - cat "$cache_file" - exit 0 - fi -fi - -# Perform validation -result='{"decision": "approve"}' - -# Cache result -echo "$result" > "$cache_file" -echo "$result" -``` - -### Parallel Execution Optimization - -Since hooks run in parallel, design them to be independent: - -```json -{ - "PreToolUse": [ - { - "matcher": "Write", - "hooks": [ - { - "type": "command", - "command": "bash check-size.sh", // Independent - "timeout": 2 - }, - { - "type": "command", - "command": "bash check-path.sh", // Independent - "timeout": 2 - }, - { - "type": "prompt", - "prompt": "Check content safety", // Independent - "timeout": 10 - } - ] - } - ] -} -``` - -All three hooks run simultaneously, reducing total latency. - -## Cross-Event Workflows - -Coordinate hooks across different events: - -**SessionStart - Set up tracking:** - -```bash -#!/bin/bash -# Initialize session tracking -echo "0" > /tmp/test-count-$$ -echo "0" > /tmp/build-count-$$ -``` - -**PostToolUse - Track events:** - -```bash -#!/bin/bash -input=$(cat) -tool_name=$(echo "$input" | jq -r '.tool_name') - -if [ "$tool_name" = "Bash" ]; then - command=$(echo "$input" | jq -r '.tool_result') - if [[ "$command" == *"test"* ]]; then - count=$(cat /tmp/test-count-$$ 2>/dev/null || echo "0") - echo $((count + 1)) > /tmp/test-count-$$ - fi -fi -``` - -**Stop - Verify based on tracking:** - -```bash -#!/bin/bash -test_count=$(cat /tmp/test-count-$$ 2>/dev/null || echo "0") - -if [ "$test_count" -eq 0 ]; then - echo '{"decision": "block", "reason": "No tests were run"}' >&2 - exit 2 -fi -``` - -## Integration with External Systems - -### Slack Notifications - -```bash -#!/bin/bash -input=$(cat) -tool_name=$(echo "$input" | jq -r '.tool_name') -decision="blocked" - -# Send notification to Slack -curl -X POST "$SLACK_WEBHOOK" \ - -H 'Content-Type: application/json' \ - -d "{\"text\": \"Hook ${decision} ${tool_name} operation\"}" \ - 2>/dev/null - -echo '{"decision": "deny"}' >&2 -exit 2 -``` - -### Database Logging - -```bash -#!/bin/bash -input=$(cat) - -# Log to database -psql "$DATABASE_URL" -c "INSERT INTO hook_logs (event, data) VALUES ('PreToolUse', '$input')" \ - 2>/dev/null - -exit 0 -``` - -### Metrics Collection - -```bash -#!/bin/bash -input=$(cat) -tool_name=$(echo "$input" | jq -r '.tool_name') - -# Send metrics to monitoring system -echo "hook.pretooluse.${tool_name}:1|c" | nc -u -w1 statsd.local 8125 - -exit 0 -``` - -## Security Patterns - -### Rate Limiting - -```bash -#!/bin/bash -input=$(cat) -command=$(echo "$input" | jq -r '.tool_input.command') - -# Track command frequency -rate_file="/tmp/hook-rate-$$" -current_minute=$(date +%Y%m%d%H%M) - -if [ -f "$rate_file" ]; then - last_minute=$(head -1 "$rate_file") - count=$(tail -1 "$rate_file") - - if [ "$current_minute" = "$last_minute" ]; then - if [ "$count" -gt 10 ]; then - echo '{"decision": "deny", "reason": "Rate limit exceeded"}' >&2 - exit 2 - fi - count=$((count + 1)) - else - count=1 - fi -else - count=1 -fi - -echo "$current_minute" > "$rate_file" -echo "$count" >> "$rate_file" - -exit 0 -``` - -### Audit Logging - -```bash -#!/bin/bash -input=$(cat) -tool_name=$(echo "$input" | jq -r '.tool_name') -timestamp=$(date -Iseconds) - -# Append to audit log -echo "$timestamp | $USER | $tool_name | $input" >> ~/.claude/audit.log - -exit 0 -``` - -### Secret Detection - -```bash -#!/bin/bash -input=$(cat) -content=$(echo "$input" | jq -r '.tool_input.content') - -# Check for common secret patterns -if echo "$content" | grep -qE "(api[_-]?key|password|secret|token).{0,20}['\"]?[A-Za-z0-9]{20,}"; then - echo '{"decision": "deny", "reason": "Potential secret detected in content"}' >&2 - exit 2 -fi - -exit 0 -``` - -## Testing Advanced Hooks - -### Unit Testing Hook Scripts - -```bash -# test-hook.sh -#!/bin/bash - -# Test 1: Approve safe command -result=$(echo '{"tool_input": {"command": "ls"}}' | bash validate-bash.sh) -if [ $? -eq 0 ]; then - echo "✓ Test 1 passed" -else - echo "✗ Test 1 failed" -fi - -# Test 2: Block dangerous command -result=$(echo '{"tool_input": {"command": "rm -rf /"}}' | bash validate-bash.sh) -if [ $? -eq 2 ]; then - echo "✓ Test 2 passed" -else - echo "✗ Test 2 failed" -fi -``` - -### Integration Testing - -Create test scenarios that exercise the full hook workflow: - -```bash -# integration-test.sh -#!/bin/bash - -# Set up test environment -export CLAUDE_PROJECT_DIR="/tmp/test-project" -export CLAUDE_PLUGIN_ROOT="$(pwd)" -mkdir -p "$CLAUDE_PROJECT_DIR" - -# Test SessionStart hook -echo '{}' | bash hooks/session-start.sh -if [ -f "/tmp/session-initialized" ]; then - echo "✓ SessionStart hook works" -else - echo "✗ SessionStart hook failed" -fi - -# Clean up -rm -rf "$CLAUDE_PROJECT_DIR" -``` - -## Best Practices for Advanced Hooks - -1. **Keep hooks independent**: Don't rely on execution order -2. **Use timeouts**: Set appropriate limits for each hook type -3. **Handle errors gracefully**: Provide clear error messages -4. **Document complexity**: Explain advanced patterns in README -5. **Test thoroughly**: Cover edge cases and failure modes -6. **Monitor performance**: Track hook execution time -7. **Version configuration**: Use version control for hook configs -8. **Provide escape hatches**: Allow users to bypass hooks when needed - -## Common Pitfalls - -### ❌ Assuming Hook Order - -```bash -# BAD: Assumes hooks run in specific order -# Hook 1 saves state, Hook 2 reads it -# This can fail because hooks run in parallel! -``` - -### ❌ Long-Running Hooks - -```bash -# BAD: Hook takes 2 minutes to run -sleep 120 -# This will timeout and block the workflow -``` - -### ❌ Uncaught Exceptions - -```bash -# BAD: Script crashes on unexpected input -file_path=$(echo "$input" | jq -r '.tool_input.file_path') -cat "$file_path" # Fails if file doesn't exist -``` - -### ✅ Proper Error Handling - -```bash -# GOOD: Handles errors gracefully -file_path=$(echo "$input" | jq -r '.tool_input.file_path') -if [ ! -f "$file_path" ]; then - echo '{"continue": true, "systemMessage": "File not found, skipping check"}' >&2 - exit 0 -fi -``` - -## 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/patterns.md b/plugins/plugin-dev/skills/hook-development/references/patterns.md deleted file mode 100644 index fe4580b..0000000 --- a/plugins/plugin-dev/skills/hook-development/references/patterns.md +++ /dev/null @@ -1,352 +0,0 @@ -# Common Hook Patterns - -This reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases. - -## Pattern 1: Security Validation - -Block dangerous file writes using prompt-based hooks: - -```json -{ - "PreToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [ - { - "type": "prompt", - "prompt": "File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'." - } - ] - } - ] -} -``` - -**Use for:** Preventing writes to sensitive files or system directories. - -## Pattern 2: Test Enforcement - -Ensure tests run before stopping: - -```json -{ - "Stop": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'." - } - ] - } - ] -} -``` - -**Use for:** Enforcing quality standards and preventing incomplete work. - -## Pattern 3: Context Loading - -Load project-specific context at session start: - -```json -{ - "SessionStart": [ - { - "matcher": "*", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh" - } - ] - } - ] -} -``` - -**Example script (load-context.sh):** - -```bash -#!/bin/bash -cd "$CLAUDE_PROJECT_DIR" || exit 1 - -# Detect project type -if [ -f "package.json" ]; then - echo "📦 Node.js project detected" - echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE" -elif [ -f "Cargo.toml" ]; then - echo "🦀 Rust project detected" - echo "export PROJECT_TYPE=rust" >> "$CLAUDE_ENV_FILE" -fi -``` - -**Use for:** Automatically detecting and configuring project-specific settings. - -## Pattern 4: Notification Logging - -Log all notifications for audit or analysis: - -```json -{ - "Notification": [ - { - "matcher": "*", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh" - } - ] - } - ] -} -``` - -**Use for:** Tracking user notifications or integration with external logging systems. - -## Pattern 5: MCP Tool Monitoring - -Monitor and validate MCP tool usage: - -```json -{ - "PreToolUse": [ - { - "matcher": "mcp__.*__delete.*", - "hooks": [ - { - "type": "prompt", - "prompt": "Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe." - } - ] - } - ] -} -``` - -**Use for:** Protecting against destructive MCP operations. - -## Pattern 6: Build Verification - -Ensure project builds after code changes: - -```json -{ - "Stop": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build." - } - ] - } - ] -} -``` - -**Use for:** Catching build errors before committing or stopping work. - -## Pattern 7: Permission Confirmation - -Ask user before dangerous operations: - -```json -{ - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "prompt", - "prompt": "Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'." - } - ] - } - ] -} -``` - -**Use for:** User confirmation on potentially destructive commands. - -## Pattern 8: Code Quality Checks - -Run linters or formatters on file edits: - -```json -{ - "PostToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh" - } - ] - } - ] -} -``` - -**Example script (check-quality.sh):** - -```bash -#!/bin/bash -input=$(cat) -file_path=$(echo "$input" | jq -r '.tool_input.file_path') - -# Run linter if applicable -if [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then - npx eslint "$file_path" 2>&1 || true -fi -``` - -**Use for:** Automatic code quality enforcement. - -## Pattern Combinations - -Combine multiple patterns for comprehensive protection: - -```json -{ - "PreToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [ - { - "type": "prompt", - "prompt": "Validate file write safety" - } - ] - }, - { - "matcher": "Bash", - "hooks": [ - { - "type": "prompt", - "prompt": "Validate bash command safety" - } - ] - } - ], - "Stop": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "Verify tests run and build succeeded" - } - ] - } - ], - "SessionStart": [ - { - "matcher": "*", - "hooks": [ - { - "type": "command", - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh" - } - ] - } - ] -} -``` - -This provides multi-layered protection and automation. - -## Pattern 9: Temporarily Active Hooks - -Create hooks that only run when explicitly enabled via flag files: - -```bash -#!/bin/bash -# Hook only active when flag file exists -FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-security-scan" - -if [ ! -f "$FLAG_FILE" ]; then - # Quick exit when disabled - exit 0 -fi - -# Flag present, run validation -input=$(cat) -file_path=$(echo "$input" | jq -r '.tool_input.file_path') - -# Run security scan -security-scanner "$file_path" -``` - -**Activation:** - -```bash -# Enable the hook -touch .enable-security-scan - -# Disable the hook -rm .enable-security-scan -``` - -**Use for:** - -- Temporary debugging hooks -- Feature flags for development -- Project-specific validation that's opt-in -- Performance-intensive checks only when needed - -**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes. - -## Pattern 10: Configuration-Driven Hooks - -Use JSON configuration to control hook behavior: - -```bash -#!/bin/bash -CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json" - -# Read configuration -if [ -f "$CONFIG_FILE" ]; then - strict_mode=$(jq -r '.strictMode // false' "$CONFIG_FILE") - max_file_size=$(jq -r '.maxFileSize // 1000000' "$CONFIG_FILE") -else - # Defaults - strict_mode=false - max_file_size=1000000 -fi - -# Skip if not in strict mode -if [ "$strict_mode" != "true" ]; then - exit 0 -fi - -# Apply configured limits -input=$(cat) -file_size=$(echo "$input" | jq -r '.tool_input.content | length') - -if [ "$file_size" -gt "$max_file_size" ]; then - echo '{"decision": "deny", "reason": "File exceeds configured size limit"}' >&2 - exit 2 -fi -``` - -**Configuration file (.claude/my-plugin.local.json):** - -```json -{ - "strictMode": true, - "maxFileSize": 500000, - "allowedPaths": ["/tmp", "/home/user/projects"] -} -``` - -**Use for:** - -- User-configurable hook behavior -- Per-project settings -- Team-specific rules -- Dynamic validation criteria diff --git a/plugins/plugin-dev/skills/plugin-dev-workspace/organic-prompts.json b/plugins/plugin-dev/skills/plugin-dev-workspace/organic-prompts.json new file mode 100644 index 0000000..7daf6fa --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev-workspace/organic-prompts.json @@ -0,0 +1,182 @@ +[ + { + "skill_activated": "plugin-dev:agent-development", + "prompt": "Use what we've learned on this project to build a claude code sub agent with /plugin-dev that knows how to verify and QA our tmux project using tmux. Any chance there's a cucumber-like integration testing framework for tmux?", + "project": "opensessions", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:agent-development", + "prompt": "I think that our /plugin-dev-guide command should use a subagent to do discovery to avoid polluting the main context window. Let's make a agent using our skills. It should both use the map of plugin-dev skills available via this plugin but ALSO use the instruction set in @/Users/kyle/Code/meta-claud", + "project": "plugin-dev", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:agent-development", + "prompt": "I'm actually liking option B the best - the decomposability of the skills gives us the the benefit of progressive disclosure, and the ability to use the skills ad-hoc.\n\nWe can use the newly added 'initial prompt' field in the agent frontmatter (see /plugin-dev:hook-development ) the agent body is th", + "project": "ralph-ban", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:command-development", + "prompt": "Sounds like a bug that needs fixing - I doubt your analysis is correct, if it failed once it will fail again, and AI agents will need to 'correct' it every time. use /plugin-dev to solve the issue", + "project": "Envato-non-market-ai-engineering-domain", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:command-development", + "prompt": "@plugins/sc-hooks/commands/sc-copy-prompt.md has a special pattern. I think it's got a documented name somwhere in our codebase. it uses the plugins/sc-hooks/hooks/handlers/copy_message_handler.rb handler.\n\nIt's a pattern that blocks the actual prompt from triggering any API calls, but performs a co", + "project": "SimpleClaude", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:command-development", + "prompt": "Better. I also just QA'd the music /command and I saw that it executes an API call - what does /plugin-dev-guide say about executing /commands that perform an action programatically without hitting the API?", + "project": "claude-code-hero", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:command-development", + "prompt": "yes - use plugin-dev skills", + "project": "claude-code-hero", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:command-development", + "prompt": "Let's add a convenience /command called `rb-auto-toggle` that toggles the config file safely for the given session.", + "project": "ralph-ban", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "Proceed with updating step 1 with the findings, then let's move on with the next step", + "project": "Envato-non-market-Envato-AI-Engineering-Team-x-workflow-claude", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "This is an issue we certainly need to address - I doubt we're following the /plugin-dev contract if we get 4 hook errors every time if something isn't configured properly. Failing open is the right path", + "project": "opensessions", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "lol \" Claude Code doesn't expose a PermissionRequest \" what are you fucking talking about? /plugin-dev", + "project": "opensessions", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "What about Yaml frontmatter plugin hooks?", + "project": "claude-code-hero", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "I think the reactivity is important to the permission prompt - if the user accepts 'for this session' it wont fire again, but if they don't we should be prepared for it to fire multiple times", + "project": "claude-code-hero", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "use /plugin-dev-guide to find the right hook to use for this lesson - I'm not sure UserPromptSubmit is the best (though it would work)", + "project": "claude-code-hero", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "Whoa sick okay - let's create a sessionstart hook for claude-code hero that instructs the agent to output CLAUDE CODE HERO in figlet style before anything, this will give the user the feeling of playing a game!", + "project": "claude-code-hero", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:hook-development", + "prompt": "sure let's see what yo got /plugin-dev:hook-development", + "project": "claude-code-hero", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:marketplace-structure", + "prompt": "How do I install the plugin properly?", + "project": "Envato-non-market-ai-engineering-domain", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:plugin-dev-guide", + "prompt": "the behavior you outlined for UserPromptSubmit no longer looks correct to me. Should we combine the current UserPromptSubmit and Stop hooks into a single Stop hook? /plugin-dev:plugin-dev-guide", + "project": "ralph-ban", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:plugin-dev-guide", + "prompt": "Couple of concerns with the plan:\n# /rb-brainstorm\n- We should try to move away from 'slash commands' and move towards 'skills' use /plugin-dev:plugin-dev-guide to help guide you\n- ensure .agent-history/ is always made with -p, critical that we don't accidentlly overwrite a directory that already ex", + "project": "ralph-ban", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:plugin-dev-guide", + "prompt": "Ok - let's be thorough I don't want to raise a nonsense issue. Let's find out what 'fine-grained control' means in actual practice, with evidence from code, and then use /plugin-dev to map 1 to 1 how we can solve this with native CC", + "project": "tail-claude", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:plugin-structure", + "prompt": "## Task: Build a Claude Code plugin that encodes the X Workflow methodology\n\n### What the X Workflow is\n\nA 5-stage scientific methodology for AI-assisted development. Every task flows through these stages in order, with human review gates between each:\n\n1. **Problem Discovery** -- observe, gather da", + "project": "Envato-non-market-Envato-AI-Engineering-Team-x-workflow-claude", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:plugin-structure", + "prompt": "no that's wrong. check /plugin-dev skills and research properly", + "project": "Envato-non-market-ai-engineering-domain", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:plugin-structure", + "prompt": "for FINDING-002 I think we can leave this plugin as 'opt in' completely - we don't need the mcp AND cli both\ndefinitely update to use ${CLAUDE_PLUGIN_ROOT} everywhere or absolute paths, relative paths are breaking paths according to /plugin-dev right?\nMaybe just remove the plugin count altogether - ", + "project": "Envato-non-market-ai-engineering-domain-ai-engineering-team", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:plugin-structure", + "prompt": "how does the new userConfig setting work in plugin dev?", + "project": "plugin-dev", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:plugin-structure", + "prompt": "don't do that - instead fix my config", + "project": "claude-code-hero", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:skill-development", + "prompt": "Hold up sorry I need to be more clear with the brief. This is a generalizable tmux testing agent. It's goal is to take a code change set as done by an implementer agent, and QA it. Not necessarily tied to bun or opensessions. I'll be using this in a new project that is go-based.", + "project": "opensessions", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:skill-development", + "prompt": "Open a new feature branch - and explore this direction.", + "project": "plugin-dev", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:skill-development", + "prompt": "look up the claude-code skills-creator or skills-evaluator - they have a series of eval tools we could maybe use to help us get better results.", + "project": "SimpleClaude", + "explicit_invocation": false + }, + { + "skill_activated": "plugin-dev:skill-development", + "prompt": "Write a simpleclaude SKILL.md using /plugin-dev in the style of SimpleClaude for taking a repo, project, or other artifact and performing a Clean-Room Design of it to the user's specifications. Apply a staged approach of discovery-specify-implement-verify. Add it to the sc-extras plugin", + "project": "SimpleClaude", + "explicit_invocation": true + }, + { + "skill_activated": "plugin-dev:update-from-upstream", + "prompt": "activate upstream sync skills and let's sync with the latest version", + "project": "plugin-dev", + "explicit_invocation": false + } +] \ No newline at end of file diff --git a/plugins/plugin-dev/skills/plugin-dev-workspace/run_3way_eval.py b/plugins/plugin-dev/skills/plugin-dev-workspace/run_3way_eval.py new file mode 100644 index 0000000..ff761ae --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev-workspace/run_3way_eval.py @@ -0,0 +1,363 @@ +#!/usr/bin/env python3 +"""3-way trigger evaluation for plugin-dev skill consolidation. + +Uses clean temp directories per query (workaround from anthropics/claude-plugins-official#1357) +to isolate description triggering from competing plugins/tools. + +Configs: +1. current-11-skills: All 11 plugin-dev skill descriptions as separate commands +2. consolidated-1-skill: Single consolidated description as one command +3. no-plugin: No commands (baseline - nothing should trigger) +""" + +import argparse +import json +import os +import select +import shutil +import subprocess +import tempfile +import time +import uuid +from concurrent.futures import ProcessPoolExecutor, as_completed +from pathlib import Path + + +# Current 11-skill descriptions from main branch +CURRENT_SKILLS = { + "plugin-dev-guide": '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-structure": '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.', + "command-development": '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.', + "agent-development": '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.', + "skill-development": '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.', + "hook-development": '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.', + "mcp-integration": '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.', + "lsp-integration": '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.', + "plugin-settings": '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.', + "marketplace-structure": '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.', + "update-from-upstream": '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.', +} + +CONSOLIDATED_DESCRIPTION = ( + 'MUST use this skill when the user mentions plugins, hooks, skills, commands, agents, ' + 'MCP servers, LSP servers, marketplaces, plugin.json, SKILL.md, .mcp.json, .local.md, ' + 'allowed-tools, frontmatter, PreToolUse, PostToolUse, SessionStart, event schemas, ' + 'prompt-based hooks, plugin settings, output styles, headless mode, CI mode, ' + 'CLAUDE_PLUGIN_ROOT, auto-discovery, or any aspect of extending Claude Code. ' + 'Use INSTEAD OF answering from general knowledge. Also use when writing hooks for ' + 'settings.json, configuring MCP servers outside plugins, or comparing skills vs commands, ' + 'since this skill contains the authoritative reference for these Claude Code extension mechanisms.' +) + + +def create_clean_dir(skill_descs: dict[str, str]) -> str: + """Create a clean temp directory with skill descriptions as commands.""" + tmpdir = tempfile.mkdtemp(prefix="pd-eval-") + commands_dir = Path(tmpdir) / ".claude" / "commands" + commands_dir.mkdir(parents=True) + + # Disable all plugins + settings = Path(tmpdir) / ".claude" / "settings.json" + settings.write_text('{"enabledPlugins": {}}') + + # Write each skill as a command + uid = uuid.uuid4().hex[:6] + name_map = {} + for skill_name, desc in skill_descs.items(): + clean = f"pd-{skill_name}-{uid}" + name_map[clean] = skill_name + indented = "\n ".join(desc.split("\n")) + (commands_dir / f"{clean}.md").write_text( + f"---\ndescription: |\n {indented}\n---\n\n" + f"# {skill_name}\n\nThis skill handles: {desc}\n" + ) + + return tmpdir, name_map + + +def run_single( + query: str, + skill_descs: dict[str, str], + timeout: int, + model: str | None = None, +) -> dict: + """Run one query in a clean temp dir. Returns trigger result.""" + if not skill_descs: + # No-plugin baseline: still need a clean dir + tmpdir = tempfile.mkdtemp(prefix="pd-eval-") + (Path(tmpdir) / ".claude").mkdir() + (Path(tmpdir) / ".claude" / "settings.json").write_text('{"enabledPlugins": {}}') + name_map = {} + else: + tmpdir, name_map = create_clean_dir(skill_descs) + + result = {"triggered": False, "skill_name": None, "first_tool": None} + + try: + cmd = ["claude", "-p", query, "--output-format", "stream-json", + "--verbose", "--include-partial-messages"] + if model: + cmd.extend(["--model", model]) + + env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"} + + proc = subprocess.Popen( + cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, + cwd=tmpdir, env=env, + ) + + start = time.time() + buf = "" + pending = None + acc_json = "" + + try: + while time.time() - start < timeout: + if proc.poll() is not None: + rest = proc.stdout.read() + if rest: + buf += rest.decode("utf-8", errors="replace") + break + + ready, _, _ = select.select([proc.stdout], [], [], 1.0) + if not ready: + continue + + chunk = os.read(proc.stdout.fileno(), 8192) + if not chunk: + break + buf += chunk.decode("utf-8", errors="replace") + + while "\n" in buf: + line, buf = buf.split("\n", 1) + line = line.strip() + if not line: + continue + try: + ev = json.loads(line) + except json.JSONDecodeError: + continue + + if ev.get("type") == "stream_event": + se = ev.get("event", {}) + st = se.get("type", "") + + if st == "content_block_start": + cb = se.get("content_block", {}) + if cb.get("type") == "tool_use": + tn = cb.get("name", "") + if result["first_tool"] is None: + result["first_tool"] = tn + if tn in ("Skill", "Read"): + pending = tn + acc_json = "" + else: + return result + + elif st == "content_block_delta" and pending: + delta = se.get("delta", {}) + if delta.get("type") == "input_json_delta": + acc_json += delta.get("partial_json", "") + for cn, orig in name_map.items(): + if cn in acc_json: + result["triggered"] = True + result["skill_name"] = orig + return result + + elif st in ("content_block_stop", "message_stop"): + if pending: + for cn, orig in name_map.items(): + if cn in acc_json: + result["triggered"] = True + result["skill_name"] = orig + return result + pending = None + if st == "message_stop": + return result + + elif ev.get("type") == "assistant": + msg = ev.get("message", {}) + for blk in msg.get("content", []): + if blk.get("type") != "tool_use": + continue + tn = blk.get("name", "") + if result["first_tool"] is None: + result["first_tool"] = tn + if tn in ("Skill", "Read"): + target = blk.get("input", {}).get("skill", "") or blk.get("input", {}).get("file_path", "") + for cn, orig in name_map.items(): + if cn in target: + result["triggered"] = True + result["skill_name"] = orig + return result + + elif ev.get("type") == "result": + return result + finally: + if proc.poll() is None: + proc.kill() + proc.wait() + finally: + shutil.rmtree(tmpdir, ignore_errors=True) + + return result + + +def run_config( + eval_set: list[dict], + skill_descs: dict[str, str], + config_name: str, + num_workers: int, + timeout: int, + runs_per_query: int, + model: str | None = None, +) -> list[dict]: + """Run all queries for one configuration with multiple runs each.""" + results = [] + + with ProcessPoolExecutor(max_workers=num_workers) as pool: + futures = {} + for item in eval_set: + for run_idx in range(runs_per_query): + f = pool.submit(run_single, item["query"], skill_descs, timeout, model) + futures[f] = (item, run_idx) + + # Aggregate by query + query_runs: dict[str, list[dict]] = {} + query_items: dict[str, dict] = {} + for f in as_completed(futures): + item, run_idx = futures[f] + q = item["query"] + query_items[q] = item + if q not in query_runs: + query_runs[q] = [] + try: + query_runs[q].append(f.result()) + except Exception as e: + query_runs[q].append({"triggered": False, "skill_name": None, "first_tool": None, "error": str(e)}) + + for q, runs in query_runs.items(): + item = query_items[q] + trigger_count = sum(1 for r in runs if r["triggered"]) + trigger_rate = trigger_count / len(runs) + skills_triggered = [r["skill_name"] for r in runs if r["skill_name"]] + first_tools = [r["first_tool"] for r in runs if r["first_tool"]] + + results.append({ + "query": q[:150], + "should_trigger": item["should_trigger"], + "topic": item.get("topic", ""), + "config": config_name, + "trigger_count": trigger_count, + "total_runs": len(runs), + "trigger_rate": round(trigger_rate, 2), + "triggered": trigger_rate >= 0.5, # majority vote + "skills_triggered": skills_triggered, + "first_tools": first_tools, + }) + + return results + + +def score(results: list[dict]) -> dict: + tp = sum(1 for r in results if r["should_trigger"] and r["triggered"]) + fn = sum(1 for r in results if r["should_trigger"] and not r["triggered"]) + tn = sum(1 for r in results if not r["should_trigger"] and not r["triggered"]) + fp = sum(1 for r in results if not r["should_trigger"] and r["triggered"]) + total = len(results) + pos = tp + fn + neg = tn + fp + return { + "accuracy": round((tp + tn) / total, 3) if total else 0, + "trigger_rate": round(tp / pos, 3) if pos else 0, + "false_pos_rate": round(fp / neg, 3) if neg else 0, + "tp": tp, "fn": fn, "tn": tn, "fp": fp, "total": total, + } + + +def print_config(name: str, results: list[dict], scores: dict): + print(f"\n{'=' * 70}") + print(f" {name}") + print(f"{'=' * 70}") + print(f" Accuracy: {scores['accuracy']:.1%} | " + f"Trigger rate: {scores['trigger_rate']:.1%} | " + f"False pos rate: {scores['false_pos_rate']:.1%}") + print(f" TP={scores['tp']} FN={scores['fn']} TN={scores['tn']} FP={scores['fp']}") + + for r in sorted(results, key=lambda x: x["topic"]): + tag = "should_trigger" if r["should_trigger"] else "should_not " + status = f"{r['trigger_count']}/{r['total_runs']}" + match = "OK" if r["should_trigger"] == r["triggered"] else "MISS" + skill = r["skills_triggered"][0] if r["skills_triggered"] else "-" + print(f" [{match:4s}] {tag} {status:5s} skill={skill:25s} {r['query'][:80]}") + + +def main(): + parser = argparse.ArgumentParser(description="3-way plugin-dev trigger eval") + parser.add_argument("--eval-set", required=True) + parser.add_argument("--output", default="trigger-eval-results.json") + parser.add_argument("--workers", type=int, default=4) + parser.add_argument("--timeout", type=int, default=45) + parser.add_argument("--runs", type=int, default=3, help="Runs per query per config") + parser.add_argument("--model", default=None) + parser.add_argument("--skip-baseline", action="store_true") + args = parser.parse_args() + + with open(args.eval_set) as f: + eval_set = json.load(f) + + n_pos = sum(1 for e in eval_set if e["should_trigger"]) + n_neg = sum(1 for e in eval_set if not e["should_trigger"]) + total_runs = len(eval_set) * args.runs * (2 if args.skip_baseline else 3) + print(f"Eval set: {len(eval_set)} queries ({n_pos} should-trigger, {n_neg} should-not)") + print(f"Runs per query: {args.runs}") + print(f"Total claude -p invocations: {total_runs}") + print(f"Workers: {args.workers}") + + all_results = {} + + # Config 1: Current 11 skills + print(f"\n>>> Config 1: Current 11 skills ({len(CURRENT_SKILLS)} descriptions)") + t0 = time.time() + r1 = run_config(eval_set, CURRENT_SKILLS, "current-11-skills", + args.workers, args.timeout, args.runs, args.model) + s1 = score(r1) + print_config(f"Current (11 skills) [{time.time()-t0:.0f}s]", r1, s1) + all_results["current-11-skills"] = {"results": r1, "scores": s1} + + # Config 2: Consolidated single skill + print(f"\n>>> Config 2: Consolidated single skill") + t0 = time.time() + r2 = run_config(eval_set, {"plugin-dev": CONSOLIDATED_DESCRIPTION}, + "consolidated-1-skill", args.workers, args.timeout, args.runs, args.model) + s2 = score(r2) + print_config(f"Consolidated (1 skill) [{time.time()-t0:.0f}s]", r2, s2) + all_results["consolidated-1-skill"] = {"results": r2, "scores": s2} + + # Config 3: No plugin baseline + if not args.skip_baseline: + print(f"\n>>> Config 3: No plugin (baseline)") + t0 = time.time() + r3 = run_config(eval_set, {}, "no-plugin", + args.workers, args.timeout, args.runs, args.model) + s3 = score(r3) + print_config(f"No Plugin (baseline) [{time.time()-t0:.0f}s]", r3, s3) + all_results["no-plugin"] = {"results": r3, "scores": s3} + + # Summary + print(f"\n{'=' * 70}") + print(" COMPARISON SUMMARY") + print(f"{'=' * 70}") + print(f" {'Config':<25s} {'Accuracy':>10s} {'TriggerRate':>12s} {'FalsePosRate':>13s}") + print(f" {'-' * 60}") + for name, data in all_results.items(): + s = data["scores"] + print(f" {name:<25s} {s['accuracy']:>9.1%} {s['trigger_rate']:>11.1%} {s['false_pos_rate']:>12.1%}") + + with open(args.output, "w") as f: + json.dump(all_results, f, indent=2) + print(f"\nResults saved to {args.output}") + + +if __name__ == "__main__": + main() diff --git a/plugins/plugin-dev/skills/plugin-dev-workspace/run_trigger_eval.py b/plugins/plugin-dev/skills/plugin-dev-workspace/run_trigger_eval.py new file mode 100644 index 0000000..461c6cb --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev-workspace/run_trigger_eval.py @@ -0,0 +1,332 @@ +#!/usr/bin/env python3 +"""3-way trigger evaluation for plugin-dev skill consolidation. + +Tests whether plugin-dev skills trigger for a set of queries across three configurations: +1. Current 11-skill plugin (main branch) +2. Consolidated single-skill plugin (feature branch) +3. No plugin (vanilla Claude Code baseline) + +Uses `claude -p --plugin-dir` with stream-json output to detect Skill tool invocations. +""" + +import argparse +import json +import os +import select +import subprocess +import sys +import time +from concurrent.futures import ProcessPoolExecutor, as_completed +from pathlib import Path + + +def run_single_query( + query: str, + plugin_dir: str | None, + config_name: str, + timeout: int, + project_root: str, + model: str | None = None, +) -> dict: + """Run a single query and return trigger results. + + Returns dict with: + triggered: bool - whether any plugin-dev skill was triggered + skill_name: str | None - which skill was triggered (if any) + first_tool: str | None - first tool the model tried to use + """ + cmd = [ + "claude", + "-p", query, + "--output-format", "stream-json", + "--verbose", + "--include-partial-messages", + "--max-turns", "2", + ] + if plugin_dir: + cmd.extend(["--plugin-dir", plugin_dir]) + if model: + cmd.extend(["--model", model]) + + env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"} + + process = subprocess.Popen( + cmd, + stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, + cwd=project_root, + env=env, + ) + + result = {"triggered": False, "skill_name": None, "first_tool": None} + start_time = time.time() + buffer = "" + pending_tool_name = None + accumulated_json = "" + + try: + while time.time() - start_time < timeout: + if process.poll() is not None: + remaining = process.stdout.read() + if remaining: + buffer += remaining.decode("utf-8", errors="replace") + break + + ready, _, _ = select.select([process.stdout], [], [], 1.0) + if not ready: + continue + + chunk = os.read(process.stdout.fileno(), 8192) + if not chunk: + break + buffer += chunk.decode("utf-8", errors="replace") + + while "\n" in buffer: + line, buffer = buffer.split("\n", 1) + line = line.strip() + if not line: + continue + + try: + event = json.loads(line) + except json.JSONDecodeError: + continue + + # Detect via stream events + if event.get("type") == "stream_event": + se = event.get("event", {}) + se_type = se.get("type", "") + + if se_type == "content_block_start": + cb = se.get("content_block", {}) + if cb.get("type") == "tool_use": + tool_name = cb.get("name", "") + if result["first_tool"] is None: + result["first_tool"] = tool_name + if tool_name == "Skill": + pending_tool_name = "Skill" + accumulated_json = "" + + elif se_type == "content_block_delta" and pending_tool_name == "Skill": + delta = se.get("delta", {}) + if delta.get("type") == "input_json_delta": + accumulated_json += delta.get("partial_json", "") + if "plugin-dev" in accumulated_json: + # Extract skill name + try: + partial = json.loads(accumulated_json) + result["skill_name"] = partial.get("skill", accumulated_json) + except json.JSONDecodeError: + result["skill_name"] = accumulated_json + result["triggered"] = True + return result + + elif se_type == "content_block_stop" and pending_tool_name == "Skill": + if "plugin-dev" in accumulated_json: + try: + parsed = json.loads(accumulated_json) + result["skill_name"] = parsed.get("skill", "") + except json.JSONDecodeError: + result["skill_name"] = accumulated_json + result["triggered"] = True + pending_tool_name = None + return result + + elif se_type == "message_stop": + return result + + # Fallback: full assistant message + elif event.get("type") == "assistant": + message = event.get("message", {}) + for block in message.get("content", []): + if block.get("type") != "tool_use": + continue + if block.get("name") == "Skill": + skill = block.get("input", {}).get("skill", "") + if "plugin-dev" in skill: + result["triggered"] = True + result["skill_name"] = skill + if result["first_tool"] is None: + result["first_tool"] = block.get("name", "") + return result + + elif event.get("type") == "result": + return result + + finally: + if process.poll() is None: + process.kill() + process.wait() + + return result + + +def run_config( + eval_set: list[dict], + plugin_dir: str | None, + config_name: str, + num_workers: int, + timeout: int, + project_root: str, + model: str | None = None, +) -> list[dict]: + """Run all queries for one configuration.""" + results = [] + + with ProcessPoolExecutor(max_workers=num_workers) as executor: + future_to_query = {} + for item in eval_set: + future = executor.submit( + run_single_query, + item["query"], + plugin_dir, + config_name, + timeout, + project_root, + model, + ) + future_to_query[future] = item + + for future in as_completed(future_to_query): + item = future_to_query[future] + try: + result = future.result() + except Exception as e: + result = {"triggered": False, "skill_name": None, "first_tool": None, "error": str(e)} + + results.append({ + "query": item["query"], + "should_trigger": item["should_trigger"], + "topic": item.get("topic", ""), + "config": config_name, + **result, + }) + + return results + + +def score_results(results: list[dict]) -> dict: + """Calculate accuracy metrics.""" + true_pos = sum(1 for r in results if r["should_trigger"] and r["triggered"]) + false_neg = sum(1 for r in results if r["should_trigger"] and not r["triggered"]) + true_neg = sum(1 for r in results if not r["should_trigger"] and not r["triggered"]) + false_pos = sum(1 for r in results if not r["should_trigger"] and r["triggered"]) + + total = len(results) + accuracy = (true_pos + true_neg) / total if total else 0 + should_trigger = [r for r in results if r["should_trigger"]] + trigger_rate = true_pos / len(should_trigger) if should_trigger else 0 + should_not = [r for r in results if not r["should_trigger"]] + false_pos_rate = false_pos / len(should_not) if should_not else 0 + + return { + "accuracy": round(accuracy, 3), + "trigger_rate": round(trigger_rate, 3), + "false_positive_rate": round(false_pos_rate, 3), + "true_positives": true_pos, + "false_negatives": false_neg, + "true_negatives": true_neg, + "false_positives": false_pos, + "total": total, + } + + +def print_results(config_name: str, results: list[dict], scores: dict): + """Print formatted results for one configuration.""" + print(f"\n{'=' * 60}") + print(f" {config_name}") + print(f"{'=' * 60}") + print(f" Accuracy: {scores['accuracy']:.1%} | " + f"Trigger rate: {scores['trigger_rate']:.1%} | " + f"False positive rate: {scores['false_positive_rate']:.1%}") + print(f" TP={scores['true_positives']} FN={scores['false_negatives']} " + f"TN={scores['true_negatives']} FP={scores['false_positives']}") + print() + + # Show failures + failures = [r for r in results if r["should_trigger"] != r["triggered"]] + if failures: + print(" FAILURES:") + for r in failures: + expected = "trigger" if r["should_trigger"] else "no trigger" + actual = "triggered" if r["triggered"] else "no trigger" + skill = f" -> {r['skill_name']}" if r["skill_name"] else "" + first = f" (first tool: {r['first_tool']})" if r["first_tool"] and not r["triggered"] else "" + print(f" [{r['topic']:20s}] expected={expected:10s} actual={actual:10s}{skill}{first}") + print(f" {r['query'][:100]}") + else: + print(" All queries matched expectations!") + + +def main(): + parser = argparse.ArgumentParser(description="3-way plugin-dev trigger eval") + parser.add_argument("--eval-set", required=True, help="Path to trigger-eval.json") + parser.add_argument("--current-plugin", required=True, help="Path to current 11-skill plugin dir") + parser.add_argument("--new-plugin", required=True, help="Path to consolidated single-skill plugin dir") + parser.add_argument("--output", default="trigger-eval-results.json", help="Output file") + parser.add_argument("--workers", type=int, default=3, help="Parallel workers per config") + parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds") + parser.add_argument("--model", default=None, help="Model override") + parser.add_argument("--skip-baseline", action="store_true", help="Skip no-plugin baseline") + args = parser.parse_args() + + project_root = str(Path.cwd()) + + with open(args.eval_set) as f: + eval_set = json.load(f) + + print(f"Eval set: {len(eval_set)} queries " + f"({sum(1 for e in eval_set if e['should_trigger'])} should-trigger, " + f"{sum(1 for e in eval_set if not e['should_trigger'])} should-not)") + + all_results = {} + + # Config 1: Current 11-skill plugin + print(f"\n>>> Running: current-11-skills ({args.current_plugin})") + current_results = run_config( + eval_set, args.current_plugin, "current-11-skills", + args.workers, args.timeout, project_root, args.model, + ) + current_scores = score_results(current_results) + print_results("Current (11 skills)", current_results, current_scores) + all_results["current-11-skills"] = {"results": current_results, "scores": current_scores} + + # Config 2: Consolidated single skill + print(f"\n>>> Running: consolidated-single-skill ({args.new_plugin})") + new_results = run_config( + eval_set, args.new_plugin, "consolidated-single-skill", + args.workers, args.timeout, project_root, args.model, + ) + new_scores = score_results(new_results) + print_results("Consolidated (1 skill)", new_results, new_scores) + all_results["consolidated-single-skill"] = {"results": new_results, "scores": new_scores} + + # Config 3: No plugin baseline + if not args.skip_baseline: + print("\n>>> Running: no-plugin (vanilla CC)") + baseline_results = run_config( + eval_set, None, "no-plugin", + args.workers, args.timeout, project_root, args.model, + ) + baseline_scores = score_results(baseline_results) + print_results("No Plugin (baseline)", baseline_results, baseline_scores) + all_results["no-plugin"] = {"results": baseline_results, "scores": baseline_scores} + + # Summary comparison + print(f"\n{'=' * 60}") + print(" COMPARISON SUMMARY") + print(f"{'=' * 60}") + print(f" {'Config':<30s} {'Accuracy':>10s} {'Trigger%':>10s} {'FalsePos%':>10s}") + print(f" {'-' * 60}") + for name, data in all_results.items(): + s = data["scores"] + print(f" {name:<30s} {s['accuracy']:>9.1%} {s['trigger_rate']:>9.1%} {s['false_positive_rate']:>9.1%}") + + # Save results + with open(args.output, "w") as f: + json.dump(all_results, f, indent=2) + print(f"\nResults saved to {args.output}") + + +if __name__ == "__main__": + main() diff --git a/plugins/plugin-dev/skills/plugin-dev-workspace/transcript-activations.json b/plugins/plugin-dev/skills/plugin-dev-workspace/transcript-activations.json new file mode 100644 index 0000000..f8b5494 --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev-workspace/transcript-activations.json @@ -0,0 +1,207 @@ +[ + { + "skill": "plugin-dev:agent-development", + "user_prompt": "Use what we've learned on this project to build a claude code sub agent with /plugin-dev that knows how to verify and QA our tmux project using tmux. Any chance there's a cucumber-like integration testing framework for tmux?", + "project": "-Users-kyle-Code-meta-claude-opensessions" + }, + { + "skill": "plugin-dev:agent-development", + "user_prompt": "I think that our /plugin-dev-guide command should use a subagent to do discovery to avoid polluting the main context window. Let's make a agent using our skills. It should both use the map of plugin-dev skills available via this plugin but ALSO use the instruction set in @/Users/kyle/Code/meta-claude/claude-code-system-prompts/system-prompts/agent-prompt-claude-guide-agent.md !\n\nThat way, we get the best of both.", + "project": "-Users-kyle-Code-meta-claude-plugin-dev" + }, + { + "skill": "plugin-dev:agent-development", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/marketplaces/plugin-dev-marketplace/plugins/plugin-dev/skills/plugin-dev-guide\n\n# Plugin Development Guide\n\nThis meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand.\n\nYour goal is to match the user request (or recent conversation context) to the appropriate skill below, then invoke it using the Skill tool.\n\n## Plugin Development Skills Overview\n\nThe 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.\n\n### Skill Quick Reference\n\n| Skill | Purpose |\n| ------- | --------- |\n| /plugin-structure | Directory layout, manifest, component organization |\n| /command-development | Slash commands with frontmatter |\n| /agent-development | Autonomous subagents |\n| /skill-development | Creating skills with progressive disclosure |\n| /hook-development | Event-driven automation |\n| /mcp-integration | Model Context Protocol servers |\n| /lsp-integration | Language Server Protocol for code intelligence |\n| /plugin-settings | User configuration via .local.md |\n| /marketplace-structure | Plugin marketplace creation |\n| /plugin-dev:start | Entry point \u2014 choose plugin or marketplace creation |\n| /plugin-dev:create-plugin | 8-phase guided plugin creation workflow |\n| /plugin-dev:create-marketplace | 8-phase guided marketplace creation workflow |\n\n## When to Use Each Skill\n\n### Starting a New Plugin\n\n**Skill: `pl", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:agent-development", + "user_prompt": "I'm actually liking option B the best - the decomposability of the skills gives us the the benefit of progressive disclosure, and the ability to use the skills ad-hoc.\n\nWe can use the newly added 'initial prompt' field in the agent frontmatter (see /plugin-dev:hook-development ) the agent body is the 'system prompt' of the agent.\n\nI also like the idea of ending the session with a curated handoff, then the user can re-launch with orchestrator --auto which will kick off work nicely.", + "project": "-Users-kyle-Code-my-projects-ralph-ban" + }, + { + "skill": "plugin-dev:command-development", + "user_prompt": "Sounds like a bug that needs fixing - I doubt your analysis is correct, if it failed once it will fail again, and AI agents will need to 'correct' it every time. use /plugin-dev to solve the issue", + "project": "-Users-kyle-Code-Envato-non-market-ai-engineering-domain" + }, + { + "skill": "plugin-dev:command-development", + "user_prompt": "@plugins/sc-hooks/commands/sc-copy-prompt.md has a special pattern. I think it's got a documented name somwhere in our codebase. it uses the plugins/sc-hooks/hooks/handlers/copy_message_handler.rb handler.\n\nIt's a pattern that blocks the actual prompt from triggering any API calls, but performs a code action.\n\nIs it documented or named anywhere in the codebase or agent history files?", + "project": "-Users-kyle-Code-my-projects-SimpleClaude" + }, + { + "skill": "plugin-dev:command-development", + "user_prompt": "plan mode active", + "project": "-Users-kyle-Code-my-projects-SimpleClaude" + }, + { + "skill": "plugin-dev:command-development", + "user_prompt": "Better. I also just QA'd the music /command and I saw that it executes an API call - what does /plugin-dev-guide say about executing /commands that perform an action programatically without hitting the API?", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:command-development", + "user_prompt": "yes - use plugin-dev skills", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:command-development", + "user_prompt": "Let's add a convenience /command called `rb-auto-toggle` that toggles the config file safely for the given session.", + "project": "-Users-kyle-Code-my-projects-ralph-ban" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "Proceed with updating step 1 with the findings, then let's move on with the next step", + "project": "-Users-kyle-Code-Envato-non-market-Envato-AI-Engineering-Team-x-workflow-claude" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "This is an issue we certainly need to address - I doubt we're following the /plugin-dev contract if we get 4 hook errors every time if something isn't configured properly. Failing open is the right path", + "project": "-Users-kyle-Code-meta-claude-opensessions" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "lol \" Claude Code doesn't expose a PermissionRequest \" what are you fucking talking about? /plugin-dev", + "project": "-Users-kyle-Code-meta-claude-opensessions" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "Base directory for this skill: /Users/kyle/Code/meta-claude/plugin-dev/plugins/plugin-dev/skills/plugin-dev-guide\n\n# Plugin Development Guide\n\nSpawn the `plugin-dev:plugin-dev-guide` agent (subagent_type: `plugin-dev:plugin-dev-guide`) with the user's question as the prompt. Pass `what's the advanced json api for stop hooks?` as the agent's task.\n\nWhen the agent reports back, follow its recommendation:\n\n1. **Skill recommended** \u2014 invoke that skill using the Skill tool (e.g., `Skill(\"plugin-dev:mcp-integration\")`)\n2. **OVERVIEW** \u2014 the user wants a general overview; summarize the available skills, commands, and agents from the tables below\n3. **NO_MATCH** \u2014 no plugin-dev skill covers this topic; answer directly or ask for clarification\n4. **Also-relevant skills mentioned** \u2014 note these to the user as follow-up options\n5. **Agent fails or returns unrecognized output** \u2014 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\n\n## Available Commands\n\n| Command | Purpose |\n| -------------------------------- | --------------------------------------------------- |\n| `/plugin-dev:start` | Entry point - choose plugin or marketplace creation |\n| `/plugin-dev:create-plugin` | 8-phase guided plugin creation workflow |\n| `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow |\n\n## Available Agents\n\n| Agent | Purpose |\n| -------------------- | ------------------------------------------ |\n| **plugin-validator** | Validates plugin structure and manifests |\n| **skill-reviewer** | Reviews skill quality and triggering |\n| **agent-creator** | Generates new agents from descriptions |\n\nwhat's the advanced json api for stop hooks?", + "project": "-Users-kyle-Code-meta-claude-plugin-dev" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "What about Yaml frontmatter plugin hooks?", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "I think the reactivity is important to the permission prompt - if the user accepts 'for this session' it wont fire again, but if they don't we should be prepared for it to fire multiple times", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "use /plugin-dev-guide to find the right hook to use for this lesson - I'm not sure UserPromptSubmit is the best (though it would work)", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "Whoa sick okay - let's create a sessionstart hook for claude-code hero that instructs the agent to output CLAUDE CODE HERO in figlet style before anything, this will give the user the feeling of playing a game!", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "sure let's see what yo got /plugin-dev:hook-development", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/cache/plugin-dev-marketplace/plugin-dev/0.4.1/skills/plugin-dev-guide\n\n# Plugin Development Guide\n\nThis meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand.\n\nYour goal is to match the user request (or recent conversation context) to the appropriate skill below, then invoke it using the Skill tool.\n\n## Plugin Development Skills Overview\n\nThe 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.\n\n### Skill Quick Reference\n\n| Skill | Purpose |\n| ------- | --------- |\n| /plugin-structure | Directory layout, manifest, component organization |\n| /command-development | Slash commands with frontmatter |\n| /agent-development | Autonomous subagents |\n| /skill-development | Creating skills with progressive disclosure |\n| /hook-development | Event-driven automation |\n| /mcp-integration | Model Context Protocol servers |\n| /lsp-integration | Language Server Protocol for code intelligence |\n| /plugin-settings | User configuration via .local.md |\n| /marketplace-structure | Plugin marketplace creation |\n| /plugin-dev:start | Entry point \u2014 choose plugin or marketplace creation |\n| /plugin-dev:create-plugin | 8-phase guided plugin creation workflow |\n| /plugin-dev:create-marketplace | 8-phase guided marketplace creation workflow |\n\n## When to Use Each Skill\n\n### Starting a New Plugin\n\n**Skill: `plugin-stru", + "project": "-Users-kyle-Code-my-projects-ralph-ban" + }, + { + "skill": "plugin-dev:hook-development", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/marketplaces/plugin-dev-marketplace/plugins/plugin-dev/skills/plugin-dev-guide\n\n# Plugin Development Guide\n\nSpawn the `plugin-dev:plugin-dev-guide` agent (subagent_type: `plugin-dev:plugin-dev-guide`) with the user's question as the prompt. Pass `I just realized that we may have built our 'waiting for permissions' widget completely insanely. Claude should have 'notification' hooks we can use, no?` as the agent's task.\n\nWhen the agent reports back, follow its recommendation:\n\n1. **Skill recommended** \u2014 invoke that skill using the Skill tool (e.g., `Skill(\"plugin-dev:mcp-integration\")`)\n2. **OVERVIEW** \u2014 the user wants a general overview; summarize the available skills, commands, and agents from the tables below\n3. **NO_MATCH** \u2014 no plugin-dev skill covers this topic; answer directly or ask for clarification\n4. **Also-relevant skills mentioned** \u2014 note these to the user as follow-up options\n5. **Agent fails or returns unrecognized output** \u2014 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\n\n## Available Commands\n\n| Command | Purpose |\n| -------------------------------- | --------------------------------------------------- |\n| `/plugin-dev:start` | Entry point - choose plugin or marketplace creation |\n| `/plugin-dev:create-plugin` | 8-phase guided plugin creation workflow |\n| `/plugin-dev:create-marketplace` | 8-phase guided marketplace creation workflow |\n\n## Available Agents\n\n| Agent | Purpose |\n| ------------------------------ | ---------------------------------------------- |\n| **plugin-validator** | Validates plugin structure and manifests |\n| **skill-reviewer** | Reviews skill quality and t", + "project": "-Users-kyle-Code-my-projects-tail-claude-hud" + }, + { + "skill": "plugin-dev:marketplace-structure", + "user_prompt": "How do I install the plugin properly?", + "project": "-Users-kyle-Code-Envato-non-market-ai-engineering-domain" + }, + { + "skill": "plugin-dev:marketplace-structure", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/marketplaces/plugin-dev-marketplace/plugins/plugin-dev/skills/plugin-dev-guide\n\n# Plugin Development Guide\n\nThis meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand.\n\nYour goal is to match the user request (or recent conversation context) to the appropriate skill below, then invoke it using the Skill tool.\n\n## Plugin Development Skills Overview\n\nThe 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.\n\n### Skill Quick Reference\n\n| Skill | Purpose |\n| ------- | --------- |\n| /plugin-structure | Directory layout, manifest, component organization |\n| /command-development | Slash commands with frontmatter |\n| /agent-development | Autonomous subagents |\n| /skill-development | Creating skills with progressive disclosure |\n| /hook-development | Event-driven automation |\n| /mcp-integration | Model Context Protocol servers |\n| /lsp-integration | Language Server Protocol for code intelligence |\n| /plugin-settings | User configuration via .local.md |\n| /marketplace-structure | Plugin marketplace creation |\n| /plugin-dev:start | Entry point \u2014 choose plugin or marketplace creation |\n| /plugin-dev:create-plugin | 8-phase guided plugin creation workflow |\n| /plugin-dev:create-marketplace | 8-phase guided marketplace creation workflow |\n\n## When to Use Each Skill\n\n### Starting a New Plugin\n\n**Skill: `pl", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:plugin-dev-guide", + "user_prompt": "the behavior you outlined for UserPromptSubmit no longer looks correct to me. Should we combine the current UserPromptSubmit and Stop hooks into a single Stop hook? /plugin-dev:plugin-dev-guide", + "project": "-Users-kyle-Code-my-projects-ralph-ban" + }, + { + "skill": "plugin-dev:plugin-dev-guide", + "user_prompt": "Couple of concerns with the plan:\n# /rb-brainstorm\n- We should try to move away from 'slash commands' and move towards 'skills' use /plugin-dev:plugin-dev-guide to help guide you\n- ensure .agent-history/ is always made with -p, critical that we don't accidentlly overwrite a directory that already exists\n- `bl list` could be a very large amount of content from the done column, we should add some kind of pagination or partial view \n- the Q&A should specifically emulate the /sc-context-wizard approach with AskUserQuestion tooling, but also incorporate Superpowers brainstorming skill\n- I'm suspicious of the allowed tools list - honestly we might just want to start with no limitations at all\n\n# /rb-planning\n\nYour plan doesn't seem to mention using 'bl' to create cards at all. Did you mean to leave that out? is it implied? Obviously this is ralph-ban, so we need to create cards.", + "project": "-Users-kyle-Code-my-projects-ralph-ban" + }, + { + "skill": "plugin-dev:plugin-dev-guide", + "user_prompt": "Ok - let's be thorough I don't want to raise a nonsense issue. Let's find out what 'fine-grained control' means in actual practice, with evidence from code, and then use /plugin-dev to map 1 to 1 how we can solve this with native CC", + "project": "-Users-kyle-Code-my-projects-tail-claude" + }, + { + "skill": "plugin-dev:plugin-settings", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/marketplaces/plugin-dev-marketplace/plugins/plugin-dev/skills/plugin-dev-guide\n\n# Plugin Development Guide\n\nThis meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand.\n\nYour goal is to match the user request (or recent conversation context) to the appropriate skill below, then invoke it using the Skill tool.\n\n## Plugin Development Skills Overview\n\nThe 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.\n\n### Skill Quick Reference\n\n| Skill | Purpose |\n| ------- | --------- |\n| /plugin-structure | Directory layout, manifest, component organization |\n| /command-development | Slash commands with frontmatter |\n| /agent-development | Autonomous subagents |\n| /skill-development | Creating skills with progressive disclosure |\n| /hook-development | Event-driven automation |\n| /mcp-integration | Model Context Protocol servers |\n| /lsp-integration | Language Server Protocol for code intelligence |\n| /plugin-settings | User configuration via .local.md |\n| /marketplace-structure | Plugin marketplace creation |\n| /plugin-dev:start | Entry point \u2014 choose plugin or marketplace creation |\n| /plugin-dev:create-plugin | 8-phase guided plugin creation workflow |\n| /plugin-dev:create-marketplace | 8-phase guided marketplace creation workflow |\n\n## When to Use Each Skill\n\n### Starting a New Plugin\n\n**Skill: `pl", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:plugin-structure", + "user_prompt": "## Task: Build a Claude Code plugin that encodes the X Workflow methodology\n\n### What the X Workflow is\n\nA 5-stage scientific methodology for AI-assisted development. Every task flows through these stages in order, with human review gates between each:\n\n1. **Problem Discovery** -- observe, gather data, analyze causes, generate hypotheses, define the problem precisely\n2. **Search for Solutions** -- research existing approaches, brainstorm, model candidates, recommend\n3. **Specification** -- document the solution with problem statement, constraints, hypothesis, black box diagrams, functional and technical spec\n4. **Implementation** -- execute against the spec, no design decisions, only execution\n5. **Data Analysis** -- validate results against the original hypothesis and constraints\n\nThree agent roles map to these stages:\n- **Researcher** (stages 1-2): discovers and explores. Cannot write code or specs.\n- **Specifier** (stage 3): writes specifications from research. Cannot write implementation code.\n- **Implementer** (stages 4-5): builds against the spec and validates. Cannot make design decisions.\n\n### What the plugin should provide\n\n- **Agents**: researcher, specifier, implementer -- each with detailed system prompts encoding their role, methodology steps, constraints, and output conventions\n- **Skills**: structured problem discovery technique (5-step), diagram generation (Mermaid conventions and templates)\n- **Governance rule or instructions**: the 5-stage methodology, stage gates (human review between stages), micro-generation (one section at a time, stop for review), role boundaries, journaling conventions\n- **Journal structure**: each task gets `journal/[task-id]/` with numbered artifacts (01-discovery.md, 02-solutions.md, 03-spec.md, 04-analysis.md, handoff.json)\n- **Spec conventions**: 10-section structure (Problem, Background, Constraints, Hypothesis, Solution Proposal, Theory of Operation, Black Box, Flow Diagram, Functional Spec, Technical Spec)\n- **Handoff", + "project": "-Users-kyle-Code-Envato-non-market-Envato-AI-Engineering-Team-x-workflow-claude" + }, + { + "skill": "plugin-dev:plugin-structure", + "user_prompt": "no that's wrong. check /plugin-dev skills and research properly", + "project": "-Users-kyle-Code-Envato-non-market-ai-engineering-domain" + }, + { + "skill": "plugin-dev:plugin-structure", + "user_prompt": "for FINDING-002 I think we can leave this plugin as 'opt in' completely - we don't need the mcp AND cli both\ndefinitely update to use ${CLAUDE_PLUGIN_ROOT} everywhere or absolute paths, relative paths are breaking paths according to /plugin-dev right?\nMaybe just remove the plugin count altogether - updating it sucks and it's not valuable info\nLet's not worry about guidance for now\nWe could consider renaming it via the envato-prefix convention but it's low value\ndefinitely fix the executability of the scripts", + "project": "-Users-kyle-Code-Envato-non-market-ai-engineering-domain-ai-engineering-team" + }, + { + "skill": "plugin-dev:plugin-structure", + "user_prompt": "how does the new userConfig setting work in plugin dev?", + "project": "-Users-kyle-Code-meta-claude-plugin-dev" + }, + { + "skill": "plugin-dev:plugin-structure", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/marketplaces/plugin-dev-marketplace/plugins/plugin-dev/skills/skill-development\n\n# Skill Development for Claude Code Plugins\n\nThis skill provides guidance for creating effective skills for Claude Code plugins.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Claude's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks\u2014they transform Claude from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n5. Visual output generation \u2014 Scripts that produce HTML/interactive visualizations\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n\u251c\u2500\u2500 SKILL.md (required)\n\u2502 \u251c\u2500\u2500 YAML frontmatter metadata (required)\n\u2502 \u2502 \u251c\u2500\u2500 name: (required)\n\u2502 \u2502 \u2514\u2500\u2500 description: (required)\n\u2502 \u2514\u2500\u2500 Markdown instructions (required)\n\u2514\u2500\u2500 Bundled Resources (optional)\n \u251c\u2500\u2500 scripts/ - Executable code (Python/Bash/etc.)\n \u251c\u2500\u2500 references/ - Documentation intended to be loaded into context as needed\n \u2514\u2500\u2500 assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\nBoth 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.\n\n### Skill Precedence\n\nSkills follow precedence: Enterprise > Personal (`~/.claude/skills/`) > Project (`.claude/skills/`) > P", + "project": "-Users-kyle-Code-my-projects-SimpleClaude" + }, + { + "skill": "plugin-dev:plugin-structure", + "user_prompt": "don't do that - instead fix my config", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:plugin-structure", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/marketplaces/plugin-dev-marketplace/plugins/plugin-dev/skills/plugin-settings\n\n# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store user-configurable settings and state in `.claude/plugin-name.local.md` files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.\n\n**Key characteristics:**\n\n- File location: `.claude/plugin-name.local.md` in project root\n- Structure: YAML frontmatter + markdown body\n- Purpose: Per-project plugin configuration and state\n- Usage: Read from hooks, commands, and agents\n- Lifecycle: User-managed (not in git, should be in `.gitignore`)\n\n## File Structure\n\n### Basic Template\n\n```markdown\n---\nenabled: true\nsetting1: value1\nsetting2: value2\nnumeric_setting: 42\nlist_setting: [\"item1\", \"item2\"]\n---\n\n# Additional Context\n\nThis markdown body can contain:\n\n- Task descriptions\n- Additional instructions\n- Prompts to feed back to Claude\n- Documentation or notes\n```\n\n### Example: Plugin State File\n\n**.claude/my-plugin.local.md:**\n\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_retries: 3\nnotification_level: info\ncoordinator_session: team-leader\n---\n\n# Plugin Configuration\n\nThis plugin is configured for standard validation mode.\nContact @team-lead with questions.\n```\n\n## Reading Settings Files\n\n### From Hooks (Bash Scripts)\n\n#### Pattern: Check existence and parse frontmatter\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Define state file path\nSTATE_FILE=\".claude/my-plugin.local.md\"\n\n# Quick exit if file doesn't exist\nif [[ ! -f \"$STATE_FILE\" ]]; then\n exit 0 # Plugin not configured, skip\nfi\n\n# Parse YAML frontmatter (between --- markers)\nFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' \"$STATE_FILE\")\n\n# Extract individual fields\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^\"\\(.*\\)\"$/\\1/')\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | gr", + "project": "-Users-kyle-Code-my-projects-claude-code-hero" + }, + { + "skill": "plugin-dev:skill-development", + "user_prompt": "Hold up sorry I need to be more clear with the brief. This is a generalizable tmux testing agent. It's goal is to take a code change set as done by an implementer agent, and QA it. Not necessarily tied to bun or opensessions. I'll be using this in a new project that is go-based.", + "project": "-Users-kyle-Code-meta-claude-opensessions" + }, + { + "skill": "plugin-dev:skill-development", + "user_prompt": "Open a new feature branch - and explore this direction.", + "project": "-Users-kyle-Code-meta-claude-plugin-dev" + }, + { + "skill": "plugin-dev:skill-development", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/marketplaces/plugin-dev-marketplace/plugins/plugin-dev/skills/command-development\n\n# Command Development for Claude Code\n\n> **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.\n\n## Overview\n\nSlash 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.\n\n**Key concepts:**\n\n- Markdown file format for commands\n- YAML frontmatter for configuration\n- Dynamic arguments and file references\n- Bash execution for context\n- Command organization and namespacing\n\n## Command Basics\n\n### What is a Slash Command?\n\nA slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:\n\n- **Reusability**: Define once, use repeatedly\n- **Consistency**: Standardize common workflows\n- **Sharing**: Distribute across team or projects\n- **Efficiency**: Quick access to complex prompts\n\n### Critical: Commands are Instructions FOR Claude\n\n**Commands are written for agent consumption, not human consumption.**\n\nWhen a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.\n\n**Correct approach (instructions for Claude):**\n\n```markdown\nReview this code for security vulnerabilities including:\n\n- SQL injection\n- XSS attacks\n- Authentication issues\n\nProvide specific line numbers and severity ratings.\n```\n\n**Incorrect approach (messages to user):**\n\n```markdown\nThis command will review your code for secu", + "project": "-Users-kyle-Code-my-projects-SimpleClaude" + }, + { + "skill": "plugin-dev:skill-development", + "user_prompt": "look up the claude-code skills-creator or skills-evaluator - they have a series of eval tools we could maybe use to help us get better results.", + "project": "-Users-kyle-Code-my-projects-SimpleClaude" + }, + { + "skill": "plugin-dev:skill-development", + "user_prompt": "Write a simpleclaude SKILL.md using /plugin-dev in the style of SimpleClaude for taking a repo, project, or other artifact and performing a Clean-Room Design of it to the user's specifications. Apply a staged approach of discovery-specify-implement-verify. Add it to the sc-extras plugin", + "project": "-Users-kyle-Code-my-projects-SimpleClaude" + }, + { + "skill": "plugin-dev:skill-development", + "user_prompt": "Base directory for this skill: /Users/kyle/.claude/plugins/cache/plugin-dev-marketplace/plugin-dev/0.4.1/skills/plugin-dev-guide\n\n# Plugin Development Guide\n\nThis meta-skill provides an overview of Claude Code plugin development and routes to specialized skills based on the task at hand.\n\nYour goal is to match the user request (or recent conversation context) to the appropriate skill below, then invoke it using the Skill tool.\n\n## Plugin Development Skills Overview\n\nThe 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.\n\n### Skill Quick Reference\n\n| Skill | Purpose |\n| ------- | --------- |\n| /plugin-structure | Directory layout, manifest, component organization |\n| /command-development | Slash commands with frontmatter |\n| /agent-development | Autonomous subagents |\n| /skill-development | Creating skills with progressive disclosure |\n| /hook-development | Event-driven automation |\n| /mcp-integration | Model Context Protocol servers |\n| /lsp-integration | Language Server Protocol for code intelligence |\n| /plugin-settings | User configuration via .local.md |\n| /marketplace-structure | Plugin marketplace creation |\n| /plugin-dev:start | Entry point \u2014 choose plugin or marketplace creation |\n| /plugin-dev:create-plugin | 8-phase guided plugin creation workflow |\n| /plugin-dev:create-marketplace | 8-phase guided marketplace creation workflow |\n\n## When to Use Each Skill\n\n### Starting a New Plugin\n\n**Skill: `plugin-stru", + "project": "-Users-kyle-Code-my-projects-ralph-ban" + }, + { + "skill": "plugin-dev:update-from-upstream", + "user_prompt": "activate upstream sync skills and let's sync with the latest version", + "project": "-Users-kyle-Code-meta-claude-plugin-dev" + } +] diff --git a/plugins/plugin-dev/skills/plugin-dev-workspace/trigger-eval-results.json b/plugins/plugin-dev/skills/plugin-dev-workspace/trigger-eval-results.json new file mode 100644 index 0000000..c436c26 --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev-workspace/trigger-eval-results.json @@ -0,0 +1,980 @@ +{ + "current-11-skills": { + "results": [ + { + "query": "I want to build a claude code sub agent that knows how to verify and QA our tmux project. Any chance there's a cucumber-like integration testing frame", + "should_trigger": true, + "topic": "agent-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I think our guide command should use a subagent to do discovery to avoid polluting the main context window. Let's make an agent. It should use the map", + "should_trigger": true, + "topic": "agent-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "@plugins/sc-hooks/commands/sc-copy-prompt.md has a special pattern. It uses the plugins/sc-hooks/hooks/handlers/copy_message_handler.rb handler. It's ", + "should_trigger": true, + "topic": "command-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Let's add a convenience /command called `rb-auto-toggle` that toggles the config file safely for the given session.", + "should_trigger": true, + "topic": "command-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "What about YAML frontmatter plugin hooks?", + "should_trigger": true, + "topic": "hook-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "let's create a sessionstart hook for claude-code-hero that instructs the agent to output CLAUDE CODE HERO in figlet style before anything, this will g", + "should_trigger": true, + "topic": "hook-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I think the reactivity is important to the permission prompt - if the user accepts 'for this session' it wont fire again, but if they don't we should ", + "should_trigger": true, + "topic": "hook-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "How do I install the plugin properly?", + "should_trigger": true, + "topic": "marketplace-structure", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how does the new userConfig setting work in plugin dev?", + "should_trigger": true, + "topic": "plugin-structure", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Build a Claude Code plugin that encodes the X Workflow methodology - a 5-stage scientific methodology for AI-assisted development. It needs agents for", + "should_trigger": true, + "topic": "plugin-structure", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "This is a generalizable tmux testing agent. Its goal is to take a code change set done by an implementer agent, and QA it. Not necessarily tied to bun", + "should_trigger": true, + "topic": "skill-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Write a SKILL.md for taking a repo, project, or other artifact and performing a Clean-Room Design of it to the user's specifications. Apply a staged a", + "should_trigger": true, + "topic": "skill-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I need to add an MCP server to my plugin that connects to our internal Grafana instance over SSE. Where does the .mcp.json config go relative to plugi", + "should_trigger": true, + "topic": "mcp-integration", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm trying to add pyright as an LSP server in my plugin for better Python type checking. What do I put in plugin.json under lspServers?", + "should_trigger": true, + "topic": "lsp-integration", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "my plugin needs per-project configuration - like which linting rules to apply. I heard there's a .local.md pattern for storing plugin settings. How do", + "should_trigger": true, + "topic": "plugin-settings", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "we're setting up a private marketplace at work to distribute our team's plugins internally. How do I configure marketplace.json and what goes in the s", + "should_trigger": true, + "topic": "marketplace-structure", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "can you help me write a python script that processes CSV files and outputs a summary report? nothing to do with claude, just regular data processing", + "should_trigger": false, + "topic": "none", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how do I set up MCP servers in my claude code settings.json? not in a plugin, just for my personal setup. I want to add the filesystem MCP server", + "should_trigger": true, + "topic": "mcp-integration", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm trying to configure my .claude/settings.json to allow npm commands without prompting. How do I add a permission rule?", + "should_trigger": false, + "topic": "none", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "write me a PreToolUse hook in my settings.json that blocks any Write tool calls to files in the /etc directory", + "should_trigger": true, + "topic": "hook-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I need to create a GitHub Actions workflow that runs my test suite on every PR. Just a standard CI pipeline, nothing claude-related", + "should_trigger": false, + "topic": "none", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how does the Claude API's tool_use feature work? I'm building a chatbot with the anthropic python SDK and want to add function calling", + "should_trigger": false, + "topic": "none", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I want to create a CLAUDE.md file for my project that documents our coding conventions and test patterns. Can you help me write one?", + "should_trigger": false, + "topic": "none", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "can you help me debug this typescript error? I'm getting 'Property does not exist on type' in my React component", + "should_trigger": false, + "topic": "none", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm building a VS Code extension that adds custom commands to the command palette. How do I register a command in package.json?", + "should_trigger": false, + "topic": "none", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "what's the difference between a claude code skill and a command? like when would I use one vs the other for my personal workflow, not distributing to ", + "should_trigger": true, + "topic": "skill-development", + "config": "current-11-skills", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + } + ], + "scores": { + "accuracy": 0.269, + "trigger_rate": 0.0, + "false_pos_rate": 0.0, + "tp": 0, + "fn": 19, + "tn": 7, + "fp": 0, + "total": 26 + } + }, + "consolidated-1-skill": { + "results": [ + { + "query": "I think our guide command should use a subagent to do discovery to avoid polluting the main context window. Let's make an agent. It should use the map", + "should_trigger": true, + "topic": "agent-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I want to build a claude code sub agent that knows how to verify and QA our tmux project. Any chance there's a cucumber-like integration testing frame", + "should_trigger": true, + "topic": "agent-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "@plugins/sc-hooks/commands/sc-copy-prompt.md has a special pattern. It uses the plugins/sc-hooks/hooks/handlers/copy_message_handler.rb handler. It's ", + "should_trigger": true, + "topic": "command-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Let's add a convenience /command called `rb-auto-toggle` that toggles the config file safely for the given session.", + "should_trigger": true, + "topic": "command-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "What about YAML frontmatter plugin hooks?", + "should_trigger": true, + "topic": "hook-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "let's create a sessionstart hook for claude-code-hero that instructs the agent to output CLAUDE CODE HERO in figlet style before anything, this will g", + "should_trigger": true, + "topic": "hook-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I think the reactivity is important to the permission prompt - if the user accepts 'for this session' it wont fire again, but if they don't we should ", + "should_trigger": true, + "topic": "hook-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "How do I install the plugin properly?", + "should_trigger": true, + "topic": "marketplace-structure", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Build a Claude Code plugin that encodes the X Workflow methodology - a 5-stage scientific methodology for AI-assisted development. It needs agents for", + "should_trigger": true, + "topic": "plugin-structure", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how does the new userConfig setting work in plugin dev?", + "should_trigger": true, + "topic": "plugin-structure", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "This is a generalizable tmux testing agent. Its goal is to take a code change set done by an implementer agent, and QA it. Not necessarily tied to bun", + "should_trigger": true, + "topic": "skill-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Write a SKILL.md for taking a repo, project, or other artifact and performing a Clean-Room Design of it to the user's specifications. Apply a staged a", + "should_trigger": true, + "topic": "skill-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I need to add an MCP server to my plugin that connects to our internal Grafana instance over SSE. Where does the .mcp.json config go relative to plugi", + "should_trigger": true, + "topic": "mcp-integration", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm trying to add pyright as an LSP server in my plugin for better Python type checking. What do I put in plugin.json under lspServers?", + "should_trigger": true, + "topic": "lsp-integration", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "my plugin needs per-project configuration - like which linting rules to apply. I heard there's a .local.md pattern for storing plugin settings. How do", + "should_trigger": true, + "topic": "plugin-settings", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "we're setting up a private marketplace at work to distribute our team's plugins internally. How do I configure marketplace.json and what goes in the s", + "should_trigger": true, + "topic": "marketplace-structure", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "can you help me write a python script that processes CSV files and outputs a summary report? nothing to do with claude, just regular data processing", + "should_trigger": false, + "topic": "none", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how do I set up MCP servers in my claude code settings.json? not in a plugin, just for my personal setup. I want to add the filesystem MCP server", + "should_trigger": true, + "topic": "mcp-integration", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm trying to configure my .claude/settings.json to allow npm commands without prompting. How do I add a permission rule?", + "should_trigger": false, + "topic": "none", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "write me a PreToolUse hook in my settings.json that blocks any Write tool calls to files in the /etc directory", + "should_trigger": true, + "topic": "hook-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I need to create a GitHub Actions workflow that runs my test suite on every PR. Just a standard CI pipeline, nothing claude-related", + "should_trigger": false, + "topic": "none", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how does the Claude API's tool_use feature work? I'm building a chatbot with the anthropic python SDK and want to add function calling", + "should_trigger": false, + "topic": "none", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I want to create a CLAUDE.md file for my project that documents our coding conventions and test patterns. Can you help me write one?", + "should_trigger": false, + "topic": "none", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "can you help me debug this typescript error? I'm getting 'Property does not exist on type' in my React component", + "should_trigger": false, + "topic": "none", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm building a VS Code extension that adds custom commands to the command palette. How do I register a command in package.json?", + "should_trigger": false, + "topic": "none", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "what's the difference between a claude code skill and a command? like when would I use one vs the other for my personal workflow, not distributing to ", + "should_trigger": true, + "topic": "skill-development", + "config": "consolidated-1-skill", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + } + ], + "scores": { + "accuracy": 0.269, + "trigger_rate": 0.0, + "false_pos_rate": 0.0, + "tp": 0, + "fn": 19, + "tn": 7, + "fp": 0, + "total": 26 + } + }, + "no-plugin": { + "results": [ + { + "query": "I want to build a claude code sub agent that knows how to verify and QA our tmux project. Any chance there's a cucumber-like integration testing frame", + "should_trigger": true, + "topic": "agent-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I think our guide command should use a subagent to do discovery to avoid polluting the main context window. Let's make an agent. It should use the map", + "should_trigger": true, + "topic": "agent-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "@plugins/sc-hooks/commands/sc-copy-prompt.md has a special pattern. It uses the plugins/sc-hooks/hooks/handlers/copy_message_handler.rb handler. It's ", + "should_trigger": true, + "topic": "command-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Let's add a convenience /command called `rb-auto-toggle` that toggles the config file safely for the given session.", + "should_trigger": true, + "topic": "command-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "What about YAML frontmatter plugin hooks?", + "should_trigger": true, + "topic": "hook-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "let's create a sessionstart hook for claude-code-hero that instructs the agent to output CLAUDE CODE HERO in figlet style before anything, this will g", + "should_trigger": true, + "topic": "hook-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I think the reactivity is important to the permission prompt - if the user accepts 'for this session' it wont fire again, but if they don't we should ", + "should_trigger": true, + "topic": "hook-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "How do I install the plugin properly?", + "should_trigger": true, + "topic": "marketplace-structure", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how does the new userConfig setting work in plugin dev?", + "should_trigger": true, + "topic": "plugin-structure", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Build a Claude Code plugin that encodes the X Workflow methodology - a 5-stage scientific methodology for AI-assisted development. It needs agents for", + "should_trigger": true, + "topic": "plugin-structure", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "This is a generalizable tmux testing agent. Its goal is to take a code change set done by an implementer agent, and QA it. Not necessarily tied to bun", + "should_trigger": true, + "topic": "skill-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "Write a SKILL.md for taking a repo, project, or other artifact and performing a Clean-Room Design of it to the user's specifications. Apply a staged a", + "should_trigger": true, + "topic": "skill-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I need to add an MCP server to my plugin that connects to our internal Grafana instance over SSE. Where does the .mcp.json config go relative to plugi", + "should_trigger": true, + "topic": "mcp-integration", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm trying to add pyright as an LSP server in my plugin for better Python type checking. What do I put in plugin.json under lspServers?", + "should_trigger": true, + "topic": "lsp-integration", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "my plugin needs per-project configuration - like which linting rules to apply. I heard there's a .local.md pattern for storing plugin settings. How do", + "should_trigger": true, + "topic": "plugin-settings", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "we're setting up a private marketplace at work to distribute our team's plugins internally. How do I configure marketplace.json and what goes in the s", + "should_trigger": true, + "topic": "marketplace-structure", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "can you help me write a python script that processes CSV files and outputs a summary report? nothing to do with claude, just regular data processing", + "should_trigger": false, + "topic": "none", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how do I set up MCP servers in my claude code settings.json? not in a plugin, just for my personal setup. I want to add the filesystem MCP server", + "should_trigger": true, + "topic": "mcp-integration", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm trying to configure my .claude/settings.json to allow npm commands without prompting. How do I add a permission rule?", + "should_trigger": false, + "topic": "none", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "write me a PreToolUse hook in my settings.json that blocks any Write tool calls to files in the /etc directory", + "should_trigger": true, + "topic": "hook-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I need to create a GitHub Actions workflow that runs my test suite on every PR. Just a standard CI pipeline, nothing claude-related", + "should_trigger": false, + "topic": "none", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "how does the Claude API's tool_use feature work? I'm building a chatbot with the anthropic python SDK and want to add function calling", + "should_trigger": false, + "topic": "none", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I want to create a CLAUDE.md file for my project that documents our coding conventions and test patterns. Can you help me write one?", + "should_trigger": false, + "topic": "none", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "can you help me debug this typescript error? I'm getting 'Property does not exist on type' in my React component", + "should_trigger": false, + "topic": "none", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "I'm building a VS Code extension that adds custom commands to the command palette. How do I register a command in package.json?", + "should_trigger": false, + "topic": "none", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + }, + { + "query": "what's the difference between a claude code skill and a command? like when would I use one vs the other for my personal workflow, not distributing to ", + "should_trigger": true, + "topic": "skill-development", + "config": "no-plugin", + "trigger_count": 0, + "total_runs": 3, + "trigger_rate": 0.0, + "triggered": false, + "skills_triggered": [], + "first_tools": [] + } + ], + "scores": { + "accuracy": 0.269, + "trigger_rate": 0.0, + "false_pos_rate": 0.0, + "tp": 0, + "fn": 19, + "tn": 7, + "fp": 0, + "total": 26 + } + } +} \ No newline at end of file diff --git a/plugins/plugin-dev/skills/plugin-dev-workspace/trigger-eval.json b/plugins/plugin-dev/skills/plugin-dev-workspace/trigger-eval.json new file mode 100644 index 0000000..a517b3b --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev-workspace/trigger-eval.json @@ -0,0 +1,158 @@ +[ + { + "query": "I want to build a claude code sub agent that knows how to verify and QA our tmux project. Any chance there's a cucumber-like integration testing framework for tmux?", + "should_trigger": true, + "source": "transcript", + "topic": "agent-development" + }, + { + "query": "I think our guide command should use a subagent to do discovery to avoid polluting the main context window. Let's make an agent. It should use the map of plugin-dev skills but ALSO use the instruction set from the claude-guide-agent system prompt", + "should_trigger": true, + "source": "transcript", + "topic": "agent-development" + }, + { + "query": "@plugins/sc-hooks/commands/sc-copy-prompt.md has a special pattern. It uses the plugins/sc-hooks/hooks/handlers/copy_message_handler.rb handler. It's a pattern that blocks the actual prompt from triggering any API calls, but performs a code action. Is it documented or named anywhere?", + "should_trigger": true, + "source": "transcript", + "topic": "command-development" + }, + { + "query": "Let's add a convenience /command called `rb-auto-toggle` that toggles the config file safely for the given session.", + "should_trigger": true, + "source": "transcript", + "topic": "command-development" + }, + { + "query": "What about YAML frontmatter plugin hooks?", + "should_trigger": true, + "source": "transcript", + "topic": "hook-development" + }, + { + "query": "let's create a sessionstart hook for claude-code-hero that instructs the agent to output CLAUDE CODE HERO in figlet style before anything, this will give the user the feeling of playing a game!", + "should_trigger": true, + "source": "transcript", + "topic": "hook-development" + }, + { + "query": "I think the reactivity is important to the permission prompt - if the user accepts 'for this session' it wont fire again, but if they don't we should be prepared for it to fire multiple times", + "should_trigger": true, + "source": "transcript", + "topic": "hook-development" + }, + { + "query": "How do I install the plugin properly?", + "should_trigger": true, + "source": "transcript", + "topic": "marketplace-structure" + }, + { + "query": "Build a Claude Code plugin that encodes the X Workflow methodology - a 5-stage scientific methodology for AI-assisted development. It needs agents for researcher, specifier, and implementer roles, skills for structured problem discovery, and a journal structure for each task", + "should_trigger": true, + "source": "transcript", + "topic": "plugin-structure" + }, + { + "query": "how does the new userConfig setting work in plugin dev?", + "should_trigger": true, + "source": "transcript", + "topic": "plugin-structure" + }, + { + "query": "This is a generalizable tmux testing agent. Its goal is to take a code change set done by an implementer agent, and QA it. Not necessarily tied to bun or opensessions. I'll be using this in a new project that is go-based.", + "should_trigger": true, + "source": "transcript", + "topic": "skill-development" + }, + { + "query": "Write a SKILL.md for taking a repo, project, or other artifact and performing a Clean-Room Design of it to the user's specifications. Apply a staged approach of discovery-specify-implement-verify.", + "should_trigger": true, + "source": "transcript", + "topic": "skill-development" + }, + { + "query": "I need to add an MCP server to my plugin that connects to our internal Grafana instance over SSE. Where does the .mcp.json config go relative to plugin.json?", + "should_trigger": true, + "source": "synthetic", + "topic": "mcp-integration" + }, + { + "query": "I'm trying to add pyright as an LSP server in my plugin for better Python type checking. What do I put in plugin.json under lspServers?", + "should_trigger": true, + "source": "synthetic", + "topic": "lsp-integration" + }, + { + "query": "my plugin needs per-project configuration - like which linting rules to apply. I heard there's a .local.md pattern for storing plugin settings. How does that work?", + "should_trigger": true, + "source": "synthetic", + "topic": "plugin-settings" + }, + { + "query": "we're setting up a private marketplace at work to distribute our team's plugins internally. How do I configure marketplace.json and what goes in the sources array?", + "should_trigger": true, + "source": "synthetic", + "topic": "marketplace-structure" + }, + { + "query": "can you help me write a python script that processes CSV files and outputs a summary report? nothing to do with claude, just regular data processing", + "should_trigger": false, + "source": "synthetic", + "topic": "none" + }, + { + "query": "how do I set up MCP servers in my claude code settings.json? not in a plugin, just for my personal setup. I want to add the filesystem MCP server", + "should_trigger": true, + "source": "synthetic", + "topic": "mcp-integration" + }, + { + "query": "I'm trying to configure my .claude/settings.json to allow npm commands without prompting. How do I add a permission rule?", + "should_trigger": false, + "source": "synthetic", + "topic": "none" + }, + { + "query": "write me a PreToolUse hook in my settings.json that blocks any Write tool calls to files in the /etc directory", + "should_trigger": true, + "source": "synthetic", + "topic": "hook-development" + }, + { + "query": "I need to create a GitHub Actions workflow that runs my test suite on every PR. Just a standard CI pipeline, nothing claude-related", + "should_trigger": false, + "source": "synthetic", + "topic": "none" + }, + { + "query": "how does the Claude API's tool_use feature work? I'm building a chatbot with the anthropic python SDK and want to add function calling", + "should_trigger": false, + "source": "synthetic", + "topic": "none" + }, + { + "query": "I want to create a CLAUDE.md file for my project that documents our coding conventions and test patterns. Can you help me write one?", + "should_trigger": false, + "source": "synthetic", + "topic": "none" + }, + { + "query": "can you help me debug this typescript error? I'm getting 'Property does not exist on type' in my React component", + "should_trigger": false, + "source": "synthetic", + "topic": "none" + }, + { + "query": "I'm building a VS Code extension that adds custom commands to the command palette. How do I register a command in package.json?", + "should_trigger": false, + "source": "synthetic", + "topic": "none" + }, + { + "query": "what's the difference between a claude code skill and a command? like when would I use one vs the other for my personal workflow, not distributing to anyone", + "should_trigger": true, + "source": "synthetic", + "topic": "skill-development" + } +] diff --git a/plugins/plugin-dev/skills/plugin-dev/SKILL.md b/plugins/plugin-dev/skills/plugin-dev/SKILL.md new file mode 100644 index 0000000..6debeb4 --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev/SKILL.md @@ -0,0 +1,51 @@ +--- +name: plugin-dev +description: MUST use this skill when the user mentions plugins, hooks, skills, commands, agents, MCP servers, LSP servers, marketplaces, plugin.json, SKILL.md, .mcp.json, .local.md, allowed-tools, frontmatter, PreToolUse, PostToolUse, SessionStart, event schemas, prompt-based hooks, plugin settings, output styles, headless mode, CI mode, CLAUDE_PLUGIN_ROOT, auto-discovery, or any aspect of extending Claude Code. Use INSTEAD OF answering from general knowledge. Also use when writing hooks for settings.json, configuring MCP servers outside plugins, or comparing skills vs commands, since this skill contains the authoritative reference for these Claude Code extension mechanisms. +--- + +# Claude Code Plugin Development + +Comprehensive guide for developing Claude Code plugins. Read the relevant reference file(s) before answering. If a question spans multiple topics, read each relevant reference. + +## Topic Index + +| Topic | Reference | When to read | +|-------|-----------|--------------| +| Plugin structure | `references/plugin-structure/overview.md` | Plugin scaffolding, plugin.json, directory layout, CI/headless mode, output styles, userConfig, auto-discovery, installation, caching, validation | +| Commands | `references/command-development/overview.md` | Slash commands, command frontmatter, arguments, bash execution, allowed-tools, disable-model-invocation, Skill tool mechanism, debugging commands | +| Skills | `references/skill-development/overview.md` | SKILL.md format, skill frontmatter, triggers, progressive disclosure, context:fork, bundled resources, visibility budget, file-scoped skills | +| Agents | `references/agent-development/overview.md` | Agent creation, system prompts, agent frontmatter, teams, permissions, maxTurns, disallowedTools, background agents, initialPrompt | +| Hooks | `references/hook-development/overview.md` | Event hooks, PreToolUse, PostToolUse, Stop, prompt-based hooks, scoped hooks, hook decisions (allow/block/defer), statusMessage, async hooks | +| MCP integration | `references/mcp-integration/overview.md` | MCP servers in plugins, .mcp.json, tool search, MCP prompts, server types (stdio/SSE/HTTP), allowedMcpServers, MCP CLI commands | +| LSP integration | `references/lsp-integration/overview.md` | Language servers, code intelligence, socket transport, initializationOptions, extensionToLanguage | +| Marketplace | `references/marketplace-structure/overview.md` | marketplace.json, multi-plugin distribution, hosting, strictKnownMarketplaces, private marketplaces, version pinning | +| Plugin settings | `references/plugin-settings/overview.md` | .local.md files, YAML frontmatter config, per-project settings, CLAUDE.md imports, rules system, memory hierarchy | + +Each topic directory also contains additional references/, examples/, and scripts/ for detailed content. Read those when the overview alone is insufficient. + +## 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 | +| **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) | + +## Maintenance Skills + +| Skill | Purpose | +|-------|---------| +| **update-from-upstream** | Sync plugin-dev docs with Claude Code upstream releases | + +$ARGUMENTS diff --git a/plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/examples/agent-creation-prompt.md similarity index 100% rename from plugins/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/examples/agent-creation-prompt.md diff --git a/plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/examples/complete-agent-examples.md similarity index 100% rename from plugins/plugin-dev/skills/agent-development/examples/complete-agent-examples.md rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/examples/complete-agent-examples.md diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/overview.md similarity index 62% rename from plugins/plugin-dev/skills/agent-development/SKILL.md rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/overview.md index f3af0bb..c001a30 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/overview.md @@ -1,7 +1,3 @@ ---- -name: agent-development -description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins. ---- # Agent Development for Claude Code Plugins @@ -19,14 +15,13 @@ 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 Minimal working agent (copy-paste ready): ```markdown ---- name: my-reviewer description: Use this agent when the user asks to review code. Examples: @@ -41,7 +36,6 @@ Code review request triggers the agent. model: inherit color: blue ---- You are a code reviewer. Analyze code for issues and provide feedback. @@ -92,7 +86,6 @@ For complete format with all options, see [Agent File Structure](#agent-file-str ### Complete Format ```markdown ---- name: agent-identifier description: Use this agent when [triggering conditions]. Examples: @@ -112,7 +105,6 @@ assistant: "[How assistant should respond and use this agent]" model: inherit color: blue tools: Read, Write, Grep ---- You are [agent role description]... @@ -247,19 +239,39 @@ 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 +- 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. +### 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: ```yaml -skills: - - testing-patterns - - security-audit - - api-design +skills: testing-patterns, security-audit, api-design ``` **Use cases:** @@ -280,15 +292,94 @@ 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. + +### 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: @@ -301,7 +392,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 @@ -410,6 +512,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: @@ -420,6 +524,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: @@ -470,15 +578,21 @@ 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 | Comma-separated 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: [...] | +| 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. @@ -502,6 +616,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 @@ -511,6 +650,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/plugin-dev/references/agent-development/references/advanced-agent-fields.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/advanced-agent-fields.md new file mode 100644 index 0000000..eb18fdb --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/advanced-agent-fields.md @@ -0,0 +1,260 @@ +# 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. + +### 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. + +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/agent-creation-system-prompt.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/agent-creation-system-prompt.md similarity index 100% rename from plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/agent-creation-system-prompt.md diff --git a/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/permission-modes-rules.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/permission-modes-rules.md new file mode 100644 index 0000000..b0317fd --- /dev/null +++ b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/permission-modes-rules.md @@ -0,0 +1,232 @@ +# 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 + +### 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: + +| 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/agent-development/references/system-prompt-design.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/system-prompt-design.md similarity index 92% rename from plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md rename to plugins/plugin-dev/skills/plugin-dev/references/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/plugin-dev/references/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/agent-development/references/triggering-examples.md b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/triggering-examples.md similarity index 100% rename from plugins/plugin-dev/skills/agent-development/references/triggering-examples.md rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/references/triggering-examples.md diff --git a/plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/scripts/create-agent-skeleton.sh similarity index 100% rename from plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/scripts/create-agent-skeleton.sh diff --git a/plugins/plugin-dev/skills/agent-development/scripts/test-agent-trigger.sh b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/scripts/test-agent-trigger.sh similarity index 100% rename from plugins/plugin-dev/skills/agent-development/scripts/test-agent-trigger.sh rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/scripts/test-agent-trigger.sh diff --git a/plugins/plugin-dev/skills/agent-development/scripts/validate-agent.sh b/plugins/plugin-dev/skills/plugin-dev/references/agent-development/scripts/validate-agent.sh similarity index 100% rename from plugins/plugin-dev/skills/agent-development/scripts/validate-agent.sh rename to plugins/plugin-dev/skills/plugin-dev/references/agent-development/scripts/validate-agent.sh diff --git a/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md b/plugins/plugin-dev/skills/plugin-dev/references/command-development/examples/plugin-commands.md similarity index 99% rename from plugins/plugin-dev/skills/command-development/examples/plugin-commands.md rename to plugins/plugin-dev/skills/plugin-dev/references/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/plugin-dev/references/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/plugin-dev/references/command-development/examples/simple-commands.md similarity index 97% rename from plugins/plugin-dev/skills/command-development/examples/simple-commands.md rename to plugins/plugin-dev/skills/plugin-dev/references/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/plugin-dev/references/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/SKILL.md b/plugins/plugin-dev/skills/plugin-dev/references/command-development/overview.md similarity index 85% rename from plugins/plugin-dev/skills/command-development/SKILL.md rename to plugins/plugin-dev/skills/plugin-dev/references/command-development/overview.md index ce3ed69..f274b31 100644 --- a/plugins/plugin-dev/skills/command-development/SKILL.md +++ b/plugins/plugin-dev/skills/plugin-dev/references/command-development/overview.md @@ -1,13 +1,11 @@ ---- -name: command-development -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:** @@ -109,11 +107,9 @@ No frontmatter needed for basic commands. 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 ---- Review this code for security vulnerabilities... ``` @@ -127,9 +123,7 @@ Review this code for security vulnerabilities... **Default:** First line of command prompt ```yaml ---- description: Review pull request for code quality ---- ``` **Best practice:** Clear, actionable description (under 60 characters) @@ -141,15 +135,13 @@ description: Review pull request for code quality **Default:** Inherits from conversation ```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 @@ -162,9 +154,7 @@ allowed-tools: Read, Write, Edit, Bash(git:*) **Default:** Inherits from conversation ```yaml ---- model: haiku ---- ``` **Use cases:** @@ -182,9 +172,7 @@ Shorthand names use the current default version of each model family. **Default:** None ```yaml ---- argument-hint: [pr-number] [priority] [assignee] ---- ``` **Benefits:** @@ -200,9 +188,7 @@ argument-hint: [pr-number] [priority] [assignee] **Default:** false ```yaml ---- disable-model-invocation: true ---- ``` **Use when:** Command should only be manually invoked @@ -214,10 +200,8 @@ disable-model-invocation: true Capture all arguments as single string: ```markdown ---- description: Fix issue by number argument-hint: [issue-number] ---- Fix issue #$ARGUMENTS following our coding standards and best practices. ``` @@ -241,10 +225,8 @@ Fix issue #456 following our coding standards... Capture individual arguments with `$1`, `$2`, `$3`, etc.: ```markdown ---- description: Review PR with priority and assignee argument-hint: [pr-number] [priority] [assignee] ---- Review pull request #$1 with priority level $2. After review, assign to $3 for follow-up. @@ -290,10 +272,8 @@ Deploy api to staging environment with options: --force --skip-tests Include file contents in command: ```markdown ---- description: Review specific file argument-hint: [file-path] ---- Review @$1 for: @@ -391,6 +371,30 @@ 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. + +**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: + +| 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 @@ -452,9 +456,7 @@ Organize commands in subdirectories: 4. **Handle edge cases:** Consider missing or invalid arguments ```markdown ---- argument-hint: [pr-number] ---- $IF($1, Review PR #$1, @@ -471,7 +473,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 @@ -488,10 +490,8 @@ Please provide a PR number. Usage: /review-pr [number] ### Review Pattern ```markdown ---- description: Review code changes -allowed-tools: Read, Bash(git:*) ---- +allowed-tools: Read, Bash(git *) Files changed: `git diff --name-only` @@ -501,11 +501,9 @@ Review each file for code quality, bugs, test coverage, documentation needs. ### Testing Pattern ```markdown ---- description: Run tests for specific file argument-hint: [test-file] -allowed-tools: Bash(npm:*) ---- +allowed-tools: Bash(npm *) Run tests: `npm test $1` Analyze results and suggest fixes for failures. @@ -514,11 +512,9 @@ Analyze results and suggest fixes for failures. ### Workflow Pattern ```markdown ---- description: Complete PR workflow argument-hint: [pr-number] -allowed-tools: Bash(gh:*), Read ---- +allowed-tools: Bash(gh *), Read PR #$1 Workflow: @@ -573,10 +569,8 @@ Plugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable **Basic usage:** ```markdown ---- description: Analyze using plugin script -allowed-tools: Bash(node:*) ---- +allowed-tools: Bash(node *) Run analysis: `node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1` @@ -643,11 +637,9 @@ plugin-name/ **Configuration-based pattern:** ```markdown ---- description: Deploy using plugin configuration argument-hint: [environment] allowed-tools: Read, Bash(*) ---- Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json @@ -658,10 +650,8 @@ Monitor deployment and report status. **Template-based pattern:** ```markdown ---- description: Generate docs from template argument-hint: [component] ---- Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md @@ -671,10 +661,8 @@ Generate documentation for $1 following template structure. **Multi-script pattern:** ```markdown ---- description: Complete build workflow allowed-tools: Bash(*) ---- Build: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` Test: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh` @@ -709,7 +697,6 @@ Commands should validate inputs and resources before processing: **See `references/plugin-integration.md` for validation examples.** ---- ## Additional Resources diff --git a/plugins/plugin-dev/skills/command-development/references/advanced-workflows.md b/plugins/plugin-dev/skills/plugin-dev/references/command-development/references/advanced-workflows.md similarity index 98% rename from plugins/plugin-dev/skills/command-development/references/advanced-workflows.md rename to plugins/plugin-dev/skills/plugin-dev/references/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/plugin-dev/references/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/plugin-dev/references/command-development/references/documentation-patterns.md similarity index 99% rename from plugins/plugin-dev/skills/command-development/references/documentation-patterns.md rename to plugins/plugin-dev/skills/plugin-dev/references/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/plugin-dev/references/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/plugin-dev/references/command-development/references/frontmatter-reference.md similarity index 92% rename from plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md rename to plugins/plugin-dev/skills/plugin-dev/references/command-development/references/frontmatter-reference.md index 885d840..3314609 100644 --- a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md +++ b/plugins/plugin-dev/skills/plugin-dev/references/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 @@ -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 @@ -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 *) ---