SkillAgentSearch skills...

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-expert

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

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.

Substance
30/30
Structure
17/20
Description
15/15
Adoption
13/20
Freshness
15/15

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 found

Our 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.

SkillScoreStarsUpdatedFormat
scenario-godot-expert (this skill)by scenario-labs891.0k35d agoSKILL.md
taste-skillby Leonxlnx100120.0ktodayCLAUDE.md
Agent-Reachby Panniantong100114.0ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md
rufloby ruvnet10082.3ktodayCLAUDE.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.

name: 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)

  1. 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_RESULT envelope 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).
  2. 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 .tscn files 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].
  3. 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_ms and cpu_ms (observed).
  4. Look AND check. Every frame goes through gd_review.image_checks and 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).
  5. 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]).
  6. 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, while Input.parse_input_event never reaches a MOUSE_FILTER_STOP Control (scenario-godot-gameplay, scenario-godot-ui, observed); pass true so positions are logical, not window pixels. Levels hold a spawn point, not the player (Godotneers [00:56:56]).
  7. Edits persist only with owner and a save. add_child alone is invisible in the Scene dock and lost on save (Godot docs, Running code in the editor); script edits bypass Undo unless routed through EditorUndoRedoManager (Queble, nW7YtSSJzbQ [00:04:41]).
  8. Be honest about visual editors. VisualShader, AnimationTree, the TileSet and theme editors, and the particle inspector are visual; the agent writes .gdshader, .tres/.tscn text, 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)

  1. Brief in numbers. Budgets per platform, resolution, scale, style. GATE: every later check has a number to compare with.
  2. Project. gd_env.base_project("3d"|"2d", dest) (APFS clone, 0.01 s, its own user:// folder) or new_project(...), which writes the project-manager defaults a hand-written project.godot lacks. GATE: audit(P, "project") has no flags.
  3. 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.
  4. Build one stage with small idempotent jobs (get-or-create, owner set, explicit save). Route domain work to its owner (below).
  5. Measure. Audit, tests (run_tests), profile_scene plus gd_stat.budget_check, or the export result. GATE: numbers against the brief.
  6. Look AND check. Same views, image_checks, contact sheet opened, judged with the domain skill's critique. GATE: no flag that sets ok false, the change visible (compare changed_fraction above 0).
  7. Fix before advancing, one change at a time; compare proves parity or gain.
  8. 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

View on GitHub
GitHub Stars1.0k
CategoryDevelopment
Updated1mo ago
Forks129

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions