SummerEngine · mathias-heide · Sep 11, 2026 · Sep 11, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,7 @@ All notable changes to summer-engine will be documented here. Following [Keep a
 ## [3.1.1] - 2026-09-11
 
 ### Fixed
+- Skill descriptions no longer blow the hosts' skills context budget. Every SKILL.md description is now the skill's 160-character `summary` (94 skills: 13k characters, about 3.3k tokens, down from 32k characters). Codex had started truncating descriptions and Claude Code's budget is about 15k characters. Trigger phrases live in the skill body; `validate-library` fails when a description and its summary differ.
 - `summer setup goose` / `hermes` on an empty config wrote the file as one flow mapping; new files are block-style YAML.
 
 ### Changed

diff --git a/docs/SKILLS.md b/docs/SKILLS.md
@@ -84,6 +84,13 @@ guidance, and `--stable-only` skips it; `deprecated` installs only by name),
 
 ## Authoring rules
 
+- **The SKILL.md `description` is the resource `summary`, verbatim** (≤160 chars).
+  Hosts inject every installed skill's name and description into every
+  session; Codex truncates past its budget and Claude Code's budget is about
+  15k characters for all skills together. Ninety-plus skills only fit when
+  each description is one short line. Put trigger phrases and examples in the
+  skill body, not the description. `npm run validate:library` enforces the match.
+
 1. **Specialist skills:** narrow technical knowledge, auto-trigger via rich `description:`. Set `user-invocable: false`.
 2. **Workflow skills:** action-verb names (`/debug`, `/play`), open with one clarifying question, orchestrate specialists. Set `user-invocable: true`.
 3. SKILL.md <= 500 lines. Push shared detail into `library/references/`.

diff --git a/library/skills/3d-lighting/SKILL.md b/library/skills/3d-lighting/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: 3d-lighting
-description: Use when setting up lighting in a Summer Engine 3D scene — adding lights, configuring WorldEnvironment, sky, or shadows. Covers DirectionalLight3D versus Omni versus Spot, shadow tuning, ambient and sky-driven lighting, and the current Summer rendering conventions. Trigger on "lighting", "shadows", "WorldEnvironment", "sun", "ambient", "sky", "light".
+description: "Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting

diff --git a/library/skills/adaptive-music/SKILL.md b/library/skills/adaptive-music/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: adaptive-music
-description: Use when wiring music stems to game state — combat / explore / boss / tension crossfades on a shared bus. Pairs generated stems with a state machine and AudioBus structure. Trigger on "adaptive music", "dynamic music", "music changes when combat starts", "layered music", "vertical music", "wire stems".
+description: "Wire music stems to game state — combat/explore/boss/tension crossfades on a shared bus, paired with a state machine and AudioBus structure."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

diff --git a/library/skills/agent-playtesting/SKILL.md b/library/skills/agent-playtesting/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: agent-playtesting
-description: Use when proving a gameplay feature, reproducing a bug, or comparing two variants by driving the LIVE running game yourself — deterministic launch (seed, fixed_fps, offscreen instances), frame-stamped probes before and after every action, exact frame stepping, scripted or recorded input. The doctrine behind summer_game_probe, summer_game_input, summer_game_control and the summer_runtime_* tools.
+description: "Playtest by driving the LIVE game — deterministic launch, frame-stamped probes before/after each action, exact frame steps, scripted or recorded input."
 ---
 
 # Agent Playtesting

diff --git a/library/skills/ambient-bed/SKILL.md b/library/skills/ambient-bed/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ambient-bed
-description: Use when generating a long looping location ambience — forest at dawn, dungeon air, city street, spaceship hum, cave drip. Non-melodic, low-energy, never draws attention. Wires as a looping AudioStreamPlayer on the Ambient bus with a marked seamless loop. Trigger on "ambient bed", "room tone", "background ambience", "forest ambience", "dungeon air", "make it sound like a cave".
+description: "Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

diff --git a/library/skills/animated-loop/SKILL.md b/library/skills/animated-loop/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: animated-loop
-description: Use when generating a short looping video clip — splash screen background, animated logo backdrop, idle title-screen footage, looping environment ambience. Output must loop seamlessly and is wired as a VideoStreamPlayer with autoplay and loop set true. Trigger on "looping background", "splash loop", "title screen video", "animated backdrop", "menu background loop", "ambient loop video", "looping clip", "seamless loop".
+description: "Generate a short seamlessly-looping video clip — splash background, animated logo backdrop, idle title-screen footage — wired as a looping VideoStreamPlayer."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video

diff --git a/library/skills/animation-tree/SKILL.md b/library/skills/animation-tree/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: animation-tree
-description: Use when the user has clips on a character and needs them to play in response to gameplay — idle/walk/run blend, attacks that interrupt locomotion, hit reactions that override everything. Designs and wires Summer Engine AnimationTree state machines and blend trees. Trigger on "AnimationTree", "state machine", "blend tree", "transition", "play animation when", "character keeps T-posing", "wire animations".
+description: "Design and wire AnimationTree state machines and blend trees so clips respond to gameplay — locomotion blends, attack interrupts, hit reactions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation

diff --git a/library/skills/art-direction/SKILL.md b/library/skills/art-direction/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: art-direction
-description: Use when defining the visual style of the game — references, palette, mood, lighting plan, post-processing, do/don't list. Outputs an art bible at `.summer/art-bible.md`. Trigger on "art direction", "art bible", "visual style", "color palette", "what should it look like", "the look".
+description: "Define the game's visual style — references, palette, mood, lighting plan, post-processing, do/don't list — output as an art bible at .summer/art-bible.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting

diff --git a/library/skills/asset-strategy/SKILL.md b/library/skills/asset-strategy/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: asset-strategy
-description: Use when planning asset creation, picking an asset pipeline, or routing an "I need a [thing]" request to the right specialist skill. Disambiguates between 2D / 3D / audio / video / VFX / animation pipelines and dispatches via the Skill tool. Trigger on "assets", "asset pipeline", "make a model", "I need a sound", "create concept art", "generate something", broad creative requests.
+description: "Route any 'I need a [thing]' asset request to the right specialist skill — disambiguates 2D / 3D / audio / video / VFX / animation pipelines."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: asset-pipeline

diff --git a/library/skills/audio-direction/SKILL.md b/library/skills/audio-direction/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: audio-direction
-description: Use when defining the sonic identity — music style, instruments, SFX vocabulary, dynamic music plan. Outputs an audio bible at `.summer/audio-bible.md`. Trigger on "audio direction", "audio bible", "music style", "sound design", "what should it sound like", "dynamic music".
+description: "Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

diff --git a/library/skills/auto-fire-targeting/SKILL.md b/library/skills/auto-fire-targeting/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: auto-fire-targeting
-description: Use when designing or fixing the targeting system for an auto-fire weapon (survivors-genre, top-down ARPG, tower-defense). Covers the pending-damage pattern that prevents over-commit when bullet flight time is longer than fire rate. Trigger on "auto-fire", "auto-aim", "weapon targeting", "targeting", "wasted bullets", "overkill", "damage prediction", "survivors weapon".
+description: "Design or fix auto-fire weapon targeting (survivors, top-down ARPG, tower defense) — the pending-damage pattern that prevents over-commit and overkill."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: gameplay-mechanics

diff --git a/library/skills/brainstorm-game/SKILL.md b/library/skills/brainstorm-game/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: brainstorm-game
-description: Use when the user wants help deciding what game to make, scoping a new project, or turning a vague idea into a buildable plan. Walks through genre, scope, core loop, mechanics, and art direction, then writes a 1-page brief to `.summer/GameSoul.md`. Trigger on "brainstorm a game", "what should I make", "I want to make a game", "help me scope", "new game idea".
+description: "Turn a vague idea into a buildable plan — genre, scope, core loop, mechanics, art direction — written as a 1-page brief to .summer/GameSoul.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project

diff --git a/library/skills/brainstorming/SKILL.md b/library/skills/brainstorming/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: brainstorming
-description: "Use when starting creative work — designing a game, picking a mechanic, building features or components, modifying behavior. Explores user intent, requirements, and design before implementation. MUST run before any creative work."
+description: "Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior."
 ---
 
 # Brainstorming Ideas Into Designs

diff --git a/library/skills/browse-templates/SKILL.md b/library/skills/browse-templates/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: browse-templates
-description: Use when the user wants to see available Summer Engine project templates, start from an existing template, or asks "what templates exist?" — lists the pinned template registry via `summer list templates`, presents the choices, and creates a project from the chosen template via `summer create <slug> <project-name>`. Trigger on "templates", "starter", "boilerplate", "from a template", "what's available", "show me templates", "third-person", "platformer", "multiplayer starter".
+description: "List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project

diff --git a/library/skills/celeste-momentum-platforming/SKILL.md b/library/skills/celeste-momentum-platforming/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: celeste-momentum-platforming
-description: "Use when building or tuning Celeste-style momentum-based precision platformer movement in SummerEngine (Godot 4): tuned gravity/fall, run acceleration, variable-height jumps with coyote time, dashes, wall jumps/slides, climb stamina, and pixel-scale corner correction, using the exact tuning constants extracted from Celeste's open-source Player class."
+description: "Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction."
 license: MIT
 category: game-feel
 tags:

diff --git a/library/skills/character-animation-wiring/SKILL.md b/library/skills/character-animation-wiring/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: character-animation-wiring
-description: Use when a rigged, animated character is in the scene (Meshy rig + generated clips, or an imported GLB) and needs to be wired end to end — inspect the clips and bones that actually arrived, build idle/walk/run locomotion with blend times, method-track footsteps and attack frames, still poses and head tracking, blend-shape facial keys, root motion. Trigger on "wire the character", "hook up the animations", "make it walk around", "the GLB has animations", "footstep events", "attack frame", "root motion", "character slides while walking".
+description: "Wire a rigged, animated character end to end — inspect real clips and bones, locomotion state machine, method-track events, poses, blend shapes, root motion."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation

diff --git a/library/skills/character-model/SKILL.md b/library/skills/character-model/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: character-model
-description: Use when generating a humanoid character ready for animation — player avatar, NPC, enemy, boss, companion. Generates a T-pose reference image, gates an un-rigged preview past the user, then runs the Meshy auto-rig pass and wires the result as a CharacterBody3D (movement) or Node3D (cinematic). Trigger on "make a character", "generate the player", "I need an enemy model", "create an NPC", "rigged humanoid", "character with a skeleton", "model for animation".
+description: "Generate a rigged humanoid — player, NPC, enemy, boss — via T-pose reference, user-gated preview, and Meshy auto-rig, wired as CharacterBody3D or Node3D."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets

diff --git a/library/skills/character-portrait/SKILL.md b/library/skills/character-portrait/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: character-portrait
-description: Use when generating a single, polished bust/portrait of a character for dialogue UI, character-select screens, lore cards, or codex entries. One character, locked composition, VN-style. Trigger on "character portrait", "dialogue portrait", "VN portrait", "character bust", "headshot", "character select image", "lore card art".
+description: "Generate a single polished character bust for dialogue UI, character select, lore cards, or codex entries. One character, locked composition, VN-style."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

diff --git a/library/skills/cinematic-cutscene/SKILL.md b/library/skills/cinematic-cutscene/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: cinematic-cutscene
-description: Use when generating a non-interactive cutscene clip — opening scene, story beat, character intro, ending. Locks the look with a reference image, image-to-videos a 5-10s shot, optionally adds TTS dialogue, and wires it as a VideoStreamPlayer that fades in/out. Trigger on "cutscene", "intro cinematic", "opening scene", "ending cinematic", "story beat video", "character intro video", "in-engine cinematic", "non-playable scene".
+description: "Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video

diff --git a/library/skills/concept-art/SKILL.md b/library/skills/concept-art/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: concept-art
-description: Use when the user is exploring art direction — wants 3-4 rough variants of a character, environment, or prop to pick a vibe before committing to a final asset. Generates a batch of evocative concept images, not finals. Trigger on "concept art", "art direction", "explore the look", "give me some variants", "what could this character look like", "mood board", "rough sketches".
+description: "Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

diff --git a/library/skills/create-asset-sheet/SKILL.md b/library/skills/create-asset-sheet/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: create-asset-sheet
-description: Use when the user wants to generate a pack of 2D game assets from a single prompt — a tile sheet, UI kit, menu screen, character pack, or biome set. The skill plans the prompt, generates a coherent sheet, removes the background, vision-detects each item, classifies it, and saves as a single pack ArtAsset. Trigger on "asset sheet", "asset pack", "tile sheet", "tileset", "UI kit", "asset pack for", "make me a sheet of", "generate a bunch of <category> assets".
+description: "Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

diff --git a/library/skills/debug/SKILL.md b/library/skills/debug/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Use when the user reports a bug, crash, error, or unexpected behavior in a Summer project, before making code or scene changes. Runs a disciplined script-errors, console, debugger, hypothesis, fix, and verify loop. Trigger on "debug", "crash", "error", "broken", "not working", "freezes", "wrong".
+description: "Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging

diff --git a/library/skills/debugging-game-feel/SKILL.md b/library/skills/debugging-game-feel/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: debugging-game-feel
-description: Use when a gameplay feature works correctly but feels wrong — floaty jumps, mushy combat, sluggish camera, weightless impacts. Different from logical bug debugging; the bug is subjective and lives in tuning, timing, and feedback layers.
+description: "Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers."
 ---
 
 # Debugging Game Feel

diff --git a/library/skills/design-level/SKILL.md b/library/skills/design-level/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: design-level
-description: Use when designing a single level — layout, pacing, encounters, secrets, reward gating. Outputs a level design doc and a concrete node-tree skeleton for `summer_create_scene`. Trigger on "design a level", "design level 1", "tutorial level", "boss arena", "design the encounter", "make a level layout".
+description: "Design a single level — layout, pacing, encounters, secrets, reward gating — outputs a level design doc and a node-tree skeleton for summer_create_scene."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: level-design

diff --git a/library/skills/design-mechanic/SKILL.md b/library/skills/design-mechanic/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: design-mechanic
-description: Use when designing one specific game mechanic in detail — input, response, feedback, failure modes, depth, tunables. Outputs a design doc and a scaffolding-ready node-graph sketch + GDScript stub. Trigger on "design a mechanic", "how should X work", "design the parry", "design the dash", "design the inventory", "the loop is broken".
+description: "Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: gameplay-mechanics

diff --git a/library/skills/design-npc/SKILL.md b/library/skills/design-npc/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: design-npc
-description: Use when the user wants to design an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior. Walks perception, personality knobs, intent layer, action state machine, telegraphs, defeat handling, and group emergence — outputs a state-machine GDScript stub plus the recommended node tree. Trigger on "enemy", "NPC", "boss", "companion", "AI", "behavior", "mob", "perception", "design enemy".
+description: "Design enemy/NPC/boss/companion behavior — perception, personality, intent, action state machine, telegraphs — outputs a GDScript stub plus node tree."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ai-and-npcs

diff --git a/library/skills/diagnosing-perf-regressions/SKILL.md b/library/skills/diagnosing-perf-regressions/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: diagnosing-perf-regressions
-description: Use when frame rate, frame time, or load time has gotten worse since a known-good state — "it used to run at 60, now it's at 30." Focused on finding the cause of a regression, not general performance tuning.
+description: "Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning."
 ---
 
 # Diagnosing Performance Regressions

diff --git a/library/skills/dispatching-parallel-agents/SKILL.md b/library/skills/dispatching-parallel-agents/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: dispatching-parallel-agents
-description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+description: "Work 2+ independent tasks in parallel when they share no state and have no sequential dependencies."
 ---
 
 # Dispatching Parallel Agents

diff --git a/library/skills/driving-the-editor-ui/SKILL.md b/library/skills/driving-the-editor-ui/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: driving-the-editor-ui
-description: Use when a task is an editor-workflow step a human would do with the mouse — open Project Settings or a dock, switch the 2D/3D/Script main screen, toggle a panel, clear a dialog that is blocking the editor, read what a dock shows — and when deciding whether a request is UI work or scene work. Drives the editor by NAME through summer_ui_actions, reads it as structure through summer_ui_tree, activates the long tail by path through summer_ui_activate, and treats summer_ui_screenshot as the pixels-last fallback. Preview — the ops ship with a follow-up engine build.
+description: "Drive the editor UI by name: invoke actions, clear blocking dialogs, switch the main screen, read a dock — and route scene work to the scene tools instead."
 ---
 
 # Driving the Editor UI