Godot Master

Godot Master: The Engine Brain

This skill is the router and judgment layer for every Godot decision the agent makes in this project. It does not duplicate the engine reference docs, the specialist agent briefs, the path-scoped rules, or the godot-sight runtime loop — it tells the agent which of them to consult, in what order, for the task at hand.

> If you are about to suggest a Godot API, type, node, signal, shader directive, or project setting, read the relevant reference first. The model's training data predates Godot 4.6 by 1+ years. Trust the docs in docs/engine-reference/godot/, not your prior.

Companion files:

• [reference.md](reference.md) — flat index of every Godot surface this skill links to.
• [playbooks.md](playbooks.md) — per-subsystem playbooks (GDScript, shaders, UI, physics, …).

Companion skill: [godot-sight](../godot-sight/SKILL.md) is the eyes & hands (verify, run, see, assert). This skill is the brain (know, decide, delegate). They compose; they do not overlap.

---

The Core Loop

For any Godot task the agent picks up:

KNOW  →  ROUTE  →  DELEGATE? →  ACT  →  VERIFY  →  RECORD

| Step | What to do | Source | |------|------------|--------| | KNOW | Confirm engine version + check for deprecation of any API you're about to use | docs/engine-reference/godot/VERSION.md, deprecated-apis.md | | ROUTE | Decide which subsystem playbook applies; read the matching module doc | playbooks.md + docs/engine-reference/godot/modules/.md | | DELEGATE? | If the work is non-trivial and lives in a specialist's domain, spawn that specialist via the Task tool | reference.md § Specialist briefs | | ACT | Write code / edit scenes / change settings, obeying the path-scoped rules | .cursor/rules/*.mdc | | VERIFY | Hand off to godot-sight core loop (verify → run → see → assert → stop) | [godot-sight/SKILL.md](../godot-sight/SKILL.md) | | RECORD | If a new pattern, deprecation, or gotcha was discovered, surface it for the engine reference docs | docs/engine-reference/godot/ |

KNOW is non-negotiable. Every Godot session must read VERSION.md once before suggesting any API. After that, only re-read it if the user mentions an engine upgrade or /setup-engine refresh.

---

Proactive Triggers

Run the matching action without being asked when any of these happen in a session:

| You're about to… | Read first | Why | |------------------|-----------|-----| | Write or rewrite GDScript | deprecated-apis.md + current-best-practices.md | Catches yield, instance(), string-based connect(), missing typed vars | | Edit a shader | modules/rendering.md + .cursor/rules/shader-code.mdc | Texture2D→Texture (4.4), Compositor (4.3+), Shader Baker (4.5) | | Edit a .tscn scene | current-best-practices.md + scene playbook | Catches missing UIDs, broken preload, dual-focus pitfalls | | Work on UI / Control nodes | modules/ui.md | 4.6 dual-focus split, FoldableContainer (4.5), recursive disable | | Add or change autoloads | autoload playbook + modules/audio.md if applicable | Autoload init order; signal binding in _ready | | Pick a physics body type (2D) | playbooks.md § Physics 2D | Area2D vs RigidBody2D vs CharacterBody2D vs StaticBody2D | | Pick a physics body type (3D) | modules/physics.md | Jolt is default in 4.6 — HingeJoint3D.damp only works with GodotPhysics3D | | Set up animation | modules/animation.md | AnimationMixer.active (not playback_active), IK via SkeletonModifier3D (4.6) | | Touch navigation | modules/navigation.md | Dedicated 2D nav server (4.5); NavigationRegion2D.avoidance_layers removed (4.3) | | Add multiplayer | modules/networking.md | set_multiplayer_authority timing, auth_callback flow | | Add a @tool script | editor playbook | @tool scripts run in editor — guard Engine.is_editor_hint() for runtime-only code | | Optimize a hot path | perf playbook + .cursor/rules/engine-code.mdc | Zero-alloc rules, profile-before-after-document | | Suggest GDScript vs C# vs GDExtension | godot-specialist brief | Engine-wide decision; specialist owns this call | | Start a new feature | /dev-story integration + Sight Scenario A | Embeds VERIFY/RUN/SEE/ASSERT into the implementation loop |

If the user says "keep going" between Godot edits, run only the KNOW step silently (re-confirm any API you're about to suggest is not in deprecated-apis.md). That's a 2-second guard with massive payoff.

---

The Knowledge Graph

Everything the agent needs for Godot work in this project, and where it lives:

docs/engine-reference/godot/         ← VERSION-PINNED ENGINE KNOWLEDGE
  ├── VERSION.md                     ← Read once per session
  ├── deprecated-apis.md             ← Check before suggesting ANY API
  ├── breaking-changes.md            ← 4.3→4.6 migration table
  ├── current-best-practices.md      ← Post-cutoff additions
  └── modules/                       ← Per-subsystem (~150 lines each)
      ├── ui.md  rendering.md  physics.md  input.md
      ├── audio.md  animation.md  networking.md  navigation.md

.cursor/agents/                       ← DELEGATABLE SPECIALISTS (via Task tool)
  ├── godot-specialist.md            ← Architecture, GDScript-vs-C#-vs-GDExtension
  ├── godot-gdscript-specialist.md   ← Typed GDScript, signal patterns
  ├── godot-shader-specialist.md     ← .gdshader, visual shaders, post-processing
  ├── godot-csharp-specialist.md     ← (only if C# is added)
  └── godot-gdextension-specialist.md ← (only if native code is added)

.cursor/rules/                        ← AUTO-APPLIED CODING STANDARDS
  ├── engine-code.mdc                ← scripts/autoloads/**, scripts/systems/**
  ├── gameplay-code.mdc              ← gameplay logic
  ├── shader-code.mdc                ← shaders/**
  └── ui-code.mdc                    ← UI code

.cursor/skills/                       ← COMPOSED SKILLS
  ├── godot-sight/                   ← Runtime verification (eyes & hands)
  ├── setup-engine/                  ← Refresh / upgrade reference docs
  └── (studio workflow skills — see reference.md § Studio integration)

Full per-file purpose and one-line summaries in [reference.md](reference.md).

---

Decision Matrix — Task → Surface

Use this table to pick the entry point when the user hands you a Godot task.

| Task shape | First read | Then maybe delegate to | Verify with | |------------|-----------|------------------------|-------------| | "Add system X" (new feature) | matching module doc + current-best-practices.md | godot-specialist (if architecture) → godot-gdscript-specialist (impl) | Sight Scenario A | | "Fix this crash" / "doesn't fire" | get_logs first, then deprecated-apis.md for the offending line | godot-gdscript-specialist if non-trivial | Sight Scenario C | | "Looks wrong" / visual bug | get_logs + modules/rendering.md or modules/ui.md | godot-shader-specialist if shader | Sight Scenario B | | "Refactor / rename / move" | current-best-practices.md (typed vars, @onready) | usually no specialist | Sight Scenario E | | "Optimize" / "it's slow" | modules/.md + .cursor/rules/engine-code.mdc | godot-specialist for architecture-level perf | /perf-profile skill | | "Port from Unity/Unreal" | current-best-practices.md + every module of the affected subsystem | godot-specialist | Sight Scenario A | | "Upgrade engine version" | breaking-changes.md for the version jump | godot-specialist | /setup-engine upgrade | | "Should we use GDScript or C# for this?" | godot-specialist brief directly | godot-specialist always | n/a (decision, not code) | | "Is this Godot API still valid?" | deprecated-apis.md then breaking-changes.md | n/a | n/a |

If a task does not match any row, default to: read VERSION.md → read current-best-practices.md → ask the user one clarifying question before proceeding.

---

Subsystem Routing — File Edit → Module Doc

| Editing… | Required reads | Playbook | |----------|---------------|----------| | .gd (general) | deprecated-apis.md + current-best-practices.md | [playbooks.md § GDScript](playbooks.md) | | .gdshader / .gdshaderinc | modules/rendering.md + shader-code.mdc | [playbooks.md § Shaders](playbooks.md) | | .tscn / .scn | current-best-practices.md + scene playbook | [playbooks.md § Scenes & Nodes](playbooks.md) | | .tres / .res | current-best-practices.md § Resources (duplicate_deep) | [playbooks.md § Resources](playbooks.md) | | UI scripts (Control nodes) | modules/ui.md + ui-code.mdc | [playbooks.md § UI](playbooks.md) | | 2D physics scripts (Area2D, RigidBody2D, CharacterBody2D) | modules/physics-2d.md | [playbooks.md § Physics 2D](playbooks.md) | | 3D physics scripts (CharacterBody3D, RigidBody3D, joints) | modules/physics.md | [playbooks.md § Physics 3D](playbooks.md) | | Audio code or AudioManager | modules/audio.md | [playbooks.md § Audio](playbooks.md) | | AnimationPlayer / AnimationTree / Tween | modules/animation.md | [playbooks.md § Animation](playbooks.md) | | Navigation / pathfinding | modules/navigation.md | [playbooks.md § Navigation](playbooks.md) | | Multiplayer / RPCs | modules/networking.md | [playbooks.md § Networking](playbooks.md) | | project.godot, autoload list, input map | autoload playbook | [playbooks.md § Project Settings & Autoloads](playbooks.md) | | @tool scripts, EditorPlugin, addons/*/plugin.cfg | modules/editor-tooling.md | [playbooks.md § Editor & Tooling](playbooks.md) |

---

Specialist Delegation

Spawn a specialist via the Task tool only when the work is non-trivial and lives squarely in that specialist's domain. For a one-line edit, do it yourself. The boundary:

| Specialist | Delegate when | Example task | Don't delegate when | |------------|--------------|--------------|---------------------| | godot-specialist | Cross-subsystem architecture, language-choice decisions | "Design the save system", "Should this be C# or GDScript?" | "Fix this typo in a .gd file" | | godot-gdscript-specialist | New non-trivial GDScript file or major refactor | "Build a typed state machine framework" | "Add one log line" | | godot-shader-specialist | Any non-trivial shader (>20 lines or any post-process) | "Write the warp tunnel shader" | "Change a uniform default value" | | godot-csharp-specialist | Any C# work (NOTE: this project is currently GDScript-only) | n/a yet | n/a | | godot-gdextension-specialist | Native code via godot-cpp / gdext-rust | n/a yet | n/a |

When spawning, include the matching specialist brief contents in the prompt (per AGENTS.md § Subagent Invocation):

Task(
  subagent_type: "godot-shader-specialist",
  description: "Implement warp tunnel shader",
  prompt: " + "
)

---

Composition With godot-sight

This skill and godot-sight are designed to interlock:

| Phase | This skill (brain) | godot-sight (eyes & hands) | |-------|-------------------|------------------------------| | Before edit | KNOW + ROUTE: confirm version, read module doc | verify_project (baseline) | | During edit | DELEGATE? + ACT: apply standards, route to specialist | — | | After edit | RECORD (if new pattern surfaced) | verify_project → run_scene → screenshot / assert_node_exists → stop | | Before declaring done | — | Sight Scenario F (pre-commit) |

Rule of thumb: never finish a Godot edit without one round of godot-sight. Never start a Godot edit without one round of godot-master.

---

Integration With Studio Skills

This skill is invoked from inside other skills, not as a replacement.

| Studio skill | Where godot-master fits | |--------------|---------------------------| | /dev-story | Run KNOW + ROUTE before touching code; ACT inside the story implementation phase; hand to godot-sight Scenario A for verification | | /code-review | Use the Decision Matrix to check the reviewer is reading the right module doc; flag any use of a deprecated-apis.md left-column entry | | /story-done | Confirm KNOW is current (no engine upgrade in flight); hand to godot-sight Scenario F | | /perf-profile | Use ROUTE to find the right modules/*.md for the suspected hotspot; consult engine-code.mdc zero-alloc rules | | /setup-engine | The owner of docs/engine-reference/godot/. Run /setup-engine refresh if any doc has a stale "Last verified" date | | /create-architecture | Required reads include every module doc relevant to architectural decisions; delegate via godot-specialist | | /reverse-document | Use the Knowledge Graph to know which subsystems exist in the project; sample scripts/scenes per subsystem | | /onboard | Hand a new contributor this skill + godot-sight first; they're the only two Godot-specific skills they need to start |

---

Anti-Patterns

1. Suggesting a Godot API from memory. The model's training data is older than 4.6. Always cross-check deprecated-apis.md and the relevant modules/*.md. Cost: one extra Read call. Payoff: no rework.

2. Reading every module doc preemptively. Read only the module(s) for the current task. The full library is for routing, not for stuffing into context. Each module is 90 days old | Suggest /setup-engine refresh | setup-engine skill | | A modules/*.md "Last verified" >90 days old | Same | setup-engine skill | | Godot released a new minor version (e.g. 4.7) | Run /setup-engine upgrade 4.6 4.7 | setup-engine skill | | Godot released a new patch version (e.g. 4.6.1) | Run /setup-engine refresh and update VERSION.md | setup-engine skill | | You learn a Godot fact the docs don't have | Surface to user; do not hand-edit the reference docs | This skill flags; user decides | | The model suggested an API the docs reject | Flag the deprecation; remind user the docs are source-of-truth | This skill | | A new modules/*.md is added (e.g. physics-2d.md) | Update reference.md § Engine Reference Library; add a routing row to SKILL.md § Subsystem Routing; remove any "content gap" callouts in playbooks.md | Author of the new module | | A specialist agent brief is added or removed | Update reference.md § Specialist Agent Briefs; update SKILL.md § Specialist Delegation | setup-engine skill (it owns the specialists list) | | A .cursor/rules/*.mdc glob changes | Update reference.md § Path-Scoped Rules; verify the matching playbook still references the right rule | Author of the rule change |

Refresh schedule

• Every 90 days: run /setup-engine refresh to pick up Godot patch releases and newly-deprecated APIs.
• Every minor engine release: run /setup-engine upgrade immediately.
• Every Godot session: the agent re-reads VERSION.md once and trusts the cached version for the rest of the session.

Smoke test (verify this skill still works)

Manual smoke test, runnable any time:

1. Open any .gd file. Confirm the master skill auto-triggers (you should see the agent consult deprecated-apis.md or a modules/*.md before suggesting changes).
2. Invoke /godot-master shaders. Confirm the agent reads modules/rendering.md + shader-code.mdc.
3. Ask the agent: "Should I use GDScript or C# for this?" — confirm it delegates to godot-specialist via Task (do not implement, just delegate).
4. After a .gd edit, confirm the agent runs godot-sight verify → run → screenshot → stop. The master skill should never finish a Godot edit without invoking Sight.

Any of those failing means the skill needs a fix — open an issue against .cursor/skills/godot-master/SKILL.md.

Ownership

• godot-master skill itself: owned by the project's technical lead. Reviewers: godot-specialist, lead-programmer.
• reference.md: auto-updated by setup-engine when the surface area changes (new specialist, new module, new rule).
• playbooks.md: community-owned — any cont

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lanc3
• Source: Lanc3/godot-sight
• License: MIT
• Homepage: https://www.expansion.ie

Install and usage instructions live in the source repository linked above.