godot-master

---
name: godot-master
description: Master Godot 4 development skill — the agent's brain for any Godot work in this project. Use proactively whenever Godot code, scenes, shaders, resources, or settings are being authored, refactored, debugged, reviewed, or planned — not only when the user explicitly asks. Triggers: writing or editing .gd / GDScript, modifying .tscn / .scn scenes, editing .gdshader / .gdshaderinc shaders, editing .tres / .res resources, changing project.godot or autoload list, working with input map / themes / .import files, suggesting any Godot API or class, designing a Godot system, picking GDScript vs C# vs GDExtension, optimizing a hot path, profiling, choosing physics / rendering / input / UI patterns, hooking up signals, building autoloads, anything that mentions Godot, GDScript, Forward+ / Mobile / Compatibility renderer, Jolt, AnimationMixer, NavigationServer, MultiplayerSynchronizer, Control nodes, or any Godot subsystem. Routes the agent to the right engine reference doc, the right specialist agent brief, the right path-scoped rule, and composes with the godot-sight runtime loop. Always consult before suggesting a Godot API — the LLM's training data is older than the pinned engine version.
license: MIT
---

# 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/<sub>.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/<the slow one>.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: "<contents of .cursor/agents/godot-shader-specialist.md> + <story / spec>"
)
```

---

## 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 <150 lines for a reason.

**3. Delegating a one-line edit to a specialist.**
Specialist spawn cost is high. Only delegate non-trivial / cross-cutting work. Use the boundary table above.

**4. Skipping `godot-sight` because "the code looks right."**
"Looks right" is not "runs right." Every Godot edit ends with at least one Sight round. The two skills are designed to be used together.

**5. Reading `VERSION.md` every turn.**
Read it **once per session** unless the user mentions an upgrade. After that, treat the version as fixed.

**6. Editing `docs/engine-reference/godot/*.md` directly.**
That's `/setup-engine refresh` territory. Don't hand-patch the reference docs — surface the new fact to the user and let the refresh skill update it with citations.

**7. Treating this skill as a replacement for the specialist briefs.**
It is a router and a judgment layer. The specialists own the deep work. Hand off when the work warrants it.

**8. Asking the user "should I read the engine reference?"**
No. Read it. Then do the work. The user enabled this skill so the agent stops asking that question.

---

## Maintenance & Ownership

### Drift triggers

| Symptom | Action | Owner |
|---------|--------|-------|
| `VERSION.md` "Last verified" >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 <old> <new>` 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 contributor adds a playbook entry when they discover a new gotcha. See § "How to extend this file" at the bottom of `playbooks.md`.
- **Engine reference docs** (`docs/engine-reference/godot/`): owned by `setup-engine` skill. **Never** hand-edit; always refresh.
- **Specialist agent briefs** (`.cursor/agents/godot-*.md`): owned by `setup-engine` (initial creation) + the matching specialist itself.

### When this skill goes out of scope

If a Godot question is about a subsystem that has **neither** a module doc **nor** a playbook entry **nor** a specialist brief, escalate to `godot-specialist` directly. Do not improvise from the model's prior. The escalation prompt should read:

> "There is no `docs/engine-reference/godot/modules/<X>.md`, no playbook entry for <X> in `.cursor/skills/godot-master/playbooks.md`, and no specialist owns this subsystem. Recommend either populating a new module via `/setup-engine refresh` or assigning ownership."

---

## Quick Reference

**Engine version:** Godot 4.6 (pinned 2026-02-12) — confirm in `docs/engine-reference/godot/VERSION.md`
**Renderer:** Forward+ (per `AGENTS.md`)
**Language:** GDScript with static typing (per `.cursor/rules/`)
**Engine reference root:** `docs/engine-reference/godot/`
**Specialist briefs root:** `.cursor/agents/godot-*.md`
**Companion runtime skill:** [`godot-sight`](../godot-sight/SKILL.md)

Full resource index: [reference.md](reference.md).
Per-subsystem playbooks: [playbooks.md](playbooks.md).

---

*Skill version: 1.0 — Last verified: 2026-05-25. Maintainer: project technical lead. Reviewers: `godot-specialist`, `lead-programmer`.*