godot-clarity

Godot Clarity

Русская версия

Godot Clarity is an open-source Agent Skill that helps coding agents create, extend, debug, review, and verify reliable Godot 4 projects written in GDScript.

Godot Clarity is an independent community project. It is not affiliated with or endorsed by the Godot Foundation.

Status and compatibility

• Status: 0.1.0-rc.2 release candidate; final 0.1.0 promotion requires the comparative fresh-agent release gate
• Reference and CI baseline: Godot 4.7.1
• Deterministic runtime suite: 8 broken-baseline/reference-solution fixtures
• Directly supported: Godot 4.7.x, GDScript, 2D and 3D
• Best effort: Godot 4.0–4.6, using documentation for the project's exact minor version
• Outside the current core scope: Godot 3.x, C#, GDExtension, engine modules, and console-specific SDK work

The Skill is a portable package following the Agent Skills specification. It is not a model, editor plugin, engine addon, or generated-code framework.

What it improves

Godot features rarely live in one script. Their behavior is split across .gd, .tscn, .tres, project.godot, imported resources, engine callbacks, and runtime state. Godot Clarity teaches agents to trace and verify that complete system.

Its strongest release gates include:

• version-aware Godot 4 and GDScript guidance;
• safe scene, Node, Resource, owner, signal, and lifecycle decisions;
• project creation through a playable vertical slice instead of speculative frameworks;
• explicit InputMap, UI focus/layout, animation, audio, navigation, save, network, renderer, and export contracts;
• a mandatory collision workflow covering shapes, body types, layers/masks, movement units, contacts, CCD/sweeps, and 2D/3D differences;
• behavioral verification with a version-matched Godot executable instead of “the code looks correct.”

Detailed knowledge is loaded on demand from focused references, so ordinary tasks do not pay the context cost of an all-in-one Godot manual.

Install

Installer CLI

The release-candidate npm channel installs the verified Skill archive without a manual download:

npx godot-clarity@next init --ai codex
npx godot-clarity@next init --ai codex --global
npx godot-clarity@next init --ai claude --global

Project scope is the default. Use --global for all local projects owned by the current user, or --project-dir /path/to/project for a different project directory.

The CLI requires Node.js 22 or newer. It downloads the pinned GitHub Release over HTTPS, verifies its embedded SHA-256, validates the archive layout, installs through a staging directory, and refuses to overwrite an existing installation. It does not require a GitHub account, API key, administrator access, or a project-owned server.

If Windows PowerShell blocks npx.ps1 because of its execution policy, run the same command with npx.cmd.

Manual installation

Clone or download this repository first. Install only the skills/godot-clarity directory; repository documentation, CI, and eval oracles are intentionally outside the Skill package.

Codex

Project scope:

mkdir -p .agents/skills
cp -R /path/to/godot-clarity/skills/godot-clarity .agents/skills/godot-clarity

User scope:

mkdir -p ~/.agents/skills
cp -R /path/to/godot-clarity/skills/godot-clarity ~/.agents/skills/godot-clarity

Invoke it explicitly with $godot-clarity, or let Codex select it from the request. Codex also supports symlinked Skill directories for local development. See OpenAI's Skill documentation.

PowerShell equivalent for project scope:

New-Item -ItemType Directory -Force .agents\skills | Out-Null
Copy-Item C:\path\to\godot-clarity\skills\godot-clarity .agents\skills\godot-clarity -Recurse

Claude Code

Project scope:

mkdir -p .claude/skills
cp -R /path/to/godot-clarity/skills/godot-clarity .claude/skills/godot-clarity

User scope:

mkdir -p ~/.claude/skills
cp -R /path/to/godot-clarity/skills/godot-clarity ~/.claude/skills/godot-clarity

Invoke it with /godot-clarity, or use a request that matches its description. See Claude Code's Skill documentation.

On PowerShell, use the same copy command with .claude\skills\godot-clarity as the destination.

Other agents

Point any Agent Skills-compatible client at skills/godot-clarity. If a client uses a different discovery directory, copy or symlink that package into the client-specific location without changing SKILL.md.

Use

Examples:

$godot-clarity Create a small Godot 4.7 platformer vertical slice with keyboard and controller input. Verify the main scene headlessly.

$godot-clarity Diagnose why this Area2D never detects the player. Inspect both scenes, layers, masks, shapes, and signals, then prove the fix at runtime.

$godot-clarity Review this save system for schema migration, Resource sharing, and unsafe object deserialization. Do not edit files.

The Skill supports four operating modes: create, extend, debug, and review. It records assumptions only when a missing decision materially changes the implementation, preserves established project conventions, and reports exactly what was and was not verified.

Repository layout

skills/godot-clarity/  Portable installable Skill
  SKILL.md             Core workflow and reference routing
  references/          Focused Godot/GDScript guidance
  agents/openai.yaml   Optional Codex UI metadata
evals/                 Agent prompts, broken fixtures, solutions, and runtime oracles
scripts/               Dependency-free repository and eval runners
release/               Pinned portable Skill artifact metadata
cli/                   Cross-platform Node.js installer and tests
.github/workflows/     Release validation on the pinned Godot version

Validate

Static repository validation:

python scripts/validate_repo.py

Reproducible Skill archive tests:

python scripts/test_package_skill.py

CLI tests and package inspection:

npm ci
npm test
npm pack --dry-run

On Windows PowerShell, use npm.cmd for these development commands if npm.ps1 is blocked.

Runtime fixtures, using a local Godot 4.7.1 executable:

python scripts/run_evals.py --godot /path/to/godot --mode all

baseline mode proves each fixture actually reproduces its intended failure. solutions mode overlays the hidden reference fix and proves the same behavioral oracle passes. This deterministic suite validates fixtures and guidance targets; it does not replace fresh-agent with-Skill/without-Skill evaluations described in CONTRIBUTING.md.

Build the portable release archive:

python scripts/package_skill.py --version 0.1.0-rc.2

The rc.1 guidance evaluation report remains applicable because rc.2 changes delivery and packaging, not the portable Skill guidance. Deterministic engine validation is complete; the wider repeated with-Skill/without-Skill campaign remains a final-release gate.

Design boundaries

Godot Clarity does not try to copy the Godot manual, dictate one universal architecture, or make unverifiable gameplay claims. References capture high-leverage failure modes and decision rules, then link to versioned official documentation for exact APIs.

It also does not bundle Godot binaries, third-party assets, generated projects, or evaluation solutions inside the installed Skill.

Contributing

Read CONTRIBUTING.md before proposing a rule or fixture. Every new rule should address an observed agent failure, state when it applies, avoid project-specific dogma, cite versioned primary documentation where appropriate, and include a way to evaluate the resulting behavior.

License and trademarks

Godot Clarity is released under the MIT License. See NOTICE.md for attribution and trademark information.

“Godot” and the Godot logo are trademarks of the Godot Foundation. This project does not use the Godot logo as its own mark. See the Godot Foundation trademark policy.