summer-engine 3.0.0 → 3.2.0

package/library/skills/character-movement/references/movement-3d.md

@@ -0,0 +1,136 @@
+# 3D Controllers: First + Third Person
+
+Both build on the minimal 3D walk in SKILL.md. The difference is entirely the
+camera rig and how look rotation is split across nodes.
+
+## First-person node layout (non-negotiable)
+
+```
+Player (CharacterBody3D)          # yaw (horizontal look) rotates THIS
+  CollisionShape3D                # CapsuleShape3D, radius 0.35, height 1.8
+  Head (Node3D)                   # y = 1.5; pitch (vertical look) rotates THIS
+    Camera3D                      # fov 70-75
+      WeaponHolder (Node3D)       # weapons/tools ride here
+```
+
+Yaw on the body, pitch on the Head. Never pitch the body (gimbal lock + physics
+tilt). Camera is a child of Head so it inherits both rotations.
+
+```gdscript
+extends CharacterBody3D
+
+@export var speed: float = 5.0
+@export var sprint_speed: float = 8.0
+@export var jump_velocity: float = 4.5
+@export var mouse_sensitivity: float = 0.002
+
+@onready var head: Node3D = $Head
+var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")
+
+func _ready() -> void:
+	Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
+
+func _unhandled_input(event: InputEvent) -> void:
+	if event is InputEventMouseMotion:
+		rotate_y(-event.relative.x * mouse_sensitivity)
+		head.rotate_x(-event.relative.y * mouse_sensitivity)
+		head.rotation.x = clampf(head.rotation.x, -PI / 2.0, PI / 2.0)
+	if event.is_action_pressed("ui_cancel"):
+		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
+
+func _physics_process(delta: float) -> void:
+	if not is_on_floor():
+		velocity.y -= gravity * delta
+	if Input.is_action_just_pressed("jump") and is_on_floor():
+		velocity.y = jump_velocity
+	var cur_speed := sprint_speed if Input.is_action_pressed("sprint") else speed
+	var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+	var direction := (transform.basis * Vector3(input_dir.x, 0.0, input_dir.y)).normalized()
+	if direction:
+		velocity.x = direction.x * cur_speed
+		velocity.z = direction.z * cur_speed
+	else:
+		velocity.x = move_toward(velocity.x, 0.0, cur_speed)
+		velocity.z = move_toward(velocity.z, 0.0, cur_speed)
+	move_and_slide()
+```
+
+## Crouch
+
+Keep two collision shapes (standing + crouching), toggle `disabled`, and a
+`RayCast3D` pointing up (`CeilingCheck`) so you cannot stand up under a ceiling.
+Lerp the Head y from 1.5 to ~0.9 for a smooth crouch, not a snap.
+
+## Headbob (optional polish)
+
+Drive the Camera's local y with `sin(time * bob_freq) * bob_amp` scaled by
+horizontal speed, only while `is_on_floor()`. Keep amp under 0.08 or it nauseates.
+
+## Third-person node layout
+
+```
+Player (CharacterBody3D)
+  CharacterRotationRoot (Node3D)   # only this visual node yaws toward movement
+    character.tscn                  # normalized role-neutral visual package
+  CameraController (Node3D)
+    SpringArm3D                     # extends behind the -Z-facing visual on local +Z
+      Camera3D
+```
+
+The `SpringArm3D` is the whole trick: it raycasts from the pivot to the camera
+and shortens when a wall is in the way, so the camera never clips into geometry.
+Set its `collision_mask` to your Level layer only (not the player).
+
+Third-person differences from FPS:
+- Mouse motion rotates the `CameraController` (orbit), not the body.
+- The visual wrapper rotates to face the MOVEMENT direction, decoupled from the camera.
+  Because imported characters face Godot forward `-Z`, lerp
+  `CharacterRotationRoot.rotation.y` toward `atan2(-direction.x, -direction.z)`.
+- Rotate only `CharacterRotationRoot.rotation.y`. Do not yaw the CharacterBody3D or add a
+  compensating 180-degree model rotation. The package already normalizes forward to `-Z`.
+- Keep the third-person camera behind the character on the camera rig's local `+Z` side.
+- Camera direction drives movement basis: build `direction` from the spring-arm's
+  global basis, flattened to the XZ plane, so "forward" means "where the camera
+  looks".
+
+## Canonical humanoid animation states
+
+Keep translation in the controller and use package animations only as in-place visuals.
+For a standard playable third-person character, read and copy
+`default-third-person-controller.gd`. It already loads exact semantic roles
+from `character.json`, selects state after `move_and_slide()`, gives airborne
+Jump highest priority, changes clips only when state changes, uses camera-relative
+movement, and turns only the normalized `-Z` visual root. Do not reassemble the
+controller from partial examples.
+
+Do not advance the `CharacterBody3D` from animation root translation. Rotate only the
+visual child when movement is non-zero, and keep the last facing direction while idle.
+
+## Legacy clip-name compatibility only
+
+Use substring discovery only for old, non-package GLBs that have no manifest. Resolve Jump
+before Run and claim each real clip at most once. Never use this for a canonical package:
+
+```gdscript
+func resolve_legacy_roles(player: AnimationPlayer) -> Dictionary:
+	var result: Dictionary = {}
+	var used_clips: Dictionary = {}
+	for role in [&"jump", &"idle", &"walk", &"run"]: # Jump must precede Run.
+		for clip in player.get_animation_list():
+			if used_clips.has(clip):
+				continue
+			if String(clip).to_lower().contains(String(role)):
+				result[role] = clip
+				used_clips[clip] = true
+				break
+	return result
+```
+
+Validate every requested role after legacy resolution. Do not fall back from Jump to Walk
+or Run, and do not reuse one clip for multiple roles.
+
+## Shared traps
+
+- Capture/release the mouse as a pair or you trap the player (see SKILL.md).
+- Sprint reads an unbound `sprint` action = silent no-op; bind it first.
+- Spring arm with the wrong mask collides with the player and jams at length 0.

package/library/skills/character-movement/references/platformer-feel.md

@@ -0,0 +1,83 @@
+# Platformer Feel
+
+The base controller in SKILL.md runs, but a raw `is_on_floor()` jump feels stiff
+and unforgiving. These four additions are what separate a prototype from a game
+that feels good. Add them in this order; each is independent.
+
+## Coyote time
+
+Let the player jump for a few frames AFTER walking off a ledge. Without it, jumps
+near edges feel like the game ate the input.
+
+```gdscript
+@export var coyote_time: float = 0.1
+var _coyote_timer: float = 0.0
+
+func _physics_process(delta: float) -> void:
+	if not is_on_floor():
+		velocity.y += gravity * delta
+		_coyote_timer -= delta
+	else:
+		_coyote_timer = coyote_time
+	# jump check uses _coyote_timer > 0.0 instead of is_on_floor()
+```
+
+## Jump buffering
+
+If the player presses jump a few frames BEFORE landing, remember it and fire on
+touchdown. Without it, fast players feel like jumps get dropped.
+
+```gdscript
+@export var jump_buffer: float = 0.1
+var _buffer_timer: float = 0.0
+
+func _physics_process(delta: float) -> void:
+	if Input.is_action_just_pressed("jump"):
+		_buffer_timer = jump_buffer
+	_buffer_timer -= delta
+	if _buffer_timer > 0.0 and _coyote_timer > 0.0:
+		velocity.y = jump_velocity
+		_buffer_timer = 0.0
+		_coyote_timer = 0.0
+```
+
+## Variable jump height
+
+Tap = short hop, hold = full jump. Cut upward velocity when the button releases.
+
+```gdscript
+	if Input.is_action_just_released("jump") and velocity.y < 0.0:
+		velocity.y *= 0.4
+```
+
+## Asymmetric gravity (fall faster than you rise)
+
+A heavier fall gravity is the single biggest feel upgrade. Rising floaty, falling
+snappy reads as responsive.
+
+```gdscript
+@export var fall_multiplier: float = 1.6
+
+func _physics_process(delta: float) -> void:
+	var g := gravity * (fall_multiplier if velocity.y > 0.0 else 1.0)
+	if not is_on_floor():
+		velocity.y += g * delta
+```
+
+## One-way platforms
+
+Use a `CollisionPolygon2D`/`CollisionShape2D` on a platform with
+`one_way_collision = true` in the platform's collision shape. Drop through by
+briefly disabling the player's collision with that layer, or move the player to a
+lower collision layer while `move_down` is held.
+
+## Tuning starting points
+
+| Feel | speed | jump_velocity | gravity scale |
+|------|-------|---------------|---------------|
+| Tight/precise | 180 | -320 | 1.0 (fall 1.8) |
+| Floaty/explorer | 220 | -420 | 0.7 (fall 1.3) |
+| Fast/action | 300 | -380 | 1.0 (fall 2.0) |
+
+Never ship default gravity 980 with a -350 jump and call it done - that is the
+"why does my jump feel bad" default. Tune fall_multiplier first.

package/library/skills/character-movement/resource.yaml

@@ -0,0 +1,40 @@
+id: skill/character-movement
+kind: skill
+version: 1.2.1
+summary: "Player controllers for 2D and 3D, plus the canonical third-person controller for Summer humanoid packages: movement owns translation, clips follow state."
+use_when:
+  - building or fixing player movement — gravity, collision, side-scroller, top-down, or 3D walk
+  - wiring an imported Summer character package (character.tscn) as the playable third-person player
+  - walk, run, and jump animation states, facing, or mouse look for a player controller
+  - the jump feels bad — coyote time, jump buffering, variable jump height, one-way platforms
+do_not_use_when:
+  - a production first-person shooter controller with air control and external velocity — use fps-controller
+  - Celeste-style momentum precision platforming with dash and wall climb — use celeste-momentum-platforming
+facets:
+  lifecycle:
+    - build
+  domains:
+    - character-controller
+    - gameplay
+    - 2d
+    - 3d
+  modalities:
+    - scripts
+    - scenes
+    - animation
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/make-game
+    - skill/camera-rigs
+    - skill/combat-basics
+    - skill/fps-controller
+    - skill/celeste-momentum-platforming
+    - skill/character-animation-wiring
+    - skill/character-model
+    - skill/playtesting-a-feature
+source: official
+license: MIT
+status: preview
+recommended: false

package/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

package/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

package/library/skills/combat-basics/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: combat-basics
+description: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: gameplay-mechanics
+user-invocable: false
+allowed-tools: Read Grep summer_read_file summer_write_file summer_replace_text summer_add_node summer_set_prop summer_batch summer_project_setting summer_save_scene summer_get_script_errors summer_get_diagnostics
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# Combat Basics
+
+The Godot combat pattern is hitbox + hurtbox + health, wired by signals. Build it
+component-first: the same three pieces work for player, enemies, and destructibles.
+
+## The layer model (set this up first)
+
+Attacks are `Area2D`/`Area3D`, not solid bodies. A hitbox (the attack) detects a
+hurtbox (the thing that can be hurt) via collision layers/masks:
+
+| Node | on layer | masks (detects) |
+|------|----------|-----------------|
+| Player hurtbox | PlayerHurt | EnemyHit |
+| Player hitbox (sword) | PlayerHit | EnemyHurt |
+| Enemy hurtbox | EnemyHurt | PlayerHit |
+| Enemy hitbox | EnemyHit | PlayerHurt |
+
+Rule: every combat Area masks only the OPPOSING side. This is why the player's
+sword never damages the player. An Area reports `area_entered` only for areas on
+a layer in its OWN mask, so the hurtbox below (which listens) must mask the
+opposing hitbox layer; a hurtbox with an empty mask never registers a hit.
+
+Name the layers once so you are not counting bits by hand —
+`summer_project_setting(key="layer_names/2d_physics/layer_4", value="PlayerHit")`
+(use `layer_names/3d_physics/...` for 3D), one call per layer.
+
+## Health component (reuse everywhere)
+
+Attach to any damageable node. It owns HP and fires signals; UI and death logic
+just listen.
+
+```gdscript
+class_name Health extends Node
+
+signal damaged(amount: int, current: int)
+signal died
+
+@export var max_health: int = 100
+var current: int
+
+func _ready() -> void:
+	current = max_health
+
+func take_damage(amount: int) -> void:
+	if current <= 0:
+		return
+	current = maxi(0, current - amount)
+	damaged.emit(amount, current)
+	if current == 0:
+		died.emit()
+
+func heal(amount: int) -> void:
+	current = mini(max_health, current + amount)
+```
+
+## Hurtbox -> Health
+
+The hurtbox is an Area on the body; when a hitbox overlaps it, read the hitbox's
+damage and route it to the Health node.
+
+```gdscript
+extends Area2D   # Hurtbox, child of the character
+
+@export var health_path: NodePath
+@onready var health: Health = get_node(health_path)
+
+func _ready() -> void:
+	area_entered.connect(_on_area_entered)
+
+func _on_area_entered(hitbox: Area2D) -> void:
+	if hitbox.has_method("get_damage"):
+		health.take_damage(hitbox.get_damage())
+```
+
+## Hitbox
+
+```gdscript
+extends Area2D   # Hitbox, child of weapon or attack
+
+@export var damage: int = 10
+func get_damage() -> int:
+	return damage
+```
+
+Enable the hitbox only during the active frames of a swing (toggle
+`monitoring`/`monitorable` or the CollisionShape's `disabled`), driven by an
+AnimationPlayer track. An always-on melee hitbox hits on touch, which feels wrong.
+
+## Death, knockback, feedback
+
+- On `died`: `queue_free()`, spawn a death VFX, drop loot, `add_kill()` on your
+  game manager. For the player, switch to a GAME_OVER state instead of freeing.
+- Knockback: push the victim `velocity = (victim.global_position -
+  attacker.global_position).normalized() * force`, decay it each frame.
+- Every hit needs feedback or it reads as broken: a flash (`modulate` to white for
+  0.05s), a damage number (floating Label), a small screen shake, a hitstop
+  (`Engine.time_scale = 0.05` for one frame). Silent damage feels like a no-op.
+
+## Projectiles (short version)
+
+An `Area2D/3D` that moves forward and calls `take_damage` on what it hits, then
+frees itself.
+
+```gdscript
+extends Area2D   # projectile
+
+@export var speed: float = 600.0
+@export var damage: int = 15
+var direction: Vector2 = Vector2.RIGHT
+
+func _ready() -> void:
+	body_entered.connect(_on_hit)
+	get_tree().create_timer(3.0).timeout.connect(queue_free)  # lifetime
+
+func _physics_process(delta: float) -> void:
+	position += direction * speed * delta
+
+func _on_hit(body: Node) -> void:
+	if body.has_node("Health"):
+		body.get_node("Health").take_damage(damage)
+	queue_free()
+```
+
+Homing, piercing, AoE, and pooling many bullets are in this skill's
+`references/projectiles-and-aoe.md` — read it only when you need one of those.
+
+## Traps
+
+- Hitbox on the wrong layer/mask = no hits or friendly fire. Verify the layer
+  table above before debugging the scripts.
+- Two Areas with neither `monitoring` nor `monitorable` never report overlap.
+- Freeing a node mid-signal can error - defer with `queue_free()` (safe), not
+  `free()`.
+- Damaging in `_process` instead of on overlap = continuous per-frame damage.
+
+## Applying it in Summer Engine
+
+- Scripts (`health.gd`, `hurtbox.gd`, `hitbox.gd`, `projectile.gd`) are files:
+  create with `summer_write_file(path=..., content=..., create_only=true)`,
+  change with `summer_replace_text`. Check each with `summer_get_script_errors`.
+- Nodes (the Area, its CollisionShape, the Health child) are scene mutations:
+  `summer_add_node` / `summer_set_prop` with `scenePath`, or one `summer_batch`
+  with `AddNode` / `SetProp` ops so the scene saves once. Set `collision_layer`
+  and `collision_mask` as integers (bit values), not layer names.
+- Prove a hit with a `RunVerification` probe (see `playtesting-a-feature`):
+  spawn or find one enemy, press the attack action, `report()` the enemy's
+  `Health.current` before and after. A static scene check cannot show that a
+  hit registered.

package/library/skills/combat-basics/references/projectiles-and-aoe.md

@@ -0,0 +1,100 @@
+# Projectiles, AoE, and Pooling
+
+Extends the base projectile in SKILL.md. Pick the behavior you need; they compose.
+
+## Homing
+
+Steer the direction toward the nearest target each frame. Turn rate keeps it from
+being unavoidable.
+
+```gdscript
+@export var turn_rate: float = 4.0
+var target: Node2D
+
+func _physics_process(delta: float) -> void:
+	if is_instance_valid(target):
+		var desired := (target.global_position - global_position).normalized()
+		direction = direction.lerp(desired, turn_rate * delta).normalized()
+	position += direction * speed * delta
+	rotation = direction.angle()
+```
+
+Find the nearest target by querying a group: iterate
+`get_tree().get_nodes_in_group("enemies")` and keep the min `distance_to`. For
+hundreds of enemies, cache the list and refresh every few frames, not per bullet.
+
+## Piercing
+
+Do not free on first hit; count hits and track who was already hit.
+
+```gdscript
+@export var pierce: int = 3
+var _hit: Array = []
+
+func _on_hit(body: Node) -> void:
+	if body in _hit:
+		return
+	_hit.append(body)
+	_apply_damage(body)
+	pierce -= 1
+	if pierce <= 0:
+		queue_free()
+```
+
+## Area of effect (explosion)
+
+Spawn an Area with a large CollisionShape for one frame, damage everything
+overlapping, then free. Scale damage by distance for a shockwave feel.
+
+```gdscript
+func explode() -> void:
+	for body in $Blast.get_overlapping_bodies():
+		if body.has_node("Health"):
+			var t := 1.0 - global_position.distance_to(body.global_position) / radius
+			body.get_node("Health").take_damage(int(max_damage * maxf(t, 0.2)))
+	spawn_vfx()
+	queue_free()
+```
+
+Ground DOT (burning patch): an Area that ticks damage on a `Timer.timeout` to
+bodies currently inside it, for a lifetime, then frees.
+
+## Object pooling (many projectiles)
+
+Instancing and freeing hundreds of bullets per second stutters. Reuse a fixed pool.
+
+```gdscript
+extends Node2D   # BulletPool autoload or level node
+
+@export var bullet_scene: PackedScene
+@export var pool_size: int = 200
+var _pool: Array[Node2D] = []
+var _next: int = 0
+
+func _ready() -> void:
+	for i in pool_size:
+		var b := bullet_scene.instantiate()
+		b.set_process(false)
+		b.hide()
+		add_child(b)
+		_pool.append(b)
+
+func fire(pos: Vector2, dir: Vector2) -> void:
+	var b := _pool[_next]
+	_next = (_next + 1) % pool_size
+	b.global_position = pos
+	b.direction = dir
+	b.set_process(true)
+	b.show()
+	# bullet hides + set_process(false) instead of queue_free on hit/lifetime
+```
+
+Deactivate (hide + `set_process(false)`) instead of freeing; the pool recycles the
+oldest. This is how survivors-style games sustain thousands of projectiles.
+
+## Traps
+
+- Homing with no turn cap = undodgeable and unfun. Cap `turn_rate`.
+- Pooled bullets that `queue_free()` defeat the pool - hide and disable instead.
+- AoE that reads overlaps in `_process` re-damages every frame; do it once.
+- Distance-scaled damage with no floor (`maxf(t, 0.2)`) makes edges deal 0.

package/library/skills/combat-basics/resource.yaml

@@ -0,0 +1,34 @@
+id: skill/combat-basics
+kind: skill
+version: 1.0.0
+summary: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+use_when:
+  - adding attacks, health and damage, or enemies that can be hit and hit back
+  - adding projectiles or bullets — homing, piercing, area-of-effect, or pooling hundreds of them
+  - wiring death and respawn, or debugging hits that never land or friendly fire
+do_not_use_when:
+  - auto-fire weapons that over-commit or overkill targets — that is the pending-damage pattern in auto-fire-targeting
+  - hits work but feel weak or floaty — tune the feedback layer with game-feel or debugging-game-feel
+facets:
+  lifecycle:
+    - build
+  domains:
+    - gameplay
+    - scripting
+    - game-design
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/make-game
+    - skill/character-movement
+    - skill/game-feel
+    - skill/auto-fire-targeting
+    - skill/design-npc
+source: official
+license: MIT
+status: preview
+recommended: false

package/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

package/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

package/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

package/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

package/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

package/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

package/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

package/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

package/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

package/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