Agentic skills framework for Godot 4.x game development. Gives AI coding agents domain-specific expertise for GDScript and C# projects.
Inspired by and built on top of the Superpowers plugin for Claude Code — which provides the underlying skill loading, brainstorming, and workflow infrastructure that GodotPrompter extends with Godot-specific domain knowledge.
GodotPrompter is a plugin that provides skills — structured domain knowledge that AI agents load on demand. When you ask your agent to "add a state machine" or "set up multiplayer", it loads the relevant GodotPrompter skill and follows Godot-specific best practices instead of relying on generic knowledge.
55 skills covering project setup, architecture, gameplay systems, input handling, physics, 2D/3D systems, animation, shaders, audio, UI, multiplayer, localization, procedural generation, XR/VR, native extensions, multithreading, mobile shipping, optimization, GDScript / C# patterns, a teaching mode, and third-party addons (LimboAI, Beehave, Popochiu, Dialogue Manager, Phantom Camera). All targeting Godot 4.3+ with both GDScript and C# examples — newer features from Godot 4.5, 4.6, and 4.7 (variadic functions, abstract classes, stencil buffers, AreaLight3D, VirtualJoystick, OpenXR Spatial Entities, and more) are included as annotated additive sections.
v1.7.0 introduces a 16 KB token budget for SKILL.md files (validator-enforced) and the new gdscript-advanced skill for production-grade GDScript depth (performance idioms, metaprogramming, @tool lifecycle, profiler-driven idioms).
v1.9.0 adds native power and mobile shipping — the new gdextension (godot-cpp / Rust native extensions), multithreading (WorkerThreadPool, threads, threaded loading), and mobile-development (Android/iOS export, lifecycle, plugins, IAP) skills.
# Add the marketplace
claude plugins marketplace add jame581/skillsmith
# Install the plugin
claude plugins install godot-prompter@skillsmithOr install from a local clone:
git clone https://github.com/jame581/GodotPrompter.git
claude plugins marketplace add ./GodotPrompter
claude plugins install godot-prompter@godot-prompterThen start a new session and ask:
"I'm starting a new Godot 4.3 project. How should I organize it?"
The agent loads the godot-project-setup skill and provides a complete directory structure, autoload setup, and .gitignore — not generic advice.
grok plugin install jame581/GodotPrompter --trust
grok plugin enable godot-prompterPin to a release:
grok plugin install jame581/[email protected] --trust
grok plugin enable godot-prompteragy plugin install https://github.com/jame581/GodotPromptercopilot plugin marketplace add jame581/skillsmith
copilot plugin install godot-prompter@skillsmith/add-plugin godot-prompter
Or clone and place in your project — Cursor reads .cursor-plugin/plugin.json.
git clone https://github.com/jame581/GodotPrompter.git ~/.codex/godot-prompter
mkdir -p ~/.agents/skills
ln -s ~/.codex/godot-prompter/skills ~/.agents/skills/godot-prompterSee .codex/INSTALL.md for Windows instructions.
Add to opencode.json:
{
"plugin": ["godot-prompter@git+https://github.com/jame581/GodotPrompter.git"]
}See .opencode/INSTALL.md for details.
GodotPrompter registers a SessionStart hook that injects its skill-routing card when it detects
a Godot project. It looks for project.godot up to four directories above your working
directory and up to three below it, so the common monorepo layout — docs and tooling at the
repo root, the engine project in source/, game/, or godot/ — is detected when you open a
session at the root. Vendored addons/ and dot-directories are skipped, so a plugin's bundled
demo project is never mistaken for yours. In any other repository the hook does nothing at all.
The hook reads only your project's project.godot and its own state file under your home
directory, makes no network requests, and writes nothing. If bash is unavailable on Windows it
exits silently and the plugin behaves exactly as it did before v1.13.0.
Verified end-to-end on Claude Code and GitHub Copilot CLI. Cursor's registration ships but is
not yet confirmed. Codex and Antigravity have no hook mechanism and continue to load the
bootstrap through AGENTS.md / GEMINI.md.
The hook covers your session. Subagents do not receive it —
SessionStartdoes not fire on subagent dispatch. When a Godot project'sCLAUDE.mdhas no## GodotPromptersection, the agent offers once to add one, since that is what subagents read. It never adds it silently.
Say "teach me as we go" in a Godot project and GodotPrompter switches to teaching delivery: the Godot concept and why that node, the editor setup, annotated GDScript and C#, what to verify when you run it, and one suggested next step. It wraps the domain skills rather than replacing them, so the guidance stays version-checked.
Your preference is remembered per project in ~/.godot-prompter/state/ — nothing is written into
your game repository. Say "just give me the code" to turn it off.
Ask the agent to brainstorm a feature. It loads godot-brainstorming and walks you through:
- Clarifying questions about your game/system
- Architectural approaches with trade-offs
- Scene tree design, signal maps, and data flow
- An implementation plan with ordered tasks
For each task, the agent loads the relevant domain skill:
- Building a player? →
player-controller+input-handling+state-machine - Adding inventory? →
inventory-system+resource-pattern - Setting up 3D scene? →
3d-essentials+assets-pipeline - Adding particles? →
particles-vfx+shader-basics - Need animations? →
animation-system+tween-animation - Need save/load? →
save-load
Ask for a code review. The agent loads godot-code-review and checks against Godot-specific checklists.
- "Set up a new Godot project" — Loads the
godot-project-setupskill and scaffolds a complete directory structure, autoloads, input map, and .gitignore following Godot best practices. - "Add a platformer player controller with coyote time and jump buffering" — Loads
player-controllerandinput-handlingskills, providing complete CharacterBody2D code with physics-correct movement in both GDScript and C#. - "Design an enemy AI system with patrol, chase, and attack" — Uses the
godot-game-architectagent to plan the system withai-navigation,state-machine, andanimation-systemskills, then thegodot-game-devagent to implement it. - "Set up a 3D scene with lighting, materials, and fog" — Loads
3d-essentialsskill with StandardMaterial3D PBR workflow, DirectionalLight3D shadow configuration, environment setup, and volumetric fog. - "Add particle effects for explosions and fire" — Loads
particles-vfxskill with GPUParticles2D/3D recipes, ParticleProcessMaterial configuration, color ramps, and one-shot burst patterns. - "Review my code for Godot best practices" — Uses the
godot-code-revieweragent with thegodot-code-reviewskill to check node architecture, signal patterns, performance, input handling, and resource management.
GodotPrompter includes 9 specialized agents:
| Agent | Purpose |
|---|---|
| godot-game-architect | Designs systems, plans scene trees, chooses patterns |
| godot-game-dev | Implements features guided by skills |
| godot-code-reviewer | Reviews code against Godot best practices |
| godot-shader-author | Authors custom shaders, post-processing, Compositor effects |
| godot-performance-profiler | Diagnoses performance issues from profiler data |
| godot-animator | Designs animation graphs, blend trees, IKModifier3D, BoneConstraint3D, retargeting |
| godot-csharp-engineer | C#-first development; parity mode for closing this repo's C# debt |
| godot-ui-designer | Builds Control-tree UI — themes, responsive layouts, localization-aware |
| godot-tools-engineer | Editor plugins, custom inspectors, gizmos, @tool scripts, plugin distribution |
| Platform | Status | Install |
|---|---|---|
| Claude Code | Primary | claude plugins marketplace add jame581/skillsmith |
| Grok Build | Supported | grok plugin install jame581/GodotPrompter --trust |
Antigravity CLI (agy) |
Supported | agy plugin install https://github.com/jame581/GodotPrompter |
| GitHub Copilot CLI | Supported | copilot plugin marketplace add jame581/skillsmith |
| Cursor | Supported | /add-plugin godot-prompter or clone with .cursor-plugin/ |
| Codex | Supported | Clone + symlink (see .codex/INSTALL.md) |
| OpenCode | Supported | Add to opencode.json (see .opencode/INSTALL.md) |
| Antigravity | Supported | Install via the Antigravity plugin marketplace |
Legacy marketplace: The
godot-prompter-marketplacerepo remains online so existing installs keep receiving updates, but new users should install fromskillsmith.
| Skill | Description |
|---|---|
using-godot-prompter |
Bootstrap — skill catalog, workflow guide, platform setup |
godot-project-setup |
Scaffold directory structure, autoloads, .gitignore, input maps |
godot-brainstorming |
Scene tree planning, node selection, architectural decisions |
godot-code-review |
Review checklist — best practices, anti-patterns, Godot pitfalls |
godot-debugging |
Remote debugger, print techniques, signal tracing, error patterns |
godot-testing |
TDD with GUT and gdUnit4 — test structure, mocking, CI |
godot-mentor |
Teaching mode — concept, editor setup, annotated code, verification, one next step |
| Skill | Description |
|---|---|
scene-organization |
Scene tree composition, when to split scenes, node hierarchy |
state-machine |
Enum-based, node-based, resource-based FSM with trade-offs |
event-bus |
Global EventBus autoload with typed signals, decoupled communication |
component-system |
Hitbox/Hurtbox/Health components, composition over inheritance |
resource-pattern |
Custom Resources for items, stats, config, editor integration |
dependency-injection |
Autoloads, service locators, @export injection, scene injection |
| Skill | Description |
|---|---|
physics-system |
RigidBody, Area, raycasting, collision shapes, Jolt, ragdolls, interpolation |
2d-essentials |
TileMaps, parallax, 2D lights/shadows, particles, custom drawing, canvas layers |
3d-essentials |
Materials, lighting, shadows, environment, GI, fog, LOD, occlusion, decals |
xr-development |
OpenXR, XROrigin3D, hand tracking, controllers, passthrough, Meta Quest |
| Skill | Description |
|---|---|
player-controller |
CharacterBody2D/3D movement — top-down, platformer, first-person |
input-handling |
InputEvent system, Input Map actions, controllers/gamepads, mouse/touch, action rebinding |
animation-system |
AnimationPlayer, AnimationTree, blend trees, state machines, sprite animation |
tween-animation |
Tween class, easing, chaining, parallel sequences, common motion recipes |
audio-system |
Audio buses, music management, SFX pooling, spatial audio, interactive music |
inventory-system |
Resource-based items, slot management, stacking, UI binding |
dialogue-system |
Branching dialogue trees, conditions, UI presentation |
save-load |
ConfigFile, JSON, Resource serialization, version migration |
ai-navigation |
NavigationAgent2D/3D, steering behaviors, patrol patterns, async baking |
ability-system |
Resource-based abilities, cost/cooldown/cast, buffs/debuffs, stat modifiers, gameplay tags, HUD binding |
camera-system |
Smooth follow, screen shake, camera zones, transitions |
localization |
TranslationServer, CSV/PO files, locale switching, RTL support, pluralization |
procedural-generation |
Noise, BSP dungeons, cellular automata, WFC, seeded randomness |
| Skill | Description |
|---|---|
godot-ui |
Control nodes, themes, anchors, containers, layout patterns |
responsive-ui |
Multi-resolution scaling, aspect ratios, DPI, mobile adaptation |
hud-system |
Health bars, score displays, minimap, damage numbers, notifications |
| Skill | Description |
|---|---|
multiplayer-basics |
MultiplayerAPI, ENet/WebSocket, RPCs, authority model |
multiplayer-sync |
MultiplayerSynchronizer, interpolation, prediction, lag compensation |
dedicated-server |
Headless export, server architecture, lobby management |
| Skill | Description |
|---|---|
shader-basics |
Godot shader language, visual shaders, common recipes, post-processing |
particles-vfx |
GPUParticles2D/3D, process materials, subemitters, trails, attractors, collision |
| Skill | Description |
|---|---|
export-pipeline |
Platform exports, CI/CD with GitHub Actions, itch.io/Steam deploy |
godot-optimization |
Profiler, draw calls, physics tuning, object pooling, bottlenecks |
addon-development |
EditorPlugin, @tool scripts, custom inspectors, dock panels |
assets-pipeline |
Image compression, 3D scene import, audio formats, resource management |
mobile-development |
Android/iOS export, signing, lifecycle, permissions, plugins, IAP, device features |
| Skill | Description |
|---|---|
gdscript-patterns |
Static typing, await/coroutines, lambdas, match, exports, common idioms |
gdscript-advanced |
Performance idioms, metaprogramming, @tool lifecycle, profiler-driven depth |
csharp-godot |
C# conventions, GodotSharp API, project setup, GDScript interop |
csharp-signals |
[Signal] delegates, EmitSignal, async awaiting, event architecture |
| Skill | Description |
|---|---|
gdextension |
godot-cpp (C++) / gdext (Rust) native extensions, class binding, building, interop |
multithreading |
WorkerThreadPool, Thread/Mutex/Semaphore, call_deferred, threaded resource loading |
| Skill | Description |
|---|---|
math-essentials |
Vectors, transforms, interpolation, curves, paths, RNG, game math recipes |
These skills cover community addons with pinned versions — LimboAI v1.8.0, Beehave v2.9.2, Popochiu v2.1.1, Dialogue Manager v3.10.4, and Phantom Camera v0.11.0.2. They require the corresponding addon to be installed in your project.
| Skill | Description |
|---|---|
limboai |
LimboAI addon — behavior trees + hierarchical state machines, visual editor, blackboard, BTTask subclassing (Godot 4.6+, C++ GDExtension) |
beehave |
Beehave addon — pure-GDScript behavior trees, composites/decorators/leaves, blackboard, visual runtime debugger (GDScript-only) |
popochiu |
Popochiu addon — point-and-click adventure framework: rooms, characters, inventory, dialogs, command GUI (Godot 4.6, GDScript-only) |
dialogue-manager |
Dialogue Manager addon — .dialogue syntax, runtime balloons, conditions/mutations (Godot 4.6, GDScript + C#) |
phantom-camera |
Phantom Camera addon — priority-based camera switching, follow/look-at modes, tweened transitions (Godot 4.4+, GDScript + C#, pre-1.0) |
Quality is enforced by an automated validator that runs on every release tag. Human-readable run:
node scripts/validate-skills.mjs # exit 1 on errors, 0 otherwise
node scripts/validate-skills.mjs --json # machine-readable for CIThe validator (scripts/validate-skills.mjs) checks every skills/*/SKILL.md and agents/*.md against these rules:
| Rule | What it checks | Severity |
|---|---|---|
frontmatter-{missing,name-missing,description-missing,name-mismatch} |
YAML frontmatter is present and name matches folder |
error |
cross-ref-broken |
Every skill referenced on the **Related skills:** line and inline see <skill> skill mentions resolves to an existing skill folder |
error |
agent-skill-path-broken |
Every skills/<name>/SKILL.md path inside an agent definition exists |
error |
related-skills-line-missing |
Skill has a **Related skills:** line between H1 and first section |
warning |
csharp-parity-missing / csharp-parity-accepted |
Every section with a GDScript code block also has a C# block (skills allowlisted as GDScript-only-by-design emit accepted instead of missing) |
warning |
checklist-missing |
Implementation checklist (- [ ] items) present near end of file |
warning |
token-budget-exceeded |
SKILL.md < 16 KB (references under skills/<name>/references/ are unrestricted) |
error |
token-budget-approaching |
SKILL.md ≥ 15.5 KB and < 16 KB — advisory heads-up before the hard budget |
warning |
orphan-reference |
Every references/*.md file is linked from its parent SKILL.md |
warning |
card-marker-{missing,malformed,duplicate} |
The hook-injected card regions (SESSION-CARD in using-godot-prompter, MENTOR-CARD in godot-mentor) have both markers, in order, appearing exactly once — the hook extracts the first region, so a duplicate pair would silently become the injected payload |
error |
card-empty |
The card region is non-empty — otherwise the hook would inject nothing while CI stayed green | error |
card-oversized |
The card region is ≤ 3 KB — it is injected on every session start and every compaction | error |
card-skill-missing |
Every skill named in CARD_SPECS exists, so deleting one fails CI instead of silently skipping its check |
error |
Hook behaviour is covered separately by npm run test:hooks (22 cases), which also runs on release tags.
Token cost reporting:
node scripts/count-tokens.mjs --tokenizer --markdownProduces a per-skill / per-agent table (bytes, KB, estimated tokens, Claude / GPT tokenizer counts, status) that lives between <!-- BEGIN-TOKEN-TABLE --> markers in docs/token-budget.md.
CI gate: .github/workflows/release.yml runs both node scripts/validate-skills.mjs and a tag-vs-manifest version-consistency check on every v*.*.* push. The release is blocked if the validator returns errors or any of package.json / .claude-plugin/plugin.json / .claude-plugin/marketplace.json / .cursor-plugin/plugin.json / plugin.json drifts from the tag.
Current baseline (v1.12.0): 0 errors, 16 warnings (all csharp-parity-accepted for intentionally GDScript-only skills; 0 token-budget). Every SKILL.md is under the 16 KB budget — since v1.12.0 that is a validator error, not a warning, so an over-budget skill fails the release.
A manual agent-integration test plan covering full workflows (skill discovery, cross-reference navigation, end-to-end feature implementation) lives in tests/agent-integration/TEST_PLAN.md for spot-checks against new agent versions or platforms.
See CONTRIBUTING.md for how to add new skills, conventions, and testing requirements.
The SessionStart hook's polyglot Windows wrapper, JSON escaper, and platform output branching are adapted from Superpowers by Jesse Vincent (MIT).
- Jan Mesarč - Creator - janmesarc.online/
Do you like this project and want to support me? Great! I really appreciate it and it makes me very happy if you Buy Me A Coffee.
