@drunkcoding/agents-and-skills 0.0.11 → 0.0.12

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "tech-graph",
       "source": "./plugins/tech-graph",
       "description": "6-step wizard for technical diagrams (SVG/PNG) via fireworks-tech-graph",
-      "version": "0.0.11",
+      "version": "0.0.12",
       "category": "diagram",
       "keywords": [
         "diagram",
@@ -26,7 +26,7 @@
       "name": "html-effectiveness",
       "source": "./plugins/html-effectiveness",
       "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
-      "version": "0.0.11",
+      "version": "0.0.12",
       "category": "reports",
       "keywords": [
         "html",
@@ -41,7 +41,7 @@
       "name": "team-superpower",
       "source": "./plugins/team-superpower",
       "description": "Coordination layer that runs the obra/superpowers skill chain across a Claude Code agent team — one /team-feature command takes an idea through brainstorming, plan, TDD implementation, review, and finish with at most 4 owner touchpoints.",
-      "version": "0.0.11",
+      "version": "0.0.12",
       "category": "workflow",
       "keywords": [
         "agent-teams",
@@ -52,6 +52,22 @@
         "brainstorming",
         "code-review"
       ]
+    },
+    {
+      "name": "plugin-validator",
+      "source": "./plugins/plugin-validator",
+      "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
+      "version": "0.0.12",
+      "category": "tooling",
+      "keywords": [
+        "validation",
+        "linting",
+        "plugin-authoring",
+        "skills",
+        "agents",
+        "commands",
+        "hooks"
+      ]
     }
   ]
 }

package/README.md

@@ -11,6 +11,7 @@ Published on npm as [`@drunkcoding/agents-and-skills`](https://www.npmjs.com/pac
 | [`tech-graph`](plugins/tech-graph) | 6-step wizard for technical diagrams (SVG + PNG). |
 | [`html-effectiveness`](plugins/html-effectiveness) | Conversational agent that generates self-contained interactive HTML reports from 20 templates. |
 | [`team-superpower`](plugins/team-superpower) | Agent-team conductor that runs the obra/superpowers skill chain end-to-end with at most 4 owner touchpoints. |
+| [`plugin-validator`](plugins/plugin-validator) | Orchestrated validator that checks every plugin's skills, agents, commands, and hooks for spec compliance — runs in parallel and proposes batched fixes. |
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Personal collection of Claude Code skills and agents, installable via `npx skills`.",
   "keywords": [
     "claude-code",

package/plugins/html-effectiveness/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "html-effectiveness",
   "displayName": "HTML Effectiveness Reports",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/plugin-validator/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "plugin-validator",
+  "displayName": "Plugin Validator",
+  "version": "0.0.12",
+  "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
+  "author": {
+    "name": "Steven Hoang"
+  },
+  "keywords": [
+    "validation",
+    "linting",
+    "plugin-authoring",
+    "skills",
+    "agents",
+    "commands",
+    "hooks"
+  ]
+}

package/plugins/plugin-validator/README.md

@@ -0,0 +1,37 @@
+# plugin-validator
+
+Orchestrated validator for Claude Code plugins. Validates skills, agents, commands, and hooks across every plugin under `plugins/**`. Runs sub-validators in parallel and proposes batched fixes.
+
+## Install
+
+```text
+/plugin marketplace add baoduy/agents-and-skills
+/plugin install plugin-validator@drunkcoding
+```
+
+## Usage
+
+Run the full validator across all plugins:
+
+```text
+/validate-plugins
+```
+
+Or invoke individual sub-validators directly:
+
+| Invocation | What it checks |
+|------------|----------------|
+| `/validate-skills` | `SKILL.md` frontmatter and body in all plugins |
+| `/validate-agents` | Agent `.md` files in all plugins |
+| `/validate-commands` | Slash-command `.md` files in all plugins |
+| `/validate-hooks` | `plugin.json` hooks fields and `hooks.json` in all plugins |
+
+## What it produces
+
+- A per-plugin report section with `[PASS]` / `[FAIL]` / `[WARN]` per check.
+- A summary table: `| Plugin | Skills | Hooks | Agents | Commands | Status |`.
+- A batched `## Proposed Fixes` block — choose `Apply all`, `Choose per-item`, or `Skip all`.
+
+## Scope
+
+Scans `plugins/**` only. Local `.claude/` artifacts and vendored paths (e.g. `plugins/tech-graph/skills/tech-graph/`) are excluded.

package/plugins/plugin-validator/agents/plugin-validator.md

@@ -0,0 +1,239 @@
+---
+name: plugin-validator
+description: Use when the user wants to validate every plugin under plugins/** at once. Spawns one parallel subagent per plugin, each running validate-skills, validate-hooks, validate-agents, and validate-commands against its assigned plugin. Aggregates results into a per-plugin section plus a top-level summary table, then proposes ALL fixes for FAIL items in a single batched prompt (Apply all / Skip all / Choose per-item).
+tools: Read, Glob, Grep, Bash, Agent, Edit, Write, AskUserQuestion
+model: sonnet
+---
+
+# Plugin Validator
+
+Orchestrates per-plugin validation. Reads `plugins/**`, dispatches one parallel subagent per plugin, aggregates results, offers interactive fixes.
+
+## Discovery
+
+Use the Glob tool with pattern `plugins/*/.claude-plugin/plugin.json` to enumerate plugin roots. Each match yields a plugin root = the directory two levels above `plugin.json`. Build the list `PLUGINS = [{name, path}, ...]`.
+
+Example: `plugins/caveman/.claude-plugin/plugin.json` → `{ name: "caveman", path: "plugins/caveman" }`.
+
+(Avoid `find ... -path` here — some shell shims strip the `-path` flag. Glob is the safe primitive.)
+
+## Parallel Dispatch
+
+Dispatch one subagent per plugin **in a single message** with multiple Agent tool blocks. Each block sends the worker prompt below with `PLUGIN_PATH` and `PLUGIN_NAME` substituted. Do not wait between launches — all Agent calls go in the same message turn.
+
+### Inlined Worker Prompt Template
+
+```
+You are a plugin validator worker. Your sole job is to validate one plugin and return a structured report. You do not spawn further agents, do not edit any file, and do not prompt the user.
+
+## Input
+
+- PLUGIN_PATH: <substituted>
+- PLUGIN_NAME: <substituted>
+
+## Workflow
+
+### Step 1 — Confirm plugin.json exists
+
+Read `<PLUGIN_PATH>/.claude-plugin/plugin.json`. If it does not exist, return:
+
+```
+### Plugin: <PLUGIN_NAME>
+
+#### validate-skills
+ERROR: plugin.json not found at <PLUGIN_PATH>/.claude-plugin/plugin.json
+
+#### validate-hooks
+ERROR: plugin.json not found
+
+#### validate-agents
+ERROR: plugin.json not found
+
+#### validate-commands
+ERROR: plugin.json not found
+
+→ Status: ERROR
+```
+
+Then stop.
+
+### Step 2 — Run four validation skills
+
+**You MUST invoke all four skills before returning. Do not stop after one. Do not summarize before running them all.** Use the Skill tool for each, scoped to `<PLUGIN_PATH>`. Collect each output as a string for use in Step 4.
+
+- Skill: `validate-skills`  — check all SKILL.md files under `<PLUGIN_PATH>/skills/`
+- Skill: `validate-hooks`   — check hooks in `<PLUGIN_PATH>/.claude-plugin/plugin.json` and any `hooks.json` under `<PLUGIN_PATH>/`
+- Skill: `validate-agents`  — check all `.md` files under `<PLUGIN_PATH>/agents/`
+- Skill: `validate-commands` — check all `.md` files under `<PLUGIN_PATH>/commands/`
+
+If a skill invocation returns an error or throws, record `ERROR: <reason>` for that section and continue with the remaining skills. Do NOT abort the worker.
+
+**Do not echo each skill's `## Validation Results` header back to the orchestrator.** Your job is to transform each skill's output into a `####` sub-section under the single `### Plugin:` block shown in Report Shape. The orchestrator parser depends on the exact shape — anything else breaks aggregation.
+
+### Step 3 — Cap output at 50 lines per section
+
+For each skill output, if the line count exceeds 50, keep the first 50 lines and append exactly:
+
+```
+... <N> more lines, run /validate-<skill> directly for full output
+```
+
+where `<N>` is the count of truncated lines and `<skill>` is the skill name (e.g. `validate-skills`).
+
+### Step 4 — Compute PASS/FAIL per skill
+
+Scan each (possibly truncated) section for `[FAIL]` occurrences.
+- If any `[FAIL]` appears → `FAIL`
+- If only `[PASS]` or `[WARN]` appear, or the section is empty (nothing to check) → `PASS`
+- If the section is an `ERROR:` string → `ERROR`
+
+## Report Shape
+
+Return exactly this markdown block, no other text:
+
+```
+### Plugin: <PLUGIN_NAME>
+
+#### validate-skills
+<output lines, capped at 50>
+
+→ validate-skills: PASS|FAIL|ERROR
+
+#### validate-hooks
+<output lines, capped at 50>
+
+→ validate-hooks: PASS|FAIL|ERROR
+
+#### validate-agents
+<output lines, capped at 50>
+
+→ validate-agents: PASS|FAIL|ERROR
+
+#### validate-commands
+<output lines, capped at 50>
+
+→ validate-commands: PASS|FAIL|ERROR
+
+→ Status: PASS|FAIL|ERROR
+```
+
+`Status` is `FAIL` if any sub-skill is `FAIL`, `ERROR` if any sub-skill is `ERROR` (and none is `FAIL`), else `PASS`.
+
+## Constraints
+
+- Do not spawn further subagents.
+- Do not edit any file.
+- Do not ask the user any question.
+- On Skill error, record `ERROR: <reason>` for that section and continue.
+- Return only the report block above — nothing else.
+```
+
+### Example Dispatch (2 plugins)
+
+The orchestrator sends a single message containing two Agent tool calls in parallel:
+
+**Agent call 1** — prompt = worker template with `PLUGIN_PATH=plugins/caveman`, `PLUGIN_NAME=caveman`
+
+**Agent call 2** — prompt = worker template with `PLUGIN_PATH=plugins/html-effectiveness`, `PLUGIN_NAME=html-effectiveness`
+
+Both run concurrently. After both complete, collect their report blocks.
+
+### Collecting Results
+
+After all subagents complete, collect their report blocks in plugin-name order (alphabetical by `PLUGIN_NAME`). If a subagent returns BLOCKED or produces no output, synthesize a placeholder:
+
+```
+### Plugin: <PLUGIN_NAME>
+
+→ Status: BLOCKED — subagent returned no output
+```
+
+## Aggregation
+
+After all subagents complete:
+
+1. Concatenate their report blocks in plugin-name order, preceded by `## Plugin Validation Report`.
+2. Parse each block's `→ PASS|FAIL|ERROR` lines per sub-skill to populate the summary table.
+3. Compute `Status` per plugin: `FAIL` if any sub-skill is `FAIL`, `ERROR` if any is `ERROR` (and none is `FAIL`), else `PASS`.
+4. Emit summary:
+
+   ```markdown
+   ## Summary
+
+   | Plugin | Skills | Hooks | Agents | Commands | Status |
+   |--------|--------|-------|--------|----------|--------|
+   | <name> | PASS   | FAIL  | PASS   | PASS     | FAIL   |
+   ```
+
+5. Final tally line: `<P>/<N> plugins pass.`
+
+## Batched Fix Proposal Phase
+
+Complete the FULL end-to-end validation first. Emit the per-plugin report AND the summary table BEFORE prompting the user for any fixes. Do not interleave validation with fixing.
+
+After the report+summary are emitted, collect every `[FAIL]` finding across all plugins in plugin-name order. Filter out FAILs whose target file path is under `plugins/tech-graph/skills/tech-graph/` — those are vendored, mark them `not-applied (vendored)` and skip silently.
+
+For the remaining FAILs, emit a single `## Proposed Fixes` section listing **every** fix at once. Numbered, in plugin-name order, each entry showing:
+
+```
+### Fix N — <PLUGIN_NAME> · <skill>
+File: <relative path>
+Issue: <[FAIL] detail>
+Diff:
+```diff
+<unified-diff hunk for the proposed fix>
+```
+```
+
+After the list, issue ONE `AskUserQuestion` with options (exact strings, verbatim):
+
+- `Apply all` — apply every numbered fix in order
+- `Choose per-item` — fall back to one-at-a-time prompts for each fix
+- `Skip all` — exit without applying anything
+
+### On `Apply all`
+
+For each fix 1..N: apply via Edit, then confirm by re-reading the edited region. Record `applied` in the fix summary. If any single Edit fails, record `error: <reason>` for that fix and continue with the rest.
+
+### On `Skip all`
+
+Record `skipped` for every fix. Print `<N> fixes skipped by user choice.`
+
+### On `Choose per-item`
+
+Walk fixes in order. For each, issue `AskUserQuestion` with options:
+
+- `Apply fix`
+- `Skip`
+- `Skip all remaining`
+
+Behavior:
+- `Apply fix` → Edit, re-read, record `applied`.
+- `Skip` → record `skipped`, continue.
+- `Skip all remaining` → record `skipped` for all unprompted FAILs, exit loop, print `<N> fixes skipped by user choice.`
+
+### Fix Summary
+
+After the fix loop completes (or is terminated), emit:
+
+```markdown
+## Fix Summary
+
+| Plugin | Check | Action |
+|--------|-------|--------|
+| <name> | <check description> | applied / skipped / not-applied (vendored) |
+```
+
+## Constraints
+
+- Sub-agent dispatch is depth 2 (you are at depth 1). Do not let workers spawn further agents.
+- Only edit plugin files during the fix phase, only on explicit user `Apply fix`.
+- Never edit files under `plugins/tech-graph/skills/tech-graph/` — vendored subtree.
+- If any worker returns BLOCKED or ERROR, surface it in the report and skip its row in the fix phase.
+- Do not emit any output until all subagents have returned (wait for full parallel batch before aggregating).
+
+## References
+
+- Sub-skills: `validate-skills`, `validate-hooks`, `validate-agents`, `validate-commands`
+- Spec: `docs/superpowers/specs/2026-05-13-plugin-validator-agent-design.md`
+- Plan: `docs/superpowers/plans/2026-05-13-plugin-validator-agent.md`

package/plugins/plugin-validator/commands/validate-plugins.md

@@ -0,0 +1,7 @@
+---
+description: Validate every plugin under plugins/** via the plugin-validator agent.
+---
+
+Dispatch the `plugin-validator` agent. Surface its full report (per-plugin sections + summary table) to the user. After the report+summary are out, surface the agent's single batched `## Proposed Fixes` block plus the `Apply all / Choose per-item / Skip all` prompt. Apply edits per the user's choice and emit the fix-summary table at the end.
+
+Do not perform any validation logic yourself — defer entirely to the agent.

package/plugins/plugin-validator/skills/validate-agents/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: validate-agents
+description: Validates plugin agents (any .md file under plugins/**/agents/) against the Claude Code subagent spec. Use via /validate-agents command.
+license: MIT
+metadata:
+  author: Steven Hoang
+  tags: validation, linting, plugin-authoring, agents
+---
+
+# Validate Agents
+
+Validate plugin agents under `plugins/**/agents/*.md` against the Claude Code subagent spec. Scope: `plugins/**` only.
+
+## Discovery
+
+```bash
+find plugins -path '*/agents/*.md'
+find plugins -path '*/.claude-plugin/plugin.json'
+```
+
+For each `plugin.json`, parse and check whether the `agents` key is present (any shape). Emit one `[FAIL]` per plugin that declares it. Then validate every agent `.md` file as below.
+
+## Spec Compliance Checks
+
+| Check | Rule |
+|-------|------|
+| YAML frontmatter | Present and parses |
+| `name` format | 1-64 chars, lowercase alphanumeric + hyphens; no leading/trailing/consecutive hyphens |
+| `name` matches filename | `agents/foo.md` → `name: foo` |
+| `description` length | 1-1024 chars, non-empty |
+| `tools` optional | Comma-separated string; each name appears in the valid-tool list below |
+| `model` optional | One of `sonnet`, `opus`, `haiku`, `inherit` |
+| No `agents` key in plugin.json | The plugin loader rejects any `agents` field with `agents: Invalid input`. Agent files are auto-discovered from `<plugin>/agents/*.md`. If `plugin.json` declares an `agents` array (or any other shape), flag as `[FAIL]` and recommend deleting the key. Confirmed against `anthropics/claude-code` official plugins (`pr-review-toolkit`, `frontend-design`, `commit-commands`, `hookify`) — none declare `agents`. |
+
+### Valid tool names (Claude Code ≥ 2.1.139)
+
+`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `NotebookEdit`, `Task`, `Agent`, `Skill`, `AskUserQuestion`, `EnterWorktree`, `ExitWorktree`, `EnterPlanMode`, `ExitPlanMode`, `TodoWrite`, `TodoRead`, `TaskCreate`, `TaskUpdate`, `WebFetch`, `WebSearch`, plus any name with the `mcp__<server>__<tool>` prefix (treat unknown `mcp__*` names as `[WARN]`, not `[FAIL]`, because MCP names are dynamic).
+
+Refresh this list when a new Claude Code major version ships. Source: docs.claude.com sub-agents page and `~/.claude/cache/changelog.md`.
+
+## Best-Practice Checks
+
+| Check | Rule |
+|-------|------|
+| Third-person description | Description does not begin with "I " or use "I will" / "I'll" |
+| When-to-invoke trigger | Description states when to invoke (heuristic: contains "Use when", "When the user", or "Trigger") |
+| Body length | Body (post-frontmatter) under 500 lines |
+| No first-person body | Body does not contain "I will" / "I'll" as a leading clause |
+| Behavior section | Body has at least one of: `## Output`, `## Behavior`, `## Workflow`, `## How to Run` |
+
+## How to Run
+
+1. Discover all agent files.
+2. Parse YAML frontmatter (use Python `yaml.safe_load`).
+3. Apply spec + best-practice tables.
+4. Emit report:
+
+   ```
+   ## Validation Results
+
+   ### plugins/<plugin>/agents/<name>.md
+   - [PASS] <check>
+   - [FAIL] <check>: <details>
+   ```
+
+5. Final tally: `Summary: <N> agent files scanned. <P> pass, <F> fail.`
+
+## References
+
+- [Claude Code subagent docs](https://docs.claude.com/en/docs/claude-code/sub-agents)
+- Tool-list provenance: see `docs/superpowers/specs/2026-05-13-plugin-validation-skills-design.md` § Resolution 2
+- Sibling skills: `validate-skills`, `validate-hooks`, `validate-commands`

package/plugins/plugin-validator/skills/validate-commands/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: validate-commands
+description: Validates plugin slash commands (any .md file under plugins/**/commands/) against the Claude Code slash-command spec. Use via /validate-commands command.
+license: MIT
+metadata:
+  author: Steven Hoang
+  tags: validation, linting, plugin-authoring, commands
+---
+
+# Validate Commands
+
+Validate plugin slash commands under `plugins/**/commands/*.md` against the Claude Code slash-command spec. Scope: `plugins/**` only.
+
+## Discovery
+
+```bash
+find plugins -path '*/commands/*.md'
+find plugins -path '*/.claude-plugin/plugin.json'
+```
+
+For each `plugin.json`, parse and check whether the `commands` key is present (any shape). Emit one `[FAIL]` per plugin that declares it. Then validate every command `.md` file as below.
+
+## Spec Compliance Checks
+
+| Check | Rule |
+|-------|------|
+| Frontmatter optional | If present, must parse |
+| `description` length | 1-1024 chars when present |
+| `allowed-tools` optional | Comma-separated string; each name appears in the valid-tool list below |
+| `argument-hint` optional | Plain string |
+| `model` optional | One of `sonnet`, `opus`, `haiku`, `inherit` |
+| Filename → command | Filename minus `.md` is lowercase alphanumeric + hyphens; produces `/<filename>` |
+| Body non-empty | At least one non-blank line after frontmatter |
+| No `commands` key in plugin.json | The plugin loader rejects any `commands` field with `commands: Invalid input`. Command files are auto-discovered from `<plugin>/commands/*.md`. If `plugin.json` declares a `commands` array (or any other shape), flag as `[FAIL]` and recommend deleting the key. Confirmed against `anthropics/claude-code` official plugins (`pr-review-toolkit`, `frontend-design`, `commit-commands`, `hookify`) — none declare `commands`. |
+
+### Valid tool names (Claude Code ≥ 2.1.139)
+
+`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `NotebookEdit`, `Task`, `Agent`, `Skill`, `AskUserQuestion`, `EnterWorktree`, `ExitWorktree`, `EnterPlanMode`, `ExitPlanMode`, `TodoWrite`, `TodoRead`, `TaskCreate`, `TaskUpdate`, `WebFetch`, `WebSearch`, plus any name with the `mcp__<server>__<tool>` prefix (treat unknown `mcp__*` names as `[WARN]`, not `[FAIL]`, because MCP names are dynamic).
+
+Refresh this list when a new Claude Code major version ships. Source: docs.claude.com slash-commands page and `~/.claude/cache/changelog.md`.
+
+## Best-Practice Checks
+
+| Check | Rule |
+|-------|------|
+| `argument-hint` when needed | If body contains `$ARGUMENTS` or `$1`/`$2` etc., frontmatter must set `argument-hint` |
+| Expected output documented | Body describes what the command produces (heuristic: contains `## Output`, `## Result`, or the words "produces" / "writes") |
+| No broken skill refs | Body references to other skills via `superpowers:` or `Skill(...)` resolve to skills installed in this repo (best-effort) |
+
+## How to Run
+
+1. Discover all command files.
+2. Parse YAML frontmatter if present.
+3. Apply spec + best-practice tables.
+4. Emit report:
+
+   ```
+   ## Validation Results
+
+   ### plugins/<plugin>/commands/<name>.md
+   - [PASS] <check>
+   - [FAIL] <check>: <details>
+   ```
+
+5. Final tally: `Summary: <N> command files scanned. <P> pass, <F> fail.`
+
+## References
+
+- [Claude Code slash-command docs](https://docs.claude.com/en/docs/claude-code/slash-commands)
+- Tool-list provenance: see `docs/superpowers/specs/2026-05-13-plugin-validation-skills-design.md` § Resolution 2
+- Sibling skills: `validate-skills`, `validate-hooks`, `validate-agents`

package/plugins/plugin-validator/skills/validate-hooks/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: validate-hooks
+description: Validates plugin hooks (plugin.json hooks field and any referenced hooks.json) in plugins/** against the Claude Code plugin spec. Use via /validate-hooks command.
+license: MIT
+metadata:
+  author: Steven Hoang
+  tags: validation, linting, plugin-authoring, hooks
+---
+
+# Validate Hooks
+
+Validate plugin hooks under `plugins/**` against the Claude Code plugin spec. Scope: `plugins/**` only — local-only `.claude/skills/` and `.claude/hooks/` are out of scope.
+
+## Discovery
+
+```bash
+find plugins -name 'hooks.json'
+find plugins -name 'plugin.json' -path '*/.claude-plugin/*'
+```
+
+Parse each `plugin.json`. If its `hooks` field is an inline object, validate inline. If its `hooks` field is a string path, that is a hard `[FAIL]` (see Spec Compliance below) — but still attempt to resolve and parse the referenced file for additional checks.
+
+## Spec Compliance Checks
+
+| Check | Rule |
+|-------|------|
+| `hooks` field shape | Must be an inline object. String-path form (`"hooks": "<path>"`) is rejected by the Claude Code plugin loader with `hooks: Invalid input`. Flag as `[FAIL]`. |
+| Top-level event keys | One of: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `Notification`, `PreCompact`, `SessionStart`, `SessionEnd` |
+| Event value | Array of matcher groups |
+| Matcher group shape | `{ matcher: string, hooks: [...] }` |
+| Hook entry shape | `{ type: "command"\|"prompt", command?: string, prompt?: string, timeout?: integer }` |
+| Command path resolves | Resolves relative to plugin root, or uses `${CLAUDE_PROJECT_DIR}` / `${CLAUDE_PLUGIN_ROOT}` |
+| Executable bit | Referenced shell script has `+x` |
+| Regex compiles | Matcher value compiles as a Python `re` pattern |
+
+## Best-Practice Checks
+
+| Check | Rule |
+|-------|------|
+| No absolute user paths | Body of command does not contain `/Users/<name>/...` or `/home/<name>/...` |
+| Timeout sane | `timeout` ≤ 60 unless inline comment justifies |
+| Prompt-type targets exist | `prompt`-type hooks reference skills or commands that exist on disk |
+
+## How to Run
+
+1. Discover candidate files (see Discovery above).
+2. For each, parse JSON and apply spec + best-practice checks.
+3. Emit report:
+
+   ```
+   ## Validation Results
+
+   ### plugins/<plugin>/<file>
+   - [PASS] <check description>
+   - [FAIL] <check description>: <details>
+   ```
+
+4. Final tally: `Summary: <N> hooks files scanned. <P> pass, <F> fail.`
+
+## References
+
+- [Claude Code plugin docs](https://docs.claude.com/en/docs/claude-code/plugins.md)
+- Resolution evidence: see `docs/superpowers/specs/2026-05-13-plugin-validation-skills-design.md` § Resolution 1
+- Sibling skills: `validate-skills`, `validate-agents`, `validate-commands`

package/plugins/plugin-validator/skills/validate-skills/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: validate-skills
+description: Validates skills in this repo against agentskills.io spec and Claude Code best practices. Use via /validate-skills command.
+license: MIT
+metadata:
+  author: Callstack
+  upstream: https://github.com/callstackincubator/agent-skills
+  tags: validation, linting, skill-authoring
+---
+
+# Validate Skills
+
+Validate all skills in this repo against the agentskills.io spec and Claude Code best practices.
+
+## Validation Checklist
+
+For each skill directory, verify:
+
+### Spec Compliance (agentskills.io)
+
+| Check | Rule |
+|-------|------|
+| `name` format | 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens |
+| `name` matches directory | Directory name must equal `name` field |
+| `description` length | 1-1024 characters, non-empty |
+| Optional fields valid | `license`, `metadata`, `compatibility` if present |
+| `skills` key in plugin.json | If `plugin.json` declares `skills`, it must be a string directory path (e.g. `"./skills/"`). Array-of-paths form is unverified and likely rejected by the loader — flag as `[WARN]` and recommend either a string path or omitting the key entirely (skills are auto-discovered from `<plugin>/skills/*/SKILL.md`). Reference: `context-mode` plugin uses `"skills": "./skills/"`; Anthropic official plugins omit the key. |
+
+### Best Practices (Claude Code)
+
+| Check | Rule |
+|-------|------|
+| Description format | Third person, describes what + when to use |
+| Body length | Under 500 lines |
+| References one-level deep | No nested reference chains |
+| Links are markdown | Use `[text](path)` not bare filenames |
+| No redundancy | Don't repeat description in body |
+| Concise | Only add context Claude doesn't already have |
+
+## How to Run
+
+1. Find all skill directories under `plugins/`:
+   ```bash
+   fd -t f -g 'SKILL.md' plugins/
+   ```
+   (Per project memory: scope is `plugins/**` only — skip `.claude/skills/`.)
+
+2. Parse each `plugins/*/.claude-plugin/plugin.json`. If `skills` key is present and not a string path (e.g., array of paths), emit `[WARN]` for that plugin with recommendation to switch to `"./skills/"` or omit.
+
+3. For each `SKILL.md`, read it and check against the rules above.
+
+3. Report issues in this format:
+   ```
+   ## Validation Results
+
+   ### plugins/<plugin>/skills/<skill>
+   - [PASS] name format valid
+   - [FAIL] name "example" doesn't match directory "example-skill"
+   - [PASS] description length OK (156 chars)
+   ```
+
+## References
+
+- [agentskills.io spec](https://agentskills.io/specification)
+- [Claude Code best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- Upstream: [callstackincubator/agent-skills](https://github.com/callstackincubator/agent-skills)

package/plugins/team-superpower/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-superpower",
   "displayName": "Team Superpower",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Coordination layer that runs the obra/superpowers skill chain across a Claude Code agent team — one /team-feature command takes an idea through brainstorming, plan, TDD implementation, review, and finish with at most 4 owner touchpoints.",
   "author": {
     "name": "Steven Hoang"

package/plugins/tech-graph/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-graph",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"