First commit

.agents/skills/developing-godot-gdscript/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: developing-godot-gdscript
+description: Builds and refactors Godot 4 projects with idiomatic GDScript, scene composition, signals, and autoload patterns. Use when implementing gameplay, UI, tools, or architecture changes in Godot/GDScript repositories.
+---
+
+# Developing Godot With GDScript
+
+Implements production-friendly Godot 4 changes using typed GDScript, scene composition, and low-coupling architecture.
+
+## Use This Skill When
+
+- Adding or refactoring gameplay systems, UI flows, or content pipelines in Godot.
+- Debugging node lifecycle, signals, resources, or autoload behavior.
+- Improving maintainability, style consistency, or data flow in GDScript code.
+
+## Core Rules
+
+1. Prefer composition over deep inheritance: split reusable behavior into scenes/resources/scripts with focused responsibilities.
+2. Choose scenes for reusable node trees and editor-authored structure; choose scripts/resources for logic and data that do not need node hierarchy.
+3. Use autoloads only for truly global state/services (save systems, global config, cross-scene coordinators), not as default dependency injection.
+4. Favor signals over direct cross-tree mutation to reduce coupling between gameplay, UI, and services.
+5. Use typed GDScript where possible: annotate variables, params, and return types for safer refactors.
+
+## GDScript Implementation Checklist
+
+1. Keep naming idiomatic: `snake_case` for vars/functions/signals, `PascalCase` for `class_name`, `UPPER_SNAKE_CASE` for constants.
+2. Use `@export` for editor-facing configuration and `@onready` only for scene-dependent node lookups.
+3. Respect lifecycle intent: `_init` for construction data, `_enter_tree` for tree attachment concerns, `_ready` for node wiring, `_process`/`_physics_process` for frame loops.
+4. Distinguish frame loops clearly: use `_physics_process` for deterministic physics movement and `_process` for visual or non-physics updates.
+5. Use `match` for clear branching on enums/states and keep functions short with early returns.
+
+## Data, Loading, And Error Handling
+
+1. Guard all file access (`FileAccess.open`) and JSON parsing before indexing into parsed values.
+2. Validate dynamic data types (`is Dictionary`, `is Array`) before field access to avoid runtime surprises.
+3. Use `preload` for stable, frequently used compile-time resources; use `load` for optional or dynamic runtime assets.
+4. Prefer `Resource`/`RefCounted` for plain data models when node features are unnecessary.
+5. Use `assert`/`push_error` for invalid states that should fail loudly during development.
+
+## Delivery Workflow
+
+1. Read `project.godot` first to identify autoloads, rendering/physics settings, and project conventions.
+2. Inspect relevant `.tscn` + `.gd` pairs together before editing to preserve scene-script contracts.
+3. Implement minimal, targeted changes that keep public APIs/signals stable unless change is requested.
+4. Run headless validation and script checks for touched scripts; run project smoke test when feasible.
+5. Summarize changed files, behavior impact, and any follow-up risks.
+
+## Validation Commands
+
+Use project-provided commands when available. Typical Godot checks:
+
+```bash
+"$GODOT_BIN" --headless --path . --quit
+"$GODOT_BIN" --headless --check-only --script res://path/to/changed_script.gd
+```
+
+## References
+
+- https://docs.godotengine.org/en/stable/tutorials/best_practices/index.html
+- https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html