CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

godot-superpowers — a Claude Code plugin (and drop-in .claude/ config) that gives Claude full-spectrum Godot 4.x game-development capability across any genre. It contains skills, subagents, hooks, and MCP defaults — no game code lives here.

Targets Godot 4.3+. All technical content tracks the official Godot docs and GDScript style guide.

Layout

.
├── .claude-plugin/plugin.json    # plugin manifest. `skills` MUST be declared as an **array of individual skill paths** (e.g. `["./skills/foo", "./skills/bar"]`) — empirically NOT auto-discovered (v1.12.2 attempted to omit the field; result was 0 skills registered, fixed in v1.12.3). `agents/`, `hooks/hooks.json`, and `.mcp.json` ARE auto-discovered by convention and must NOT be declared in the manifest. Earlier versions (≤1.12.1) shipped `"skills": "./skills/"` as a string — the loader expects an array, so string values are silently dropped (zero skills registered). Validator now enforces array-of-paths matching the on-disk skill directories.
├── .claude-plugin/marketplace.json # marketplace listing (single-plugin marketplace) — version must stay in lock-step with plugin.json
├── agents/                       # 15 subagents (auto-discovered when plugin-loaded)
├── skills/                       # 33 skills (each <name>/SKILL.md) — every directory MUST be listed in plugin.json `skills` array (validator enforces 1:1 parity)
├── hooks/hooks.json              # GENERATED mirror of `settings.json`'s `hooks` block (auto-regenerated by `scripts/validate.sh`). Read by Claude Code in plugin mode by convention; do NOT edit by hand.
├── .mcp.json                     # recommended MCP servers — auto-discovered by convention (no explicit field in plugin.json). Strict to the MCP schema: no `_tier` / `_purpose` annotations inline.
├── .claude-plugin/mcp-meta.json   # human-readable tier + purpose per MCP server (sidecar — keeps `.mcp.json` strict-schema-clean)
├── settings.json                 # CANONICAL source for permissions + hooks (drop-in mode + plugin mode). The `hooks` block here is the only source of truth; `hooks/hooks.json` is generated from it.
├── settings.local.json           # MCP enables (gitignored on real projects); see `settings.local.json.example` for the template
├── scripts/                      # repo tooling: sync-hooks.sh, validate.sh, hooks/*.sh (per-hook helpers invoked from settings.json)
├── LICENSE                       # MIT
├── README.md                     # plugin overview for end users
└── CLAUDE.md                     # this file

Editing rules for this repo

When editing skills or agents in this directory:

• Skill bodies are end-user docs. Be concrete: full code blocks, exact file paths, no abstract handwaving.
• Cite the official Godot doc URL when explaining a non-obvious technical claim.
• The "Authoritative source" rule (verify Godot APIs via godot-docs MCP before emitting code) lives ONLY in the auto-loaded dispatcher (using-godot-superpowers). Do NOT duplicate the callout in individual skills or agents. The dispatcher is loaded on every Godot session via its paths glob, so the rule is always in context. The validator enforces this: dispatcher MUST carry the callout, every other file MUST NOT.
• Frontmatter description is the discovery hook — first sentence must contain the keywords a user would naturally use ("scaffold a player scene", "fix Godot 3 to 4 syntax", "configure collision layers").
• Keep skills self-contained. Cross-references between skills are fine, but a skill should be useful read in isolation.
• English only. Italian / other languages live in language packs (separate plugins).
• No project-specific content. No card-game shortcuts, no genre assumptions baked into core skills (genre packs are explicit opt-in).

Developing this plugin

This repo IS the plugin — no separate dist/ step. Two source-of-truth conventions matter:

1. Hooks: settings.json .hooks is the single source of truth (canonical for drop-in mode). hooks/hooks.json is a generated mirror that Claude Code reads in plugin mode (--plugin-dir / marketplace) by convention — plugin.json does NOT declare it explicitly. Never edit hooks/hooks.json by hand; scripts/validate.sh auto-regenerates it from settings.json on every run, so drift is impossible. scripts/sync-hooks.sh is kept as a convenience for manual regeneration but the validator no longer needs it.
2. Versions: .claude-plugin/plugin.json and .claude-plugin/marketplace.json MUST share the same version. The validator enforces lock-step.
3. Skill / agent frontmatter: every skill must have name + description; every agent must have name. The validator enforces this.

Local test loop

# 1. Validate the plugin self-consistency
scripts/validate.sh

# 2. Try the plugin against a real (or scratch) Godot project
claude --plugin-dir /Users/you/Code/claude-gamedev /path/to/godot/project

# 3. Or drop it in directly:
cp -R agents skills hooks scripts settings.json .mcp.json /path/to/godot/project/.claude/
cp settings.local.json.example /path/to/godot/project/.claude/settings.local.json
# settings.local.json is gitignored in this repo — copy from the tracked .example template

Pre-commit / pre-publish checklist

• scripts/validate.sh returns PASS
• All JSON parses (jq empty <file>)
• New skill added → README catalog + CLAUDE.md catalog updated, both skill counts updated
• New skill cross-references existing skill → use [name](../<dir>/SKILL.md), validator confirms link resolves

Hooks (active in this repo + delivered to consumers)

Do not bypass these hooks (no --no-verify, no skipping format) without user request.

Note (PostToolUse spawn overhead): the four PostToolUse hooks (gdformat-gd.sh, check-tscn.sh, dep-integrity.sh, verifier-reminder.sh) all bind to matcher: "Edit|Write" and therefore run on every write — including non-Godot files (markdown, JSON, YAML). Each script early-exits in the file-extension switch, but the shell spawn cost is not free. This is intentional: Claude Code's hook matcher does not currently support per-extension globs at the hook-config level, so filtering happens inside the script. If Claude Code adds path/extension matchers to hook configuration, prefer those to eliminate the spawn overhead.

Note (Stop gdlint coverage): the Stop hook runs gdlint only against scripts/ and autoload/ if those directories exist. GDScript stored elsewhere (src/, entities/, player/, addon directories, project root) is NOT auto-linted on Stop. This is intentional to keep Stop output cheap. Projects with non-standard layouts can either (a) add their custom paths to scripts/hooks/stop-gdlint.sh, or (b) run gdlint <path> manually as part of pre-commit. The code-reviewer agent always lints whatever file it reviews regardless of path.

Hook environment variables

Claude Code sets these in the environment of every hook script. Honor them; do not invent new ones without updating this list.

• CLAUDE_FILE_PATHS — comma-separated list of paths the tool wrote (PostToolUse Edit/Write).
• CLAUDE_PROJECT_DIR — project root, absolute path.
• CLAUDE_COMMAND — bash command being evaluated (PreToolUse Bash).
• CLAUDE_AGENT_NAME — name of the active subagent if any; empty in main context.
• CLAUDE_SUBAGENT — 1 when running inside a subagent, otherwise unset. Hooks that should fire only in main context (e.g. verifier-reminder.sh) gate on CLAUDE_AGENT_NAME non-empty OR CLAUDE_SUBAGENT=1.
• CLAUDE_PLUGIN_ROOT — plugin install path; falls back to $CLAUDE_PROJECT_DIR/.claude in drop-in mode. Hook helpers resolve via ${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/scripts/hooks/<name>.sh.
• CLAUDE_GIT_OVERRIDE — if 1, the git-guard's destructive-git block is skipped (the shell-pattern block still applies). Manual escape hatch — set per-command, never export globally.

Skill catalog (33)

Design gates (auto-loaded; precede everything else):

• using-godot-superpowers — auto-loaded dispatcher (paths: ["**/*.gd", ...]); enforces design-before-code + verifier-after-write rule; routes greenfield vs feature trail
• game-brainstorming — idea → approved GDD via structured Q&A; soft-gates implementation skills (opt-out via /skip-design) (greenfield trail)
• writing-game-plan — approved GDD → approved milestone plan; soft-gates implementation skills (opt-out via /skip-design) (greenfield trail)
• codebase-survey — read-only map of files / APIs / hotspots a planned feature will touch on an existing project (feature trail, step 1)
• feature-spec — approved survey → approved feature spec; design delta on top of GDD (feature trail, step 2)
• feature-plan — approved feature spec → approved feature plan; soft-gates implementation skills (opt-out via /skip-design) (feature trail, step 3)

Execution / Orchestration:

• subagent-dev-mode — orchestrator + worker + verifier loop for milestones (3+ files / 2+ subsystems); keeps main-context tokens flat

Foundation (run early in a project's life, AFTER plan approved):

• bootstrap-godot-project — full directory + autoload scaffold
• setup-git-godot — .gitignore + .gitattributes + Git LFS for binary assets
• godot-patterns — Godot 4.x reference (auto-loads on .gd/.tscn)
• setup-collision-layers — 11-layer scheme for 2D + 3D physics
• setup-input-map — standard actions + remap UI
• setup-save-system — Resource-based save/load
• save-schema-migration — version save data + sequential migrations + fixture tests
• setup-localization — CSV / gettext i18n, language switcher, font fallback
• ui-patterns-godot — Theme + StyleBox, focus chain, _unhandled_input vs _gui_input, stretch/scale, accessibility floor
• networking-foundation — High-Level Multiplayer patterns: ENet/WebSocket, MultiplayerSpawner/Synchronizer, @rpc annotations, authority model

Scaffolding (one-off generation):

• create-scene — scene templates: player / enemy / level / menu / HUD / inventory / dialogue
• create-component — HealthComponent, Hurtbox, Hitbox, MoveComponent, Inventory, Interactable
• create-state-machine — node-based FSM
• create-resource — custom Resource classes (Item, Ability, EnemyStats, DialogueLine, ...)
• create-autoload — single autoload + project.godot registration

Quality:

• gut-test-writer — GUT tests with proper setup/teardown
• performance-audit — static scan for perf antipatterns
• update-docs — sync README / GDD / PROGRESS / CLAUDE

Content:

• shader-writer — 2D + 3D shader recipes
• sfx-generator — audio + Godot bus layout + AudioManager pattern
• gdd-writer — generic Game Design Document maintainer

Build:

• export-config — export presets, signing, CI builds for Win/Mac/Linux/Web/Android/iOS

Genre packs (opt-in, genre-specific):

• genre-pack-platformer — coyote time, jump buffer, variable jump, wall jump, dash
• genre-pack-topdown — 8-dir movement, A* pathfinding, twin-stick aim
• genre-pack-3d-action — SpringArm camera, lock-on, dodge roll, animation tree
• genre-pack-turnbased — TurnManager, Action queue, deterministic RNG

Agent catalog (15)

Agent picker (situation → call)

Always invoke via Agent tool with subagent_type: "<name>". Full table also in using-godot-superpowers skill (auto-loaded on .gd/.tscn).

Priority: (1) verifier when batch ≥3 files or single risky file (skip trivial edits); (2) orchestrator on multi-file milestone; (3) read-only → analyst agent; (4) genre-pack → skill directly. Otherwise main context.

Project-side rules these skills/agents enforce

When operating in a downstream Godot project, the skills and agents enforce:

• Composition > inheritance — components as child nodes, not deep extends chains
• Type hints everywhere — var x: int, func f(a: int) -> void
• Signals connected in code in _ready(), never in editor
• @onready for repeated lookups — never $Path in _process / _physics_process
• Custom Resources for game data — never Dictionary literals
• Unique scene names (%) instead of long $Path/To/Node
• change_scene_to_packed() with preloaded PackedScene
• TileMapLayer (4.3+) over deprecated TileMap
• Parallax2D (4.3+) over deprecated ParallaxBackground / ParallaxLayer
• Hurtbox/Hitbox on separate collision layers per setup-collision-layers
• Resource save for game state (not JSON; JSON loses Vector2/Color/typed objects)
• _unhandled_input for action triggers, not _input (UI takes precedence)

Distribution

This plugin can be:

1. Installed via Claude Code marketplace (once published) — namespaced as /godot-superpowers:<skill>
2. Loaded locally — claude --plugin-dir /path/to/godot-superpowers
3. Copied as .claude/ — drop agents/, skills/, hooks/, scripts/, settings.json, .mcp.json into a project's .claude/ directory, plus settings.local.json.example copied as .claude/settings.local.json (the source file is gitignored here, so the tracked .example is the install template). Hooks resolve their helper scripts via ${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/scripts/hooks/<name>.sh, which works in both plugin mode and drop-in mode — but the scripts/ directory MUST be copied alongside the others. The template uses an explicit enabledMcpjsonServers whitelist (tier 1 only by default); tier 2 server git is opt-in. Without settings.local.json, .mcp.json is declarative-only and no server starts. Keep settings.local.json gitignored on real projects (per-user state).

When copied as .claude/ (option 3), skills are NOT namespaced — invoked as /<skill> directly.

When the user asks to add a new skill or agent

1. Check if existing one covers it. Many requests overlap with existing skills (especially godot-patterns, create-component, genre packs).
2. Decide skill vs agent: skills load inline knowledge; agents run as side tasks with isolated context.
3. Write to the conventions above — frontmatter, language, citations.
4. Keep skills genre-agnostic. Genre-specific content goes in genre-pack-* skills, never in foundational ones.

Requirements (for downstream projects)

• Godot 4.3+
• gdtoolkit 4.x (pipx install gdtoolkit==4.*)
• Optionally GUT or GdUnit4 (per addon-curator recommendation)