# match-builder — a Claude Code skill for composing USPSA matches

This is the **public mirror** of the [match-builder](https://itsmatchday.app/skills/match-builder/) skill — an end-to-end Claude Code skill that interviews a match director, picks a balanced selection of stages from the bundled Match Day classifier set (plus any custom stages the MD names), drives the [Stage Setter editor](https://itsmatchday.app/build/)'s Match Builder dialog, and produces a `.usmatch` file ready to share with the club.

> **Looking for stage authoring, not match assembly?** See the [stage-builder skill](https://itsmatchday.app/skills/stage-builder/). For just the Match Day JSON formats, see [AGENTS.md](https://itsmatchday.app/AGENTS.md).

---

## Install (Claude Code)

```bash
curl -sSL https://itsmatchday.app/skills/match-builder.zip -o /tmp/match-builder.zip \
  && unzip -o /tmp/match-builder.zip -d ~/.claude/skills/ \
  && rm /tmp/match-builder.zip
```

Restart Claude Code (or start a new session) and trigger the skill by saying *"build me a match"*, *"plan a match"*, *"let's plan Saturday's match"*, or similar.

---

## Use

The skill walks you through composing a complete USPSA match in two short batches of multiple-choice questions:

**Batch 1 — match shape (4 q):** stage count, classifier inclusion, round-count target, stage character (speed / balanced / accuracy / standards).

**Batch 2 — venue + MD (2 q):** which saved venue + MD profile to use, or fill new ones. If you've never used the skill before, it'll ask for the details once and offer to save them.

After the interview the skill:
1. Picks a balanced selection from the bundled classifier set based on your prefs
2. Adds any custom stages you name (resolves them by name from `~/Desktop/new stage designs/` or wherever you've saved them)
3. Composes the match JSON, validates it, and drives the Match Builder dialog to show you the result
4. Writes the final `.usmatch` to wherever you want
5. Offers to save the venue + MD as profiles for next time

---

## Setting up the editor preview

The skill drives the hosted Stage Setter editor 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.)

If you just want the `.usmatch` file without a visual review, tell the skill *"just give me the file"* and it'll skip the editor entirely.

---

## Venue + MD profiles

The skill persists venue and director details to `~/Documents/Match Day/profiles/{venues,directors}/` as plain JSON files. Edit them by hand, back them up, copy them between machines — they're not in a proprietary format.

Profiles eliminate re-typing the same club info every month. After your first match, the next session will offer your saved venue + director as named options instead of asking for the details again.

---

## What's in the box

| File | Purpose |
|---|---|
| `SKILL.md` | Main skill spec — pipeline, interview, validation rules |
| `references/classifier_index.md` | Catalog of the bundled USPSA classifiers with character tags. The skill uses this to pick a balanced selection. |
| `references/match_pipeline.md` | Stage-picking algorithm + ordering heuristics |
| `references/match_builder_api.md` | Recipes for driving the web Match Builder via `preview_eval` |
| `references/stage_resolution.md` | How the skill resolves a stage name to a bundled classifier or saved custom stage |
| `references/profile_storage.md` | Venue + MD profile JSON shape + read/write conventions |
| `references/usmatch_format.md` | Match JSON v1 schema reference |

---

## Attribution & trademarks

This skill references **Claude Code** (a product of Anthropic, PBC) and the USPSA rule set. 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 information.

## License & feedback

Use, fork, modify freely. Found a bug or want a new feature in the skill? Drop a note at `hey@itsmatchday.app`.