# Install "Godot, One Mechanic at a Time (reference folder, grey box, tested mechanics)"

A GameSkill original for building a Godot 4 game with an agent in an order that holds up: a reference folder with a style-prompt JSON, a grey box, then one mechanic per prompt in its own script with its own headless playtest, re-running every earlier playtest before the next. Ships templates, checkers for the reference folder and project layout, and a tested 2D example (run and jump, then glide across a gap) whose playtests catch a broken mechanic.

- Source: GameSkill original, hosted only on https://gameskill.dev/skills/godot-one-mechanic
- Based on (ideas only, code is ours): Reference folder to world, and one mechanic per prompt (posts, ideas only) https://x.com/sorenxet by @sorenxet (no licence, idea only, no code or text used)
- License: MIT
- By: GameSkill
- Works with: Claude Code, Codex, Cursor, OpenCode
- Engines: Godot

## Prerequisites

- Godot 4.2+ (tested on 4.7.2); playtests run headless
- Python 3 standard library for check_refs.py and check_project.py

## Install GameSkill's tested copy (recommended)

GameSkill wrote this skill for gameskill.dev and hosts it here (MIT). The ZIP holds SKILL.md, SKILL.zh.md, scripts, a runnable example, tests, CHECKLIST.md, LICENSE, CREDITS.md, ATTRIBUTION.md and a `gameskill/` folder (test report, self-check list, Chinese guide).

- ZIP: https://gameskill.dev/dl/skills/godot-one-mechanic.zip (31 KB, sha256 616d1ac180f49da9cb008b34af77053fc3fb685315bd074feeb58e76d1b3e139)
- Version: 1.0.0 (2026-11-03). Latest version and changes: https://gameskill.dev/skills/godot-one-mechanic/version.json
- Tested by GameSkill on Godot 4.7.2 (2D physics, headless playtests) + Python 3 standard library, 2026-11-03: 35/35 checks passed. Report: https://gameskill.dev/dl/skills/godot-one-mechanic/test-report.json

The ZIP holds one folder, `godot-one-mechanic/`, with SKILL.md directly inside it.

Pick the block for the agent you are and run it from the root of the user’s project, then restart the agent.

### Claude Code (`.claude/skills/godot-one-mechanic/`)

```bash
mkdir -p .claude/skills
curl -fsSL https://gameskill.dev/dl/skills/godot-one-mechanic.zip -o /tmp/gameskill-godot-one-mechanic.zip
unzip -oq /tmp/gameskill-godot-one-mechanic.zip -d .claude/skills
rm /tmp/gameskill-godot-one-mechanic.zip
```

### Codex, Gemini CLI, OpenCode (`.agents/skills/godot-one-mechanic/`)

```bash
mkdir -p .agents/skills
curl -fsSL https://gameskill.dev/dl/skills/godot-one-mechanic.zip -o /tmp/gameskill-godot-one-mechanic.zip
unzip -oq /tmp/gameskill-godot-one-mechanic.zip -d .agents/skills
rm /tmp/gameskill-godot-one-mechanic.zip
```

### Cursor (`.cursor/skills/godot-one-mechanic/`)

```bash
mkdir -p .cursor/skills
curl -fsSL https://gameskill.dev/dl/skills/godot-one-mechanic.zip -o /tmp/gameskill-godot-one-mechanic.zip
unzip -oq /tmp/gameskill-godot-one-mechanic.zip -d .cursor/skills
rm /tmp/gameskill-godot-one-mechanic.zip
```

### GitHub Copilot (`.github/skills/godot-one-mechanic/`)

```bash
mkdir -p .github/skills
curl -fsSL https://gameskill.dev/dl/skills/godot-one-mechanic.zip -o /tmp/gameskill-godot-one-mechanic.zip
unzip -oq /tmp/gameskill-godot-one-mechanic.zip -d .github/skills
rm /tmp/gameskill-godot-one-mechanic.zip
```

### Windsurf (`.windsurf/skills/godot-one-mechanic/`)

```bash
mkdir -p .windsurf/skills
curl -fsSL https://gameskill.dev/dl/skills/godot-one-mechanic.zip -o /tmp/gameskill-godot-one-mechanic.zip
unzip -oq /tmp/gameskill-godot-one-mechanic.zip -d .windsurf/skills
rm /tmp/gameskill-godot-one-mechanic.zip
```

### Self-check after using the skill

- 先写 refs/style.json，每张图写取什么、不取什么 / Write refs/style.json first; every image says what to take and ignore
- 先灰盒，尺寸写成常量 / Grey box first, sizes as constants
- 一个提示只加一个机制，一个机制一个脚本 / One mechanic per prompt, one script per mechanic
- 每个机制的测试同时说明它做什么、为什么需要它 / Each playtest shows what the mechanic does and why it is needed
- 打开新机制后重跑之前所有测试组 / Re-run every earlier playtest group with the new mechanic on
- 机制稳定之前不上美术 / No art until the mechanics hold

## Verify

- `godot-one-mechanic/SKILL.md` exists in the skills folder above.
- Try a request like: "Start my Godot platformer the one-mechanic way: write refs/style.json from my reference images, make a grey box, then add mechanic 1 (run and jump) with its playtests."
- Tell the user what you installed and where.

## Attribution

"Godot, One Mechanic at a Time (reference folder, grey box, tested mechanics)" is a GameSkill original (https://gameskill.dev/skills/godot-one-mechanic), licensed under MIT. CREDITS.md in the ZIP lists the workflow inspiration, test assets and third-party libraries; keep LICENSE and CREDITS.md with any copy.