scenario-godot-expert
Use when an agent drives Godot 4.7 on macOS or Windows for any task: headless --script jobs, --import, --check-only, command-line exports, GUT tests, windowed screenshots, the headless editor (-e) or an MCP server into a running editor; when a run hangs or fails silently, a capture is black, Godot 3…
Install / Use
npx skills add scenario-labs/skills --skill scenario-godot-expertInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of scenario-godot-expert
scenario-godot-expert scores 89/100 on our quality scale, 1615th of 4,705 Development & Engineering skills we index (top 35%).
Its SKILL.md is 23 KB long, well organised into 13 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
With 1,048 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated 35 days ago, so scenario-godot-expert is actively maintained.
- Our last check on 2026-11-22 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.
Automated pattern scan on 2026-11-20. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
scenario-godot-expert compared with similar skills
All 4 of these similar skills score higher than scenario-godot-expert; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| scenario-godot-expert (this skill)by scenario-labs | 89 | 1.0k | 35d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 120.0k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
Frequently asked questions
- How do I install scenario-godot-expert?
- Run
npx skills add scenario-labs/skills --skill scenario-godot-expert. The install tabs above show the steps for each supported agent. - Which AI agents does scenario-godot-expert work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is scenario-godot-expert safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is scenario-godot-expert still maintained?
- The repository was last updated 35 days ago, so scenario-godot-expert is actively maintained.
Skill content
View source on GitHubname: scenario-godot-expert description: "Use when an agent drives Godot 4.7 on macOS or Windows for any task: headless --script jobs, --import, --check-only, command-line exports, GUT tests, windowed screenshots, the headless editor (-e) or an MCP server into a running editor; when a run hangs or fails silently, a capture is black, Godot 3 code breaks in 4.x, 'Identifier not found', export templates are missing; or when a Godot brief (2D, 3D, shaders, VFX, UI, multiplayer, export) must go to the right scenario-godot-* specialist." license: MIT
Godot expert (technical director and agent protocol)
Target: Godot 4.7.2.stable (standard build, no C#), macOS Apple Silicon with Metal by default, or Windows with D3D12.
Expert Godot work is a loop run against evidence: set the budget, build one stage, measure it, look
at it, fix it, advance. An agent without a mouse gets there by picking the right channel, passing
only on a machine-readable result, and never trusting one signal alone. This skill is that protocol,
the shared toolkit every scenario-godot-* skill calls (scripts/), and the map of the
team. If a sibling skill named here is missing from your available skills, load it with skill_get
(Scenario MCP) or ask the user to install it (https://github.com/scenario-labs/skills#install);
unattended, proceed from tool schemas and flag the gap.
Status (2026-10-02): every toolkit function below ran in Godot 4.7.2 here (23 live tests, 17
offline, all pass; references/procedures.md).
Stance (the expert delta)
- Headless output is the truth; the editor's Output panel is not. MCP servers that scrape it
"report errors for lines no longer on disk", and it does not list every project error (Fennara,
2vSYP7GyA5U [00:02:51, 00:06:20]). PixelLab's agent runs the Godot binary itself and reads the
console (THwZYWuOdZI [00:13:45]). Pass on the
AGENT_RESULTenvelope plus a log scan, never on "it exited": a script with a parse error exits 0, with or without--check-only, and so does a script path Godot cannot find (version deltas, verified; L6). - One writer per project. A GUI editor holding a project keeps its own copy of the open scenes,
so its next save can overwrite a headless edit [added]; merged
.tscnfiles can fail to parse (Lilith Duncan, CAJ_iIedx_I [00:01:36]). The toolkit refuses a project a GUI Godot has open; work through that editor (MCP) or ask the user to close it. Never close a Godot or Blender process you did not start [added]. - Milliseconds against a budget, on the target. Measure before optimizing (Dan Does Dev,
s2C2RO_WMh0 [00:07:12]); profile on the real device class, thermals included (Ian Bolton,
WrjaUNAXYqk [00:09:35]). Headless frame time is loop time, not game cost; windowed frame time on
this Mac is pinned to the display refresh; judge
gpu_msandcpu_ms(observed). - Look AND check. Every frame goes through
gd_review.image_checksand a contact sheet you open. Headless draws nothing, so captures need a windowed run (observed). After AI asset import, check facing, animation direction, tile seams and camera jitter by eye (PixelLab, THwZYWuOdZI). - Tests are the contract. Assert on signals and public results, not internals (Godotneers, CreugthdgJ0 [01:08:36]; Butch Wesley, ImqhHLlPfZg [00:16:59]; Mike Schulze, x6GdTgIAFiU [00:24:19]); bound every await (2 s Godotneers, 5 s Schulze); prove the test bites by emptying the function and watching it go red (Wesley [00:13:40]).
- Design for a mouseless driver. Split body and brain so a test brain can steer a character
(Godotneers [00:18:14]). Headless has no mouse device (Wesley [00:48:33]), yet GUI input still
tests headless:
get_viewport().push_input(event, true)reaches Controls, whileInput.parse_input_eventnever reaches a MOUSE_FILTER_STOP Control (scenario-godot-gameplay, scenario-godot-ui, observed); passtrueso positions are logical, not window pixels. Levels hold a spawn point, not the player (Godotneers [00:56:56]). - Edits persist only with
ownerand a save.add_childalone is invisible in the Scene dock and lost on save (Godot docs, Running code in the editor); script edits bypass Undo unless routed throughEditorUndoRedoManager(Queble, nW7YtSSJzbQ [00:04:41]). - Be honest about visual editors. VisualShader, AnimationTree, the TileSet and theme editors,
and the particle inspector are visual; the agent writes
.gdshader,.tres/.tscntext, or builds the resource in code, and names the GUI path for a human. Pick an MCP by feedback fidelity, not tool count (Fennara [00:09:22]).
Execution channels
| Channel | Use for | Cost (measured here) | Rules |
| --------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Headless job gd_run.run_script | logic, data, audits, scene building, imports, tests, exports | 0.2 s for a small job; --import about 2 s | default channel; watchdog ends a hung job (exit 124) |
| Windowed job capture_scene, capture_sequence, profile_scene | anything that must render: screenshots, sequences, GPU time | about 1 s for 4 views warm; first capture in a fresh project 10.8 s, a 5 s profile 29.6 s | 160x90 window, SubViewport at the requested size, focus handed back (2 restores per run observed); GD_MAX_WINDOWED 2 |
| Headless editor run_script(editor=True) | EditorInterface: open, edit and save scenes; EditorFileSystem | 1.1 s | wait 2 frames before editor calls; without -e EditorInterface calls fail (observed) |
| GUI editor + MCP (hybridindie godot-editor-mcp) | the user's open editor: live tree, selection, undoable edits | stdio probe 0.9 s, 23 tools exposed by default | only when the user has the editor open; project-local .mcp.json only (gd_live.write_mcp_config) |
| Running game + MCP (tugcantopaloglu) | drive a running game (input, eval) | not run here | clone, npm run build, a game autoload on port 9090 |
gd_live.channels(P) reports what is possible now. Prefer the headless channels; add an MCP for
live scene inspection.
Establish first
Ask once, then run: target platforms and lowest device; frame budget (default 60 fps desktop, 30 fps
mobile); 2D or 3D; renderer (Forward+ desktop 3D, Mobile for demanding phones, Compatibility for web
and widest reach, after Ray Hayes, KWhVVMpihsc [00:06:03]); art style and pixel art or not; whether
the user's editor has the project open; the deliverable. Then gd_live.channels(P) and
gd_run.audit(P, "project"), and write the renderer, physics engine (Jolt for 3D), stretch mode,
main scene and autoloads into the plan.
Workflow (the expert loop)
- Brief in numbers. Budgets per platform, resolution, scale, style. GATE: every later check has a number to compare with.
- Project.
gd_env.base_project("3d"|"2d", dest)(APFS clone, 0.01 s, its ownuser://folder) ornew_project(...), which writes the project-manager defaults a hand-writtenproject.godotlacks. GATE:audit(P, "project")has no flags. - Baseline.
check_all(P),audit(P, "scene", scene=...), captures from fixed views, a profile if performance matters. GATE: zero parse and script errors; flags fixed or listed; sheet opened. - Build one stage with small idempotent jobs (get-or-create,
ownerset, explicit save). Route domain work to its owner (below). - Measure. Audit, tests (
run_tests),profile_sceneplusgd_stat.budget_check, or the export result. GATE: numbers against the brief. - Look AND check. Same views,
image_checks, contact sheet opened, judged with the domain skill's critique. GATE: no flag that setsokfalse, the change visible (comparechanged_fraction above 0). - Fix before advancing, one change at a time;
compareproves parity or gain. - Deliver with evidence. Each step with its toolkit call, then Verified (what ran, result file, number or frame) and Assumed (not run, defaults). Never call a scene, shader, level or build done without numbers and a frame you looked at.
Shared toolkit (scripts/, the contract for every scenario-godot-* skill)
import sys; sys.path.insert(0, "<scenario-godot-expert>/scripts"). System python3, standard
library (Pillow optional).
Every gd_env, gd_run, gd_review, gd_stat and gd_live call, with defaults and return
values: references/procedures.md section 1. Most used:
gd_env.new_project, gd_run.run_script, gd_run.capture_scene, gd_run.profile_scene,
gd_run.export, gd_review.image_checks.
Every gd_run run returns ok, error, result (the job's dictionary), exit_code, timed_out,
parse_errors, script_errors, shader_errors, engine_errors, warnings, leaks, log_path,
result_path. Output lands in <project>/.agent_out/ (carries .gdignore). Concurrency: GD_MAX
(6) Godot processes, GD_MAX_WINDOWED (2), one per project, all through gd_run.godot_slot;
GodotBusy when a GUI editor holds the project.
A domain job is a GDScript file in the project (AgentKit, scripts/agentkit/,
is copied to res://addons/agentkit/):
extends "res://addons/agentkit/agent_job.gd"
func run() -> Dictionary:
var scene := await load_scene("res://main.tscn", 2) # in the tree, 2 frames waited
note("children", scene.get_child_count())
return {"ok": true, "speed": arg("speed", 4.0)} # arg() typed by its default
Or a method on any RefCounted script, run_script(P, "res://tools/x.gd:build", args) (it receives
the job). Errors logged during the job flip ok to false unless expect_errors is set. A script
error aborts a typed run() -> Dictionary, which then returns {}: an empty result always fails
(aborted: true), even with expect_errors, so return at least {"ok": true}. export reports
bytes for every file it wrote (main_bytes for the named one) and treats an iOS
export_project_only Xcode project as the artifact. Captures emulate the project stretch (keep,
keep_width, keep_height, expand, ignore, integer scale, scale factor, viewport mode) with black
bars, matching the engine on 15 cases (L20); in your own job read a make_viewport SubViewport with
agent_capture.grab(vp). Helpers: arg, out_path, load_scene, wait_frames,
wait_physics_frames, wait_seconds, note, is_headless, captured_errors; libraries
agent_build.gd (save_scene, presets),
agent_profile.gd (record). Domain code goes in
scripts/gd_<domain>.py and scripts/agentkit/<domain>/.
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
120.0kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
