GodotPrompter

Agentic skills framework for Godot 4.x. Domain-specific skills for AI coding agents (Claude Code, Copilot, Antigravity, Cursor)

Automatically checked · GitHub checked 2026-11-14

Overview

GodotPrompter

License: MIT Godot 4.x Skills: 59

GodotPrompter on Product Hunt

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.

What is this?

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.

59 skills covering project setup, architecture, gameplay systems, input handling, physics, 2D/3D systems, animation, shaders, audio, UI, multiplayer, web services, localization, procedural generation, XR/VR, native extensions, multithreading, mobile and web shipping, rendering pipeline, 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 to 4.8 (variadic functions, abstract classes, stencil buffers, AreaLight3D, VirtualJoystick, OpenXR Spatial Entities, and in 4.8 theme sounds, auto-fit labels and the .NET 10 minimum) are included as annotated additive sections. The 4.8 content is checked against 4.8-beta3 and re-checked at 4.8-stable in v1.17.1.

v1.17.0 refreshes the Dialogue Manager addon skill to 4.x, adds Godot 4.8 callouts (checked against 4.8-beta3, re-verified at stable in v1.17.1), loads skills only when you build a new system rather than extend an existing one, and lets godot-grill ask its questions interactively. See the CHANGELOG.

Quick Start

Claude Code (recommended)

# Add the marketplace
claude plugins marketplace add jame581/skillsmith

# Install the plugin
claude plugins install godot-prompter@skillsmith

Or install from a local clone:

git clone https://github.com/jame581/GodotPrompter.git
claude plugins marketplace add ./GodotPrompter
claude plugins install godot-prompter@godot-prompter-marketplace

Then 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 Build

grok plugin install jame581/GodotPrompter --trust
grok plugin enable godot-prompter

Pin to a release:

grok plugin install jame581/[email protected] --trust
grok plugin enable godot-prompter

Antigravity CLI (agy)

agy plugin install https://github.com/jame581/GodotPrompter

GitHub Copilot CLI

copilot plugin marketplace add jame581/skillsmith
copilot plugin install godot-prompter@skillsmith

Detailed guide: docs/platforms/copilot-cli.md

Cursor

/add-plugin godot-prompter

Or clone and place in your project — Cursor reads .cursor-plugin/plugin.json.

Detailed guide: docs/platforms/cursor.md

Codex

git clone https://github.com/jame581/GodotPrompter.git ~/.codex/godot-prompter
mkdir -p ~/.agents/skills
ln -s ~/.codex/godot-prompter/skills ~/.agents/skills/godot-prompter

See .codex/INSTALL.md for Windows instructions.

OpenCode

Add to opencode.json:

{
  "plugin": ["godot-prompter@git+https://github.com/jame581/GodotPrompter.git"]
}

See .opencode/INSTALL.md for details.

Using fewer skills

Skills load by description match, so each one costs a little context in every session. To drop one you never need (say save-load), use the host's own switch. The skill name is the folder name under skills/; the table was last checked against each host's docs on 2026-11-11.

HostMechanismExampleStatus
Claude CodeDeny the skill with a permission rule. Plugin skills are named godot-prompter:<skill>. skillOverrides does not apply to plugin skills (docs)"permissions": {"deny": ["Skill(godot-prompter:save-load)"]} in .claude/settings.jsonTested on Claude Code 2.1.322 (deny run: denied; control: loaded). A deny rule hides nothing from / and does not stop you typing the command yourself
Copilot CLIcopilot skill disable works on plugin skills (docs)copilot skill disable save-load (undo: copilot skill enable save-load)Tested with Copilot CLI 1.0.108: the skill shows (disabled) and disabledSkills is written to settings.json
CodexDisable one skill in config.toml (docs), or link only the skills you want instead of the whole folder[[skills.config]] with name = "save-load" and enabled = false; or ln -s ~/.codex/godot-prompter/skills/player-controller ~/.agents/skills/ per skillDocumented, not tested (Codex not installed)
CursorNo per-skill switch is documented. Closest: skip the plugin and link a subset into .cursor/skills/ or ~/.cursor/skills/ (docs)ln -s /path/to/GodotPrompter/skills/player-controller ~/.cursor/skills/Documented, not tested
OpenCodeDeny the skill with a permission rule; 1.x and 2.x spell it differently (skills, permissions)1.x: "permission": {"skill": {"save-load": "deny"}}. 2.x: "permissions": [{"action": "skill", "resource": "save-load", "effect": "deny"}]1.18.29: config accepted and resolved into a skill deny rule; an invalid value is rejected. 2.x: documented, not tested. Whether the model list hides the skill needs a model session
AntigravityHide it with exclude in a skills.json manifest (docs), or symlink skills one by one (ln -s skills/<name>) instead of the whole folder.agents/skills.json: {"exclude": ["save-load"]}. Does not apply to ~/.gemini/skills/ or ~/.gemini/antigravity-cli/skills/ in the CLIDocumented, not tested
Grok BuildNo per-skill switch is documented. Do not enable the plugin; link a subset into ~/.grok/skills/ (docs)Skip grok plugin enable, then ln -s /path/to/GodotPrompter/skills/player-controller ~/.grok/skills/Documented, not tested

Disabling a skill does not edit the session card, which still routes by skill name; an agent that cannot load a disabled skill falls back to general knowledge.

How It Works

Automatic activation

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 — SessionStart does not fire on subagent dispatch. When none of a Godot project's agent instructions files has a ## GodotPrompter section, the agent offers once to add one, since that is what subagents read. CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md and the .claude/rules/ and .cursor/rules/ directories all count — whichever agent they belong to — and the offer names the file your repo already keeps, so an agent-agnostic project is never asked to start a CLAUDE.md it does not want. It never adds the section silently, and a refusal is remembered in ~/.godot-prompter/state/ so you are asked once, not at every session start. Changed your mind? Just ask the agent to add the section; nothing has to be un-set by hand.

A section along these lines works: "Invoke the matching godot-prompter:* skill before building a new Godot system; to change or extend an existing one, follow the project's code." A section added before v1.17.0 says "before implementing any Godot system"; update it to this wording.

Mentor mode

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.

1. Design Phase

Ask the agent to brainstorm a feature. When design decisions are open it loads godot-grill first, which asks them in rounds of up to 4 questions, each with a recommended answer, and records your choices. Where your host offers a question tool in the session (Claude Code, OpenCode, Copilot, Codex, Cursor, Grok), the rounds are asked interactively with the recommended answer first. Elsewhere, and in subagents, they are numbered text. Either way a "Decided so far" table is printed after each round. Antigravity has its own built-in /grill-me command, which is separate from this skill; the skill still runs there in text rounds. Then godot-brainstorming walks you through:

  • Architectural approaches with trade-offs
  • Scene tree design, signal maps, and data flow
  • An implementation plan with ordered tasks

2. Implementation Phase

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

3. Review Phase

Ask for a code review. The agent loads godot-code-review and checks against Godot-specific checklists.

Example Use Cases

  • "Set up a new Godot project" — Loads the godot-project-setup skill 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-controller and input-handling skills, 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-architect agent to plan the system with ai-navigation, state-machine, and animation-system skills, then the godot-game-dev agent to implement it.
  • "Set up a 3D scene with lighting, materials, and fog" — Loads 3d-essentials skill with StandardMaterial3D PBR workflow, DirectionalLight3D shadow configuration, environment setup, and volumetric fog.
  • "Add particle effects for explosions and fire" — Loads particles-vfx skill with GPUParticles2D/3D recipes, ParticleProcessMaterial configuration, color ramps, and one-shot burst patterns.
  • "Review my code for Godot best practices" — Uses the godot-code-reviewer agent with the godot-code-review skill to check node architecture, signal patterns, performance, input handling, and resource management.

Agents

GodotPrompter includes 9 specialized agents:

AgentPurpose
godot-game-architectDesigns systems, plans scene trees, chooses patterns
godot-game-devImplements features guided by skills
godot-code-reviewerReviews code against Godot best practices
godot-shader-authorAuthors custom shaders, post-processing, Compositor effects
godot-performance-profilerDiagnoses performance issues from profiler data
godot-animatorDesigns animation graphs, blend trees, IKModifier3D, BoneConstraint3D, retargeting
godot-csharp-engineerC#-first development; parity mode for closing this repo's C# debt
godot-ui-designerBuilds Control-tree UI — themes, responsive layouts, localization-aware
godot-tools-engineerEditor plugins, custom inspectors, gizmos, @tool scripts, plugin distribution

Supported Platforms

PlatformInstallSessionStart hookFresh-context pathStatusDocs
Claude Codeclaude plugins marketplace add jame581/skillsmithYesCLAUDE.md / .claude/CLAUDE.mdPrimary, verifiedThis README + tests/agent-integration/TEST_PLAN.md
GitHub Copilot CLIcopilot plugin marketplace add jame581/skillsmithYes.github/copilot-instructions.md or AGENTS.mdVerifieddocs/platforms/copilot-cli.md
Cursor/add-plugin godot-prompter or clone with .cursor-plugin/Registration ships.cursor/rules/ or AGENTS.mdEnd-to-end install still pending confirmationdocs/platforms/cursor.md
CodexClone + symlinkNoAGENTS.mdDocumented.codex/INSTALL.md
Antigravityagy plugin install https://github.com/jame581/GodotPrompterNoGEMINI.mdDocumentedThis README
OpenCodeAdd to opencode.jsonNoAGENTS.mdDocumented.opencode/INSTALL.md
Grok Buildgrok plugin install jame581/GodotPrompter --trustNot documentedNot documentedInstall path documented; smoke coverage still neededThis README

Machine-readable release smoke coverage lives in tests/agent-integration/host-smoke-matrix.json. The generated machine-readable skill catalog lives in skills/index.json.

Legacy marketplace: The godot-prompter-marketplace repo remains online so existing installs keep receiving updates, but new users should install from skillsmith.

Available Skills

Core / Process (8 skills)

SkillDescription
using-godot-prompterBootstrap — skill catalog, workflow guide, platform setup
godot-project-setupScaffold directory structure, autoloads, .gitignore, input maps
godot-brainstormingScene tree planning, node selection, architectural decisions
godot-grillSettle open design decisions in rounds — scope first, each question with a recommended answer, recorded
godot-code-reviewReview checklist — best practices, anti-patterns, Godot pitfalls
godot-debuggingRemote debugger, print techniques, signal tracing, error patterns
godot-testingTDD with GUT and gdUnit4 — test structure, mocking, CI
godot-mentorTeaching mode — concept, editor setup, annotated code, verification, one next step

Architecture & Patterns (6 skills)

SkillDescription
scene-organizationScene tree composition, when to split scenes, node hierarchy
state-machineEnum-based, node-based, resource-based FSM with trade-offs
event-busGlobal EventBus autoload with typed signals, decoupled communication
component-systemHitbox/Hurtbox/Health components, composition over inheritance
resource-patternCustom Resources for items, stats, config, editor integration
dependency-injectionAutoloads, service locators, @export injection, scene injection

Physics, 2D/3D & XR (4 skills)

SkillDescription
physics-systemRigidBody, Area, raycasting, collision shapes, Jolt, ragdolls, interpolation
2d-essentialsTileMaps, parallax, 2D lights/shadows, particles, custom drawing, canvas layers
3d-essentialsMaterials, lighting, shadows, environment, GI, fog, LOD, occlusion, decals
xr-developmentOpenXR, XROrigin3D, hand tracking, controllers, passthrough, Meta Quest

Gameplay Systems (13 skills)

SkillDescription
player-controllerCharacterBody2D/3D movement — top-down, platformer, first-person
input-handlingInputEvent system, Input Map actions, controllers/gamepads, mouse/touch, action rebinding
animation-systemAnimationPlayer, AnimationTree, blend trees, state machines, sprite animation
tween-animationTween class, easing, chaining, parallel sequences, common motion recipes
audio-systemAudio buses, music management, SFX pooling, spatial audio, interactive music
inventory-systemResource-based items, slot management, stacking, UI binding
dialogue-systemBranching dialogue trees, conditions, UI presentation
save-loadConfigFile, JSON, Resource serialization, version migration
ai-navigationNavigationAgent2D/3D, steering behaviors, patrol patterns, async baking
ability-systemResource-based abilities, cost/cooldown/cast, buffs/debuffs, stat modifiers, gameplay tags, HUD binding
camera-systemSmooth follow, screen shake, camera zones, transitions
localizationTranslationServer, CSV/PO files, locale switching, RTL support, pluralization
procedural-generationNoise, BSP dungeons, cellular automata, WFC, seeded randomness

UI/UX (3 skills)

SkillDescription
godot-uiControl nodes, themes, anchors, containers, layout patterns
responsive-uiMulti-resolution scaling, aspect ratios, DPI, mobile adaptation
hud-systemHealth bars, score displays, minimap, damage numbers, notifications

Multiplayer & Web Services (4 skills)

SkillDescription
multiplayer-basicsMultiplayerAPI, ENet/WebSocket, RPCs, authority model
multiplayer-syncMultiplayerSynchronizer, interpolation, prediction, lag compensation
dedicated-serverHeadless export, server architecture, lobby management
web-servicesHTTPRequest, REST/JSON API clients, downloads, TLS, WebSocket clients

Rendering & Visual (3 skills)

SkillDescription
rendering-pipelineRenderer per platform, lighting strategy, AA, FSR/resolution scaling, SubViewports, graphics settings
shader-basicsGodot shader language, visual shaders, common recipes, post-processing
particles-vfxGPUParticles2D/3D, process materials, subemitters, trails, attractors, collision

Build & Deploy (6 skills)

SkillDescription
export-pipelinePlatform exports, CI/CD with GitHub Actions, itch.io/Steam deploy
godot-optimizationProfiler, draw calls, physics tuning, object pooling, bottlenecks
addon-developmentEditorPlugin, @tool scripts, custom inspectors, dock panels
assets-pipelineImage compression, 3D scene import, audio formats, resource management
mobile-developmentAndroid/iOS export, signing, lifecycle, permissions, plugins, IAP, device features
web-exportBrowser builds, threads vs COOP/COEP headers, itch.io/self-hosting, PWA, JavaScriptBridge

Scripting (4 skills)

SkillDescription
gdscript-patternsStatic typing, await/coroutines, lambdas, match, exports, common idioms
gdscript-advancedPerformance idioms, metaprogramming, @tool lifecycle, profiler-driven depth
csharp-godotC# conventions, GodotSharp API, project setup, GDScript interop
csharp-signals[Signal] delegates, EmitSignal, async awaiting, event architecture

Native & Performance (2 skills)

SkillDescription
gdextensiongodot-cpp (C++) / gdext (Rust) native extensions, class binding, building, interop
multithreadingWorkerThreadPool, Thread/Mutex/Semaphore, call_deferred, threaded resource loading

Math & Data (1 skill)

SkillDescription
math-essentialsVectors, transforms, interpolation, curves, paths, RNG, game math recipes

Third-Party Addons (5 skills)

These skills cover community addons with pinned versions — LimboAI v1.8.1, Beehave v2.9.3, Popochiu v2.2.1, Dialogue Manager v4.2.0, and Phantom Camera v0.11.0.4. They require the corresponding addon to be installed in your project.

SkillDescription
limboaiLimboAI addon — behavior trees + hierarchical state machines, visual editor, blackboard, BTTask subclassing (Godot 4.6+, C++ GDExtension)
beehaveBeehave addon — pure-GDScript behavior trees, composites/decorators/leaves, blackboard, visual runtime debugger (GDScript-only)
popochiuPopochiu addon — point-and-click adventure framework: rooms, characters, inventory, dialogs, command GUI (Godot 4.7; 2.1.x on 4.6, GDScript-only)
dialogue-managerDialogue Manager addon — .dialogue syntax, cues, runtime balloons, conditions/mutations, actionable nodes (Godot 4.6+, GDScript + C#)
phantom-cameraPhantom Camera addon — priority-based camera switching, follow/look-at modes, tweened transitions (Godot 4.4+, GDScript + C#, pre-1.0)

Validation

Quality is enforced by an automated validator that runs on every pull request, every push to master, and 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 CI

The validator (scripts/validate-skills.mjs) checks every skills/*/SKILL.md and agents/*.md against these rules. scanner-risky-approval covers the whole repository. Additional metadata checks keep the generated Codex mirrors, the machine-readable skill index, and the cross-host smoke matrix current:

RuleWhat it checksSeverity
frontmatter-{missing,name-missing,description-missing,name-mismatch}YAML frontmatter is present and name matches foldererror
cross-ref-brokenEvery skill referenced on the **Related skills:** line and inline see <skill> skill mentions resolves to an existing skill foldererror
agent-frontmatter-{missing,name-missing,description-missing}An agents/*.md file has YAML frontmatter with name and descriptionerror
agent-skill-path-brokenEvery skills/<name>/SKILL.md path inside an agent definition existserror
related-skills-line-missingSkill has a **Related skills:** line between H1 and first sectionwarning
csharp-parity-missing / csharp-parity-acceptedEvery section with a GDScript code block also has a C# block (skills allowlisted as GDScript-only-by-design emit accepted instead of missing)warning
csharp-parity-exempt-no-reasonA csharp-parity: n/a marker in a section states a reason. Checked for every marker, not only where C# is missing, so a reasonless marker cannot hide until the section is editederror
csharp-parity-{missing,accepted}-referenceThe same parity check for skills/<name>/references/*.md, section by section (or the whole file when it has no headings); allowlisted GDScript-only skills and n/a sections emit acceptedwarning
checklist-missingImplementation checklist (- [ ] items) present near end of filewarning
token-budget-exceededSKILL.md < 16 KB (references under skills/<name>/references/ are unrestricted)error
token-budget-approachingSKILL.md ≥ 15.5 KB and < 16 KB — advisory heads-up before the hard budgetwarning
orphan-referenceEvery references/*.md file is linked from its parent SKILL.mdwarning
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 payloaderror
card-emptyThe card region is non-empty — otherwise the hook would inject nothing while CI stayed greenerror
card-oversizedThe card region is ≤ 3 KB — it is injected on every session start and every compactionerror
card-skill-missingEvery skill named in CARD_SPECS exists, so deleting one fails CI instead of silently skipping its checkerror
gdscript-nonexistent-apiNo GDScript code block in a SKILL.md or references/*.md uses an API already caught being invented: Signal.any() / Signal.all(), or the C#-only ToSignal(). Prose is not scanned. It is a denylist, so it cannot prove an API existserror
scanner-risky-approvalNo .md, .json, .toml, .yml or .yaml file writes out a setting the plugin scanner in plugin-scan.yml flags: a full-access sandbox mode, a never-ask approval policy, or a bypass approval mode. Comments and prose count, as they do for the scanner. In a git work tree it checks the files a clone would hold (tracked, or untracked and not ignored)error

Hook behaviour is covered separately by npm run test:hooks (51 cases), which also runs on release tags. Metadata coverage now also includes node scripts/sync-codex-agents.mjs --check, node scripts/generate-skill-index.mjs --check, and node scripts/validate-platform-metadata.mjs.

Token cost reporting:

npm ci --prefix scripts   # once: the tokenizers live in scripts/, not the plugin root
node scripts/count-tokens.mjs --tokenizer --markdown

Produces 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 the version-consistency check, node scripts/validate-skills.mjs, the hook tests, the validator tests, the metadata tests, and the broken-fixture self-test on every v*.*.* push. The release is blocked if any of those fail 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: 0 errors, 57 warnings on node scripts/validate-skills.mjs in this repository state. All 57 are intentional csharp-parity-accepted warnings for GDScript-only content. 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.

Behaviour is measured with claude plugin eval suites in evals/ — mentor mode, godot-grill, the session card, and a set of domain skills — each run with and without the plugin; results are recorded in evals/FOLLOWUPS.md, evals/GRILL.md and evals/SKILLS.md, and skill routing (when a skill should and should not load) in evals/TRIGGERS.md. Since v1.15.1 every code example has also been parsed (GDScript) or compiled (C#) against Godot 4.7.2; the 4.8 examples added in v1.17.0 against 4.8-beta3 and Godot.NET.Sdk 4.8.0-beta.3 (.NET 10).

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. Cross-host release smoke coverage is tracked in tests/agent-integration/host-smoke-matrix.json.

Contributing

See CONTRIBUTING.md for how to add new skills, conventions, and testing requirements.

Acknowledgements

The SessionStart hook's polyglot Windows wrapper, JSON escaper, and platform output branching are adapted from Superpowers by Jesse Vincent (MIT).

License

MIT

Author

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.