summer-engine 1.2.1 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Summer Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/commands/skills.js

@@ -13,7 +13,7 @@ function getBuiltinSkills() {
     for (const entry of SKILL_REGISTRY) {
         if (!entry.public)
             continue;
-        const skillPath = join(skillsDir, entry.name, "SKILL.md");
+        const skillPath = join(skillsDir, entry.category, entry.name, "SKILL.md");
         if (!existsSync(skillPath))
             continue;
         const frontmatter = parseSkillFrontmatter(skillPath);
@@ -48,13 +48,19 @@ function getSkillMeta(name) {
     return getBuiltinSkills().find((skill) => skill.name === name) ?? null;
 }
 function getSkillPath(name) {
-    const path = join(skillsDir, name);
+    const entry = SKILL_REGISTRY.find((s) => s.name === name);
+    if (!entry)
+        return null;
+    const path = join(skillsDir, entry.category, entry.name);
     if (!existsSync(path) || !existsSync(join(path, "SKILL.md")))
         return null;
     return path;
 }
 function getSkillBody(name) {
-    const skillPath = join(skillsDir, name, "SKILL.md");
+    const entry = SKILL_REGISTRY.find((s) => s.name === name);
+    if (!entry)
+        throw new Error(`Unknown skill: ${name}`);
+    const skillPath = join(skillsDir, entry.category, entry.name, "SKILL.md");
     const content = readFileSync(skillPath, "utf-8");
     return content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, "").trim();
 }

package/dist/lib/skills-registry.d.ts

@@ -1,67 +1,73 @@
 export declare const AGENT_CLIENTS: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
 export type AgentClient = (typeof AGENT_CLIENTS)[number];
-export type SkillCategory = "workflow" | "scripting" | "scene" | "gameplay" | "lighting" | "assets" | "ui";
+export declare const SKILL_CATEGORIES: readonly ["_meta", "character-controllers", "gameplay-mechanics", "scripting-patterns", "scene-and-project", "rendering-and-lighting", "shaders", "visual-effects", "post-processing", "animation", "audio", "physics", "multiplayer-and-networking", "ai-and-npcs", "level-design", "performance", "ui-and-ux", "asset-pipeline", "input-and-controls", "debugging", "deployment"];
+export type SkillCategory = (typeof SKILL_CATEGORIES)[number];
 export interface SkillRegistryEntry {
     name: string;
-    public: boolean;
     category: SkillCategory;
+    public: boolean;
     clients: readonly AgentClient[];
     recommended: boolean;
     requiresMcpTools: readonly string[];
     testScenario: string;
 }
+/**
+ * Skills with `status: HAVE` in catalog.yaml. The catalog is the planning source
+ * of truth (~85 skills); this TS registry is the install-time list (only skills
+ * with shippable content). When a NEXT skill ships, mirror it here.
+ */
 export declare const SKILL_REGISTRY: readonly [{
     readonly name: "gdscript-patterns";
+    readonly category: "scripting-patterns";
     readonly public: true;
-    readonly category: "scripting";
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
     readonly recommended: true;
-    readonly requiresMcpTools: readonly ["summer_set_prop", "summer_connect_signal", "summer_input_map_bind", "summer_get_script_errors"];
-    readonly testScenario: "Create a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.";
+    readonly requiresMcpTools: readonly ["summer_get_script_errors"];
+    readonly testScenario: "Write a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.";
 }, {
     readonly name: "scene-composition";
+    readonly category: "scene-and-project";
     readonly public: true;
-    readonly category: "scene";
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_create_scene", "summer_open_scene", "summer_get_scene_tree", "summer_add_node", "summer_instantiate_scene", "summer_save_scene"];
     readonly testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.";
 }, {
     readonly name: "fps-controller";
+    readonly category: "character-controllers";
     readonly public: true;
-    readonly category: "gameplay";
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_add_node", "summer_set_prop", "summer_set_resource_property", "summer_input_map_bind"];
     readonly testScenario: "Create a CharacterBody3D player with collision, camera, input actions, and a host-edited controller script.";
 }, {
     readonly name: "3d-lighting";
+    readonly category: "rendering-and-lighting";
     readonly public: true;
-    readonly category: "lighting";
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_add_node", "summer_set_prop", "summer_set_resource_property"];
     readonly testScenario: "Add sun, fill lighting, WorldEnvironment, and shadow settings to a simple 3D scene.";
 }, {
     readonly name: "ui-basics";
+    readonly category: "ui-and-ux";
     readonly public: true;
-    readonly category: "ui";
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_add_node", "summer_set_prop", "summer_connect_signal"];
     readonly testScenario: "Create a HUD CanvasLayer with labels, a ProgressBar, and a connected Button signal.";
 }, {
     readonly name: "asset-strategy";
+    readonly category: "asset-pipeline";
     readonly public: true;
-    readonly category: "assets";
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_search_assets", "summer_import_asset", "summer_import_from_url", "summer_generate_image", "summer_generate_3d", "summer_generate_audio"];
     readonly testScenario: "Choose library, generated, or primitive assets for a small level and import one asset into the project.";
 }, {
     readonly name: "make-game";
+    readonly category: "scene-and-project";
     readonly public: true;
-    readonly category: "workflow";
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
     readonly recommended: false;
     readonly requiresMcpTools: readonly ["summer_get_agent_playbook", "summer_get_project_context", "summer_create_scene", "summer_open_scene", "summer_save_scene", "summer_add_node", "summer_set_prop", "summer_set_resource_property", "summer_instantiate_scene", "summer_play", "summer_stop", "summer_get_diagnostics"];

package/dist/lib/skills-registry.js

@@ -5,26 +5,51 @@ export const AGENT_CLIENTS = [
     "cursor",
     "windsurf",
 ];
+export const SKILL_CATEGORIES = [
+    "_meta",
+    "character-controllers",
+    "gameplay-mechanics",
+    "scripting-patterns",
+    "scene-and-project",
+    "rendering-and-lighting",
+    "shaders",
+    "visual-effects",
+    "post-processing",
+    "animation",
+    "audio",
+    "physics",
+    "multiplayer-and-networking",
+    "ai-and-npcs",
+    "level-design",
+    "performance",
+    "ui-and-ux",
+    "asset-pipeline",
+    "input-and-controls",
+    "debugging",
+    "deployment",
+];
 const ALL_CLIENTS = AGENT_CLIENTS;
+/**
+ * Skills with `status: HAVE` in catalog.yaml. The catalog is the planning source
+ * of truth (~85 skills); this TS registry is the install-time list (only skills
+ * with shippable content). When a NEXT skill ships, mirror it here.
+ */
 export const SKILL_REGISTRY = [
     {
         name: "gdscript-patterns",
+        category: "scripting-patterns",
         public: true,
-        category: "scripting",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
-            "summer_set_prop",
-            "summer_connect_signal",
-            "summer_input_map_bind",
             "summer_get_script_errors",
         ],
-        testScenario: "Create a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.",
+        testScenario: "Write a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.",
     },
     {
         name: "scene-composition",
+        category: "scene-and-project",
         public: true,
-        category: "scene",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -39,8 +64,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "fps-controller",
+        category: "character-controllers",
         public: true,
-        category: "gameplay",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -53,8 +78,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "3d-lighting",
+        category: "rendering-and-lighting",
         public: true,
-        category: "lighting",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -66,8 +91,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "ui-basics",
+        category: "ui-and-ux",
         public: true,
-        category: "ui",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -79,8 +104,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "asset-strategy",
+        category: "asset-pipeline",
         public: true,
-        category: "assets",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -95,8 +120,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "make-game",
+        category: "scene-and-project",
         public: true,
-        category: "workflow",
         clients: ALL_CLIENTS,
         recommended: false,
         requiresMcpTools: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",

package/skills/README.md

@@ -0,0 +1,96 @@
+# Summer Skill Library
+
+The canonical agent-readable game-dev knowledge source for Claude Code, Cursor, Codex, and Windsurf.
+
+When an agent is asked to make a game in Godot, this is what it reads to learn how.
+
+## Layout
+
+```
+skills/
+├── README.md                  # this file
+├── catalog.yaml               # canonical registry (name, category, status, template-id)
+├── _shared/                   # cross-skill references every skill can link
+│   ├── godot-version.md
+│   ├── mcp-tools-reference.md
+│   ├── collaborative-protocol.md
+│   ├── template-registry.md
+│   └── gd-style.md
+├── _meta/
+│   ├── skill-test/            # static + behavioral linter
+│   ├── skill-create/          # bootstrap a new skill
+│   └── skill-improve/         # eval-harness iteration
+├── _tests/
+│   ├── runner.md              # how /skill-test works
+│   └── specs/                 # behavioral specs per skill
+└── <category>/<skill>/
+    ├── SKILL.md               # < 500 lines, frontmatter + body
+    ├── references/            # loaded on demand
+    ├── examples/              # working snippets
+    └── tests/spec.md          # behavioral spec
+```
+
+## Categories (20)
+
+`character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
+
+## Standard
+
+Adopts the **Anthropic Agent Skills open standard** (`agentskills.io`). Frontmatter:
+
+```yaml
+---
+name: <kebab-case>
+description: <when-to-use, key trigger phrases first>
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: <one of the 20>
+template-id: <optional, resolved against _shared/template-registry.md>
+allowed-tools: Read Grep summer_add_node summer_set_prop ...
+paths: ["**/*.gd", "**/*.tscn"]
+---
+```
+
+Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
+
+## Authoring rules
+
+1. **SKILL.md ≤ 500 lines.** Push detail into `references/`. Progressive disclosure.
+2. **MCP-preferred + file-edit-fallback.** Every code-touching skill must show both paths so the skill works without Summer MCP installed.
+3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `_shared/collaborative-protocol.md`.
+4. **Template cross-link.** When a working starter exists, link via `template-id` and the section "Want a working starter?".
+5. **Test spec.** Every non-`_meta` skill ships `tests/spec.md` with at least one Test Case.
+
+## Adding a new skill
+
+```
+/skill-create
+```
+
+(See `_meta/skill-create/SKILL.md`.)
+
+## Testing
+
+```
+/skill-test <name>           # static lint
+/skill-test <name> spec      # behavioral spec runner
+/skill-test audit            # whole-library audit
+/skill-improve <name>        # parallel-eval harness for iteration
+```
+
+(See `_meta/skill-test/SKILL.md` and `_tests/runner.md`.)
+
+## Roadmap
+
+Status legend in `catalog.yaml`:
+
+- **HAVE** — ships today.
+- **NEXT** — next wave, in active development.
+- **LATER** — on roadmap.
+
+Currently: **7 HAVE / ~50 NEXT / ~30 LATER ≈ 85 skills across 20 categories**. Subagents fill content category by category.
+
+## See also
+
+- [Architecture spec](../../../publicsummerengine/Docs/superpowers/specs/2026-05-05-skill-library-architecture.md) (lives in publicsummerengine for spec history)
+- [Research notes](../../../publicsummerengine/Docs/superpowers/research/2026-05-05-skill-library-research.md)

package/skills/_meta/skill-create/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: skill-create
+description: Bootstrap a new Summer skill with the canonical folder structure, frontmatter, and stub sections. Use when adding a new skill to the library. Trigger on "create skill", "add skill", "new skill".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: _meta
+allowed-tools: Read Write Glob Grep
+---
+
+# /skill-create — Bootstrap a New Skill
+
+## Steps
+
+### 1. Get the basics
+
+Ask the user:
+- **Name** (kebab-case, ≤ 64 chars). Example: `state-machine-patterns`.
+- **Category** (one of the 20 in `catalog.yaml`). Example: `scripting-patterns`.
+- **One-sentence description** for the frontmatter.
+- **Template-id** (optional). Lookup against `_shared/template-registry.md`.
+
+### 2. Create the folder
+
+May I create `skills/<category>/<name>/` with this structure?
+
+```
+skills/<category>/<name>/
+├── SKILL.md
+├── references/        (empty, populate as needed)
+├── examples/          (empty, populate as needed)
+└── tests/spec.md
+```
+
+### 3. Write SKILL.md (template)
+
+```markdown
+---
+name: <name>
+description: <one-sentence what + when. Lead with key trigger phrases.>
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: <category>
+template-id: <optional template-id from _shared/template-registry.md>
+allowed-tools: Read Grep <summer_* tools this skill uses>
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# <Title> for Summer Engine
+
+<One-paragraph context. Why this exists, who needs it.>
+
+## Steps
+
+### 1. <First step>
+
+**Preferred (Summer MCP):**
+
+\`\`\`
+summer_<tool>(...)
+\`\`\`
+
+**Fallback (no MCP — edit `<file>` directly):**
+
+\`\`\`
+<raw text/code>
+\`\`\`
+
+May I <action>?
+
+### 2. <Second step>
+
+...
+
+## Common mistakes
+
+- <mistake 1, with one-line fix>
+- <mistake 2, with one-line fix>
+
+## Want a working starter?
+
+→ **template-id**: `<template-id>`
+→ **Repo**: <github URL from _shared/template-registry.md>
+→ **Bootstrap**: `summer template clone <template-id> my-game`
+
+## See also
+
+- `_shared/godot-version.md`
+- `_shared/mcp-tools-reference.md`
+- `_shared/gd-style.md`
+- (other relevant skills)
+```
+
+### 4. Write tests/spec.md (template)
+
+```markdown
+# Skill Spec: /<name>
+
+## Fixture
+- <starting state of the project>
+- <which tools are available — Summer MCP yes/no>
+
+## Case 1: Happy Path
+**Input:** "<typical user prompt>"
+**Expected MCP tool sequence (in order):**
+1. <first tool call>
+2. <second>
+
+**Assertions:**
+- [ ] <observable outcome>
+- [ ] <skill asks "May I" before any write step>
+
+## Case 2: Failure / Edge
+**Fixture:** <something different>
+**Input:** "<edge prompt>"
+**Expected:** <how the skill should adapt>
+```
+
+### 5. Register in catalog.yaml
+
+Append:
+
+```yaml
+  - name: <name>
+    category: <category>
+    status: NEXT  # or HAVE if shipping immediately
+    template-id: <or omit>
+    public: true
+    recommended: false  # flip to true when status: HAVE and tested
+```
+
+### 6. Run /skill-test in static mode
+
+Confirm the new skill passes the 7 structural checks before commit.
+
+## Collaborative protocol
+
+This skill writes files (the new skill folder + catalog update). Always ask before each write step.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_meta/skill-test/SKILL.md`
+- `catalog.yaml`

package/skills/_meta/skill-improve/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: skill-improve
+description: Iterate on an existing Summer skill using a parallel-eval harness — run the skill against a behavioral spec with and without proposed changes, compare outputs, ship the version that wins. Use to upgrade a skill that's underperforming. Trigger on "improve skill", "iterate on skill", "make this skill better".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: _meta
+allowed-tools: Read Write Edit Task
+---
+
+# /skill-improve — Iterate on a Skill With Eval Harness
+
+Inspired by `anthropics/skills` `skill-creator/`. Use when a skill's behavioral spec is failing assertions or producing low-quality output.
+
+## When to use this vs. `/skill-test`
+
+- `/skill-test spec` reasons over text. Cheap, fast, lossy.
+- `/skill-improve` actually runs the skill in parallel subagents with-vs-without proposed changes. Expensive, accurate.
+
+Run this when `/skill-test spec` flags issues you can't fix by reading the skill alone.
+
+## Steps
+
+### 1. Pick the skill + the spec
+
+Ask the user:
+- **Skill name.** Resolves to `skills/<category>/<name>/SKILL.md`.
+- **Test cases to focus on.** Default: all `## Case` blocks in `_tests/specs/<name>.md`.
+
+### 2. Establish a baseline
+
+For each Case:
+
+1. Spawn a subagent (`Task` tool, `general-purpose`) with the **current** skill body in context.
+2. Give it the Case's Input + Fixture.
+3. Capture the tool calls it makes and the diff it produces.
+4. Score against the Case's Assertions.
+
+Save outputs to `_tests/runs/<skill-name>/baseline/case-<N>/`.
+
+### 3. Propose changes
+
+Read the failing Cases. Identify the gap between what the skill says and what the agent did. Common gaps:
+
+- Skill names a tool but the agent picked a different one (clarify the trigger).
+- Skill assumes a fixture detail the agent missed (add explicit step to confirm).
+- Skill's "May I" wording is too generic for the agent to infer the right ask.
+
+Draft a revised SKILL.md. May I write it to `_tests/runs/<skill-name>/proposed/SKILL.md`?
+
+### 4. Run the proposed version
+
+Repeat step 2 with the proposed SKILL.md. Save to `_tests/runs/<skill-name>/proposed/case-<N>/`.
+
+### 5. Compare and decide
+
+For each Case, score:
+
+- Assertions passed (proposed vs. baseline).
+- Tool-call efficiency (fewer tools = better, all else equal).
+- Hallucination / unwanted ops (penalize).
+
+Output:
+
+```
+Case 1 (Happy):     baseline 4/6  proposed 6/6  ✓ ship proposed
+Case 2 (Failure):   baseline 3/4  proposed 4/4  ✓ ship proposed
+Case 3 (Edge):      baseline 3/3  proposed 3/3  = no change
+```
+
+If proposed wins on net, prompt the user:
+
+> Proposed version wins 2 cases, ties 1, loses 0. May I overwrite `skills/<category>/<name>/SKILL.md` with the proposed version and update `last-tested:` in `catalog.yaml`?
+
+### 6. Ship
+
+On user yes:
+- Overwrite `SKILL.md`.
+- Update `last-tested: <today>` in `catalog.yaml`.
+- Commit with message `feat(skill): improve <name> — <one-line summary of change>`.
+
+## Collaborative protocol
+
+This skill writes files at multiple steps. Always ask before each write.
+
+## See also
+
+- `_meta/skill-test/SKILL.md`
+- `_tests/runner.md`
+- `_tests/specs/`

package/skills/_meta/skill-test/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: skill-test
+description: Validate a Summer skill against static structural rules and per-skill behavioral specs. Use to lint a skill before commit, audit the whole library, or check a behavioral spec assertion. Trigger on "skill test", "lint skill", "validate skill".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: _meta
+allowed-tools: Read Glob Grep
+---
+
+# /skill-test — Validate a Summer Skill
+
+Three modes. Pick by the user's intent.
+
+## Mode: `static` — Structural lint (default for "test this skill")
+
+For a single skill at `skills/<category>/<name>/`, run these checks:
+
+1. **Frontmatter completeness.** `name`, `description`, `license`, `compatibility`, `category` present. `name` matches the directory name.
+2. **SKILL.md length.** ≤ 500 lines. (Progressive disclosure rule from Anthropic spec.)
+3. **MCP-preferred + file-edit-fallback.** If the skill mutates scenes or resources, body must show both:
+   - At least one `summer_*` MCP tool example.
+   - At least one file-edit fallback block (e.g., raw `.tscn` snippet) OR an explicit "no fallback for this — Summer MCP required" note.
+4. **Collaborative protocol.** If the skill triggers user-visible writes, body must contain at least one of: `May I`, `I'm about to`, `Continue?`, `OK?`, `Proceed?`. Skills that only inspect/read are exempt.
+5. **Template-id resolved.** If the skill's frontmatter declares `template-id: <id>`, that id must exist in `_shared/template-registry.md`.
+6. **Tests/spec.md present.** Every skill in a non-`_meta` category must have `tests/spec.md` with at least one `## Case` heading.
+7. **No broken relative links.** Every `](../...)` and `](./...)` in the body must point at an existing file.
+
+Output:
+
+```
+skill: <category>/<name>
+  PASS  (1) frontmatter complete
+  PASS  (2) length 217 / 500 lines
+  FAIL  (3) no MCP-preferred example found in body
+  PASS  (4) collaborative protocol present
+  PASS  (5) template-id resolved
+  PASS  (6) tests/spec.md exists
+  PASS  (7) all relative links resolve
+
+6 PASS / 1 FAIL — fix item 3 before commit.
+```
+
+## Mode: `spec` — Behavioral spec runner
+
+For a single skill, read both `skills/<category>/<name>/SKILL.md` and `_tests/specs/<name>.md`. For each `## Case` in the spec:
+
+1. Lay out the **Fixture** (starting state, available tools).
+2. Read the **Input** (user prompt).
+3. Reason: given the skill's instructions and this fixture, would the agent follow the **Expected MCP tool sequence**?
+4. For each assertion under `**Assertions:**`, mark `[x]` if the skill's instructions would satisfy it, `[ ]` if not, with a one-line reason.
+
+Output: an annotated copy of the spec with assertions filled in, plus a pass-rate.
+
+No code execution. Pure reasoning over text.
+
+## Mode: `audit` — Whole library report
+
+Read `catalog.yaml`. For each skill with `status: HAVE`:
+
+1. Run `static` mode on the skill.
+2. Note the skill's `last-tested:` date.
+3. Flag skills where `last-tested:` is missing or older than 30 days.
+
+Output: a table with PASS / FAIL counts, last-tested ages, and a punch list of skills needing attention.
+
+## When to use which mode
+
+| User said | Mode |
+|---|---|
+| "test the fps-controller skill" | static |
+| "lint this skill" | static |
+| "does this skill actually do what it should?" | spec |
+| "run the behavioral check" | spec |
+| "audit the skill library" | audit |
+| "what skills need work" | audit |
+
+## Collaborative protocol
+
+This skill is **read-only**. It never writes. No "May I" needed.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_shared/template-registry.md`
+- `_tests/runner.md`
+- `_tests/specs/` — per-skill behavioral specs