# stage-builder — a Claude Code skill for designing USPSA stages

This is the **public mirror** of the [stage-builder](https://itsmatchday.app/skills/stage-builder/) skill — an end-to-end Claude Code skill that interviews you, plans a stage against master-shooter design principles, builds it incrementally in the [Stage Setter editor](https://itsmatchday.app/build/), and saves valid Match Day JSON.

> **Looking for the schema, not the skill?** See [`itsmatchday.app/AGENTS.md`](https://itsmatchday.app/AGENTS.md) for the raw JSON format and editor deep-link options.

---

## Install (Claude Code)

Download the folder and drop it into your user-skills directory:

```bash
# One-liner: download the zip and unpack to ~/.claude/skills/
curl -sSL https://itsmatchday.app/skills/stage-builder.zip -o /tmp/stage-builder.zip \
  && unzip -o /tmp/stage-builder.zip -d ~/.claude/skills/ \
  && rm /tmp/stage-builder.zip
```

Or manually: grab the [zip](https://itsmatchday.app/skills/stage-builder.zip), unzip it, and put the resulting `stage-builder/` folder inside `~/.claude/skills/`.

Restart Claude Code (or start a new session) and the skill will be available.

---

## Use

Say anything like:

- "Build me a stage"
- "Design a field course"
- "Let's design a stage" / "stage builder"

Claude will interview you (5 questions across two batches: difficulty, round count, movement style, symmetry, and design philosophy), plan against USPSA safety rules + master-shooter principles, then build the stage in the editor with screenshots between chunks. You critique, it iterates.

The final stage saves to a JSON file you can open in [Stage Setter](https://itsmatchday.app/build/) for review or send to your phone via the Match Day iOS app.

---

## What's in the box

| File | Purpose |
|---|---|
| `SKILL.md` | The main skill spec — pipeline overview, interview questions, safety rules. |
| `references/master_principles.md` | The 5 master-shooter design philosophies (Grauffel, Leatham, Michel, Stoeger, Miculek) + the builder's rulebook. Loaded on demand. |
| `references/safety_rules.md` | USPSA shooting-area, fault-line, and bullet-path rules. |
| `references/editor_api.md` | Concrete recipes for driving the Stage Setter editor from a coding agent. |
| `references/geometry_rules.md` | v2 coordinate system, target facing math, stand-endpoint formulas. |
| `references/session_gotchas.md` | Specific bugs and design failures from the session that produced this skill — the "don't repeat these mistakes" file. |

---

## Setting up the editor preview

The skill drives the [hosted Stage Setter editor](https://itsmatchday.app/build/) via Claude Code's preview MCP. It expects a preview-server entry named **`match-day-editor`** pointing at the hosted URL. Add this to `.claude/launch.json` in whichever directory you'll be working from:

```json
{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "match-day-editor",
      "url": "https://itsmatchday.app/build/"
    }
  ]
}
```

(If your version of the Claude Code preview tool requires a local server, swap the `url` line for `"runtimeExecutable": "python3", "runtimeArgs": ["-m", "http.server", "8765"], "port": 8765` and run it from a directory that contains a downloaded copy of the editor. Most users won't need this — the hosted editor works fine.)

That's it. The skill handles save-folder discovery (it'll ask where you want stages saved if you have no preference) and works with the hosted editor out of the box.

---

## Attribution & trademarks

This skill references **Claude Code** (a product of Anthropic, PBC) and characterizes the competitive design styles of well-known USPSA shooters (including Eric Grauffel, Rob Leatham, Max Michel, Ben Stoeger, and Jerry Miculek) for educational purposes. None of these parties are affiliated with or have endorsed Match Day or this skill. See [Match Day's legal page](https://itsmatchday.app/legal.html) for full trademark and attribution information.

## License & feedback

Use, fork, modify freely. If the skill produces a stage that fails real-world safety review, or you have a master-shooter principle worth adding — drop a note at `hey@itsmatchday.app`.