| 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. |
| argument-hint | [subsystem: gdscript | shaders | scenes | ui | physics-2d | physics-3d | audio | animation | resources | autoloads | editor | perf] or [task: feature | bugfix | refactor | review | optimize | port | onboard] |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Shell, Task, AskQuestion, CallMcpTool, WebSearch |
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 — flat index of every Godot surface this skill links to.
- playbooks.md — per-subsystem playbooks (GDScript, shaders, UI, physics, …).
Companion skill: godot-sight 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 |
| 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.
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
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:
- 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).
- Invoke
/godot-master shaders. Confirm the agent reads modules/rendering.md + shader-code.mdc.
- Ask the agent: "Should I use GDScript or C# for this?" — confirm it delegates to
godot-specialist via Task (do not implement, just delegate).
- 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 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
Full resource index: reference.md.
Per-subsystem playbooks: playbooks.md.
Skill version: 1.0 — Last verified: 2026-05-25. Maintainer: project technical lead. Reviewers: godot-specialist, lead-programmer.
