summer-engine 1.2.0 → 1.3.0

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

package/skills/_shared/collaborative-protocol.md

@@ -0,0 +1,50 @@
+# Collaborative Protocol — "May I write?"
+
+> Every Summer skill must follow this. The agent works *with* the user, not around them.
+
+## The rule
+
+**Before any user-visible write step, the agent must explicitly state what it is about to do and ask permission to proceed.**
+
+This applies to:
+- Creating files (`.gd`, `.tscn`, `.tres`, JSON, configs)
+- Modifying existing files (especially `.gd` and `.tscn`)
+- Running irreversible operations (deletion, reset, force-overwrite)
+- Setting up project-wide settings (`project.godot`)
+- Installing tools, libraries, or templates
+
+Reading is unconditional. Inspection, scene-tree walks, diagnostics — never need permission.
+
+## Phrasing
+
+Plain, short, action-first. Examples:
+
+> May I create `scenes/player.tscn` and add a CharacterBody3D + Camera3D?
+
+> I'm about to overwrite `levels/level_01.tscn`. The current version has 14 nodes — I'll preserve them and add the new lighting setup. Continue?
+
+> May I attach `scripts/player_controller.gd` to `./World/Player`?
+
+> I'm going to bind `move_forward`, `move_back`, `move_left`, `move_right`, `jump`. OK?
+
+## What this prevents
+
+1. **Silent overwrites.** The agent stomps the user's hand-edited script.
+2. **Cascading scope creep.** A "small fix" turns into a 30-file refactor.
+3. **Unclear state.** The user has no idea what changed when something breaks.
+4. **Trust loss.** One unauthorized edit and the user stops trusting the agent.
+
+## What this is NOT
+
+- Not a confirmation dialog for every property change in a single skill execution. Group related writes into one ask: "I'm about to add the player root, attach the controller script, and bind 5 input actions. OK?"
+- Not a request for design input. The skill should know what to do; the ask is for permission, not direction.
+- Not a stop on simple read-only ops or single-property tweaks the user clearly directed.
+
+## Linter check
+
+The `_meta/skill-test/SKILL.md` static linter looks for the phrases:
+- "May I" / "May I write" / "May I create" / "May I attach"
+- "I'm about to"
+- "Continue?" / "OK?" / "Proceed?"
+
+A skill that mutates files but never says any of these fails the linter.

package/skills/_shared/gd-style.md

@@ -0,0 +1,121 @@
+# GDScript Style — Summer Conventions
+
+> The bar for GDScript in Summer. Skills should produce code that matches this. Where Godot's official style guide is silent, this is the tiebreaker.
+
+## File structure
+
+```gdscript
+class_name PlayerController
+extends CharacterBody3D
+
+# 1. Constants
+const SPEED := 5.0
+const JUMP_VELOCITY := 4.5
+const GRAVITY := 9.8
+
+# 2. Exports (designer-tweakable in inspector)
+@export var move_speed: float = 5.0
+@export var jump_height: float = 1.0
+@export_range(0.1, 10.0) var look_sensitivity: float = 1.0
+
+# 3. Signals (events this node emits)
+signal died
+signal health_changed(new_value: int)
+
+# 4. Onready references (cached node lookups)
+@onready var camera: Camera3D = $Camera3D
+@onready var collision: CollisionShape3D = $CollisionShape3D
+
+# 5. Private state (snake_case, leading underscore optional)
+var _is_grounded: bool = false
+var _velocity := Vector3.ZERO
+
+# 6. Lifecycle (in canonical order)
+func _ready() -> void:
+    pass
+
+func _process(delta: float) -> void:
+    pass
+
+func _physics_process(delta: float) -> void:
+    pass
+
+func _input(event: InputEvent) -> void:
+    pass
+
+# 7. Public API (PascalCase or snake_case methods, snake_case for funcs)
+func take_damage(amount: int) -> void:
+    pass
+
+# 8. Private helpers (leading underscore)
+func _calculate_movement(delta: float) -> Vector3:
+    return Vector3.ZERO
+```
+
+## Type hints
+
+**Always type-hint.** No bare `var x = 5`. Use `:=` for inferred typing or `:` for explicit.
+
+```gdscript
+# RIGHT
+var speed: float = 5.0
+var name := "Player"
+func attack(target: Node3D, amount: int) -> bool:
+    return true
+
+# WRONG
+var speed = 5.0
+func attack(target, amount):
+    return true
+```
+
+## Naming
+
+| Thing | Convention | Example |
+|---|---|---|
+| Class | PascalCase | `class_name PlayerController` |
+| File | snake_case | `player_controller.gd` |
+| Variable, function | snake_case | `move_speed`, `take_damage()` |
+| Constant | SCREAMING_SNAKE_CASE | `const MAX_HEALTH := 100` |
+| Signal | snake_case (past tense for events) | `died`, `health_changed` |
+| Private | leading underscore | `_is_grounded`, `_calculate_movement` |
+| Node in scene | PascalCase | `Player`, `Camera3D`, `CollisionShape3D` |
+
+## Signals
+
+Define with typed args. Connect in `_ready()` or in scene `.tscn` directly.
+
+```gdscript
+signal health_changed(new_value: int, max_value: int)
+
+func _ready() -> void:
+    health_changed.connect(_on_health_changed)
+
+func _on_health_changed(new_value: int, max_value: int) -> void:
+    pass
+```
+
+## Tweens
+
+Use `create_tween()` for animation. Don't manually lerp in `_process` unless you need fine control.
+
+```gdscript
+var tween := create_tween()
+tween.tween_property(self, "modulate", Color.WHITE, 0.3)
+```
+
+## What to avoid
+
+- Bare `var x = something` (no type)
+- `Object` typed parameters (use specific class)
+- `match` for two-branch logic (use `if`)
+- Recreating node lookups in `_process` (cache via `@onready`)
+- Hard-coded strings for node paths in code (use `@onready` + scene-relative paths)
+- Setting `position` in `_process` for physics objects (use `_physics_process` and `velocity`)
+
+## See also
+
+- [Official Godot GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html)
+- `scripting-patterns/gdscript-patterns/SKILL.md` — patterns and idioms
+- `scripting-patterns/signal-patterns/SKILL.md` — signal usage
+- `scripting-patterns/state-machine-patterns/SKILL.md` — state machine patterns

package/skills/_shared/godot-version.md

@@ -0,0 +1,32 @@
+# Godot / Summer Engine Version Reference
+
+> Read this **before** writing any code, especially shaders or rendering code. Godot's API is moving; the LLM cutoff date matters per domain.
+
+## Engine fork base
+
+Summer Engine is a fork of **Godot 4.5** (stable). All skills assume Godot 4.x APIs.
+
+## LLM training cutoff vs. Godot release dates
+
+| Domain | Godot 4.x churn | Action |
+|---|---|---|
+| Scripting (GDScript core) | low | Trust your training. Spot-check signatures only when something feels off. |
+| Scene / node tree APIs | low | Trust your training. |
+| Renderer (`RenderingServer`, `Compositor`) | high in 4.4 / 4.5 | Verify before writing. Check `MovieMaker`, `Compositor` effects, `RenderSceneBuffers` — these renamed/added recently. |
+| Shaders (`canvas_item`, `spatial`, `compute`) | medium | Built-in functions stable, but `hint_*` flags shifted. Verify `hint_screen_texture` / `hint_depth_texture` syntax. |
+| Animation (`AnimationTree`, `AnimationMixer`) | high (4.0 → 4.3 rename) | Use `AnimationMixer` for new code, not deprecated `AnimationPlayer`-as-mixer. |
+| Multiplayer (`MultiplayerAPI`) | medium | High-level API stable. `SceneReplicationConfig` settled in 4.0+. |
+| Editor / EditorPlugin | medium | Spot-check. |
+| `Tween` / `SceneTreeTween` | low | Stable since 4.0. |
+
+## Summer-specific deltas from vanilla Godot
+
+- Local API server runs on `localhost:6550` (set per machine via `~/.summer/api-token`).
+- Engine ships a webview module in `modules/1summer_engine/` — do not assume vanilla Godot for editor UI patches.
+- Project root contains `.summer/` for project memory; do not delete it.
+
+## When in doubt
+
+1. Use Summer MCP tools (`summer_inspect_node`, `summer_inspect_resource`) to read live editor state instead of guessing.
+2. Use `summer_get_diagnostics` after every scene change.
+3. Check `_shared/mcp-tools-reference.md` for the canonical tool list.

package/skills/_shared/mcp-tools-reference.md

@@ -0,0 +1,133 @@
+# Summer MCP Tools — Canonical Reference
+
+> Use this as the single source of truth for which Summer MCP tool to call. Skills should reference tool names exactly as written here.
+
+## When to use Summer MCP vs. host file edits
+
+**Use Summer MCP for** anything that needs the live editor or Godot's import pipeline:
+- Scene graph mutation (`.tscn`)
+- Node properties and resources (`.tres`)
+- Project settings (`project.godot`) and InputMap
+- Asset import (Godot's import pipeline must run)
+- Play / stop / runtime state
+- Diagnostics, console, debugger output, script errors
+
+**Use the host agent's file tools for** plain text:
+- `.gd` GDScript files
+- `.cs` C# files
+- `.json`, `.md`, `.txt`, `.yaml`
+- Most simple `.tres` resources where the structure is well-known
+
+**Rule of thumb:** if Godot's importer or the live editor needs to know about it, MCP. Otherwise, file edits.
+
+## Tool surface (37 tools)
+
+### Scene graph (10)
+
+| Tool | Use |
+|---|---|
+| `summer_get_scene_tree` | Read current scene graph. Always do this before mutating. |
+| `summer_open_main_scene` | Open the project's main scene. |
+| `summer_open_scene` | Open a specific `.tscn`. |
+| `summer_create_scene` | Create a new scene. |
+| `summer_inspect_node` | Read a single node's properties. |
+| `summer_add_node` | Add a node to the active scene. |
+| `summer_remove_node` | Remove a node. |
+| `summer_replace_node` | Swap a node's type, preserving children. |
+| `summer_select_node` | Set editor selection (visual feedback for the user). |
+| `summer_save_scene` | Persist changes. **Always save before play.** |
+
+### Properties / resources (4)
+
+| Tool | Use |
+|---|---|
+| `summer_set_prop` | Set a typed property (Vector3, Color, etc.) using Godot's `str_to_var()`. |
+| `summer_set_resource_property` | Set a property on a nested resource (e.g., CollisionShape's `shape.radius`). |
+| `summer_inspect_resource` | Read a resource's properties. |
+| `summer_connect_signal` | Wire a signal between nodes. |
+
+### Project & input (2)
+
+| Tool | Use |
+|---|---|
+| `summer_project_setting` | Modify `project.godot` settings (rendering, physics). |
+| `summer_input_map_bind` | Bind input actions in InputMap. Folds in the legacy `add_action` step. |
+
+### Import pipeline (2)
+
+| Tool | Use |
+|---|---|
+| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run Godot's full import pipeline. |
+| `summer_import_from_url_batch` | Same, batched (single filesystem scan). |
+
+### Play / runtime (3)
+
+| Tool | Use |
+|---|---|
+| `summer_play` | Run the game. |
+| `summer_stop` | Stop the running game. |
+| `summer_is_running` | Check play state before deciding to call `summer_stop`. |
+
+### Diagnostics (5)
+
+| Tool | Use |
+|---|---|
+| `summer_get_diagnostics` | Aggregate error/warning summary. Call after every change. |
+| `summer_get_console` | Engine output panel. |
+| `summer_clear_console` | Clear before a fresh play, so post-run output is clean. |
+| `summer_get_debugger_errors` | Runtime errors with stack traces. |
+| `summer_get_script_errors` | Script compilation errors. |
+
+### Asset library (2)
+
+| Tool | Use |
+|---|---|
+| `summer_search_assets` | Free public asset search (community library + user's own). Sources: `library`, `community`, `my_assets`, `all`. |
+| `summer_import_asset` | Download a found asset and run import. |
+
+### Asset generation (4 — metered)
+
+| Tool | Use |
+|---|---|
+| `summer_generate_image` | AI image gen. |
+| `summer_generate_3d` | Image-to-3D. |
+| `summer_generate_audio` | SFX / music gen. |
+| `summer_generate_video` | Video gen. |
+
+### Job tracking (2)
+
+| Tool | Use |
+|---|---|
+| `summer_check_job` | Poll a generation job. |
+| `summer_batch` | Run multiple ops as a transaction. |
+
+### Meta (2)
+
+| Tool | Use |
+|---|---|
+| `summer_get_project_context` | Project structure summary — call at start of session. |
+| `summer_get_agent_playbook` | Daily operating contract — call at start of session. |
+
+## Common pattern
+
+Every scene-touching skill should follow this loop:
+
+1. `summer_get_project_context` — orient.
+2. `summer_get_agent_playbook` — read the rules.
+3. `summer_get_scene_tree` — see what's there.
+4. (mutations: `summer_add_node`, `summer_set_prop`, `summer_connect_signal`, ...)
+5. `summer_save_scene` — persist.
+6. `summer_get_script_errors` — catch GDScript breakage.
+7. `summer_play` → `summer_get_debugger_errors` → `summer_stop` if verifying runtime.
+
+## Trap: silent-fail on inline sub-resource SetResourceProperty
+
+`summer_set_resource_property` will silently fail if the target resource is an inline `sub_resource` rather than a standalone `.tres`. If you need to set nested properties (mesh size, shape radius, material color), make the resource standalone first:
+
+```
+summer_add_node(... mesh = "BoxMesh" ...)         # creates inline sub_resource
+# WRONG: summer_set_resource_property("./Box", "mesh.size", "Vector3(2,2,2)")  ← silently fails
+# RIGHT: save mesh as .tres, then SetResourceProperty
+```
+
+This is documented in `public/knowledge/asset_pipeline.json`.

package/skills/_shared/template-registry.md

@@ -0,0 +1,40 @@
+# Template Registry
+
+> Skills cross-link to template repos via the `template-id` frontmatter field. This file is the canonical mapping. When a template repo moves, update one entry here.
+
+## Template IDs
+
+| template-id | Description | Repo |
+|---|---|---|
+| `template-3d-fps` | First-person shooter starter (CharacterBody3D, Camera3D, input, sample level) | https://github.com/SummerEngine/FPS-template-Summer-Engine |
+| `template-3d-tps` | Third-person shooter starter | https://github.com/SummerEngine/tps-template |
+| `template-2d-platformer` | 2D platformer starter (TileMap, CharacterBody2D, parallax) | TBD |
+| `template-3d-platformer` | 3D platformer starter (jump, double jump, simple level) | TBD |
+| `template-top-down-rpg` | Top-down ARPG starter | TBD |
+| `template-2d-deckbuilder` | Deck-builder starter (card, deck, draw, discard, energy) | TBD (prototype lives at `templates/template-2d-deckbuilder/`) |
+| `template-tower-defense` | Tower defense starter | TBD |
+| `template-walking-sim` | Walking sim starter | TBD |
+
+## Convention
+
+Each template is its own GitHub repo, MIT licensed, kept small (< 50 MB). Templates ship working code. Skills describe patterns. A skill links to the matching template via:
+
+```markdown
+## Want a working starter?
+
+This skill describes the pattern. For a runnable project, use the template:
+
+→ **template-id**: `template-3d-fps`
+→ **Repo**: https://github.com/SummerEngine/FPS-template-Summer-Engine
+→ **Bootstrap**: `summer template clone template-3d-fps my-fps`
+```
+
+## Linter check
+
+The `_meta/skill-test/SKILL.md` static linter validates that any `template-id:` declared in a skill's frontmatter exists in the table above.
+
+## Adding a template
+
+1. Create a new GitHub repo under `SummerEngine` org, MIT license.
+2. Add the `template-id`, description, and repo URL to the table above.
+3. Reference the `template-id` from any relevant skill.

package/skills/_tests/runner.md

@@ -0,0 +1,90 @@
+# Skill Test Runner
+
+> How `/skill-test` and `/skill-improve` actually work in this repo. Read this if you're authoring a behavioral spec or trying to understand the test pipeline.
+
+## Architecture
+
+```
+skills/
+├── _meta/skill-test/SKILL.md        # the linter + spec runner (3 modes)
+├── _meta/skill-improve/SKILL.md     # the eval harness for iteration
+└── _tests/
+    ├── runner.md                    # this file
+    ├── specs/
+    │   └── <skill-name>.md          # behavioral specs, one per non-_meta skill
+    └── runs/                        # generated, gitignored
+        └── <skill-name>/
+            ├── baseline/
+            └── proposed/
+```
+
+## What a spec looks like
+
+Every spec at `_tests/specs/<skill-name>.md` has:
+
+- A `## Fixture` block describing the starting state and tool availability.
+- One or more `## Case <N>: <Happy | Failure | Edge>` blocks.
+- Each Case has `**Input:**`, `**Expected MCP tool sequence:**`, and `**Assertions:**` (markdown checkboxes).
+
+Reference: `_tests/specs/fps-controller.md` (canonical example).
+
+## Static linter (cheap, every commit)
+
+Run by `/skill-test <name>` in `static` mode. Pure markdown reasoning — no subagents, no tool calls.
+
+The 7 checks live in `_meta/skill-test/SKILL.md` § "Mode: static". Re-read that for the canonical list.
+
+## Spec runner (medium, weekly)
+
+Run by `/skill-test <name>` in `spec` mode. Reads SKILL.md and the matching spec, reasons over the assertions. No execution.
+
+This catches drift between what the skill says and what its spec demands. It does not catch agent variation — for that, use `/skill-improve`.
+
+## Eval harness (expensive, on-demand)
+
+Run by `/skill-improve <name>`. Spawns parallel `Task` subagents with the current SKILL.md vs. proposed SKILL.md. Compares outputs against assertions. Decides which wins. Writes results to `_tests/runs/<name>/`.
+
+Use this when:
+- A skill consistently fails its spec but you can't tell why from reading it.
+- You're rewriting a skill and want a regression baseline.
+- A skill is critical (top of `catalog.yaml` recommended set) and overdue for an audit.
+
+## Authoring a spec
+
+Five-minute job per skill. Copy this template:
+
+```markdown
+# Skill Spec: /<skill-name>
+
+## Fixture
+- <starting state of the project / scene>
+- Available tools: Summer MCP <yes|no>, host file edits <yes|no>
+
+## Case 1: Happy Path
+**Input:** "<the most common user prompt that should trigger this skill>"
+
+**Expected MCP tool sequence (in order):**
+1. summer_<tool>(...)
+2. summer_<tool>(...)
+
+**Assertions:**
+- [ ] <observable outcome 1>
+- [ ] <skill asks "May I" before any user-visible write>
+- [ ] <skill never calls the silent-fail anti-pattern>
+
+## Case 2: Failure Path
+**Fixture:** <something missing or already present that should change behavior>
+**Input:** "<edge prompt>"
+**Expected:** <how the skill should adapt — clarify, defer, fail-safe>
+
+## Case 3: Edge Case
+**Fixture:** ...
+**Input:** "<unusual prompt>"
+**Expected:** ...
+```
+
+Aim for 2–4 cases per skill. More than 4 = the skill is doing too much and should be split.
+
+## Catalog last-tested
+
+Every successful run of `/skill-improve` (or a manual sign-off) should bump `last-tested:` in `catalog.yaml`. The audit mode of `/skill-test` flags skills with stale `last-tested:` fields.

package/skills/_tests/specs/3d-lighting.md

@@ -0,0 +1,19 @@
+# Skill Spec: /3d-lighting
+
+> Stub spec. Expand with Happy / Failure / Edge cases. See `fps-controller.md` for the canonical format.
+
+## Fixture
+
+- TBD
+
+## Case 1: Happy Path
+
+**Input:** "<typical user prompt>"
+
+**Expected MCP tool sequence (in order):**
+
+1. TBD
+
+**Assertions:**
+
+- [ ] TBD

package/skills/_tests/specs/asset-strategy.md

@@ -0,0 +1,19 @@
+# Skill Spec: /asset-strategy
+
+> Stub spec. Expand with Happy / Failure / Edge cases. See `fps-controller.md` for the canonical format.
+
+## Fixture
+
+- TBD
+
+## Case 1: Happy Path
+
+**Input:** "<typical user prompt>"
+
+**Expected MCP tool sequence (in order):**
+
+1. TBD
+
+**Assertions:**
+
+- [ ] TBD