# Mtg Edh Primer

> Generate a comprehensive, publish-ready **primer** for an existing 100-card Magic: The Gathering Commander (EDH) deck — a deep "how this deck works and how to pilot it" guide, plus a role-tagged Moxfield import. Use this skill whenever the user wants to explain, document, or write up a Commander deck rather than build, upgrade, or merely rate one: "generate a primer", "write a primer for my deck", "create a deck guide", "explain how my deck works / how do I win with it", "how do I pilot this", "tag my deck by role", "make a Moxfield primer", or "document my <commander> deck". The user gives a deck either by **slug** (a deck already in the workspace, `.mtg/decks/edh/<slug>/import.txt`) or by **pasting a list inline**. The skill reads every card's Oracle text from the local Scryfall database, infers the deck's win conditions and theme, classifies every card into role + theme tags (mana dork, sac outlet, fatty, draw, drain, recursion, removal, finisher, land, …), explains each card in one tight line in the conte

- Skill: `guuse/mtg-edh-primer` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add guuse/mtg-edh-primer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/guuse/mtg-edh-primer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: guuse (https://skillmd.com/u/guuse)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/guuse/mtg-edh-primer

---


# MTG Commander Deck Primer Generator

This skill turns an existing Commander deck into a **primer**: the document you'd publish so anyone — or
future-you — can understand *how the deck wins* and *how to pilot it*, card by card. It is the **explain/teach**
counterpart to the suite: it doesn't build (`mtg-edh-build`), swap cards (`mtg-edh-upgrade`), or just score
(`mtg-edh-analyze`) — it **reads the deck and explains it**, then hands the score back via the same rating
rubric.

Two principles keep it honest:

1. **Read the cards, don't guess from names.** Win conditions, a card's real job, and the theme all live in the
   **Oracle text** — which `scripts/analyze_deck.py` pulls from the local Scryfall database. The wincon read and
   the per-card lines must reflect actual text, not vibes.
2. **Every card earns its place on the page.** The primer's value is that it explains *each* card *in the
   context of this deck* — one tight, purposeful line — and groups them by the job they do.

## Start here: get the deck

The user gives the deck one of two ways:

- **By slug** — a deck already in the workspace. Read `.mtg/decks/edh/<slug>/import.txt`. (Run
  `python "${CLAUDE_SKILL_DIR}/scripts/scryfall_search.py" --paths` to resolve the `decks/` location; honours
  `$MTG_HOME`.) This is the common path and means the primer lands in the right folder automatically.
- **Pasted inline** — a Moxfield/Archidekt export or a `1 Card Name` list. Write it to a temp file (e.g.
  `.mtg/decks/edh/<slug>/import.txt` if you're creating the folder, or any temp path).
- **By link** — a Moxfield/Archidekt URL: run `scripts/import_deck.py <url>` to pull the list via the site
  JSON API (it falls back to asking for a paste if the deck is private/unreachable; never invents a list),
  then write its output to a temp file as above.

Identify the **commander** (a Commander-section/`*CMDR*` card, or ask) and confirm the **target bracket (1–5)**
the deck is meant for — if unsure, rate at the bracket the deck looks like, and say so. If the list isn't ~100
cards or the commander is ambiguous, say what you found and confirm before writing.

## The `.mtg` workspace, the database, and syncing

Same backbone as the other deck skills:

- **Workspace** resolves via `$MTG_HOME` → nearest `.mtg/` → `./.mtg/`. `scripts/scryfall_search.py --paths`
  prints the resolved `decks/`/`database/` paths as JSON and creates nothing. Decks live under
  `.mtg/decks/edh/<slug>/`.
- **Database**: the scripts read the local Scryfall SQLite DB (`.mtg/database/cards.sqlite`), **built
  automatically on first use** by the shared library (the **mtg-db** skill). If it reports the data is **stale
  (>30 days)**, tell the user prices/sets may have moved and offer to refresh.
- **Syncing** (if the workspace is a synced git repo): invoke **mtg-sync** to **pull** before reading and to
  **push** after writing the primer (`--push -m "primer: <commander>"`). Best-effort — if it reports
  `skipped`/`FAILED`, note it in one line and continue; the files are saved locally.

## Run the analysis

Run the bundled analyzer to get the objective data the primer is built from:

```
python "${CLAUDE_SKILL_DIR}/scripts/analyze_deck.py" <import.txt> --commander "<name>" --json
```

It returns, per card: **Oracle text**, type line, mana value, EUR price, EDHREC rank — plus deck aggregates:
card/land count, **mana curve**, average MV, **EDHREC-rank staple signal**, **Game Changer count**,
**off-color-identity** cards, total price, and any cards not found. You do the reading and judging on top.

## Build the primer (the method)

### Step 1 — Infer the win conditions and theme
Read the commander + every card's Oracle text and match the deck to one or more patterns in
`references/win-patterns.md` (use `references/synergy.md`'s read→extract→intersect method). Name the
**1–4 real, repeatable** win conditions, each with its **key enabling cards**, the primary plan vs backups, and
any **two-card combo** (matters for bracket). Note the deck's speed (from curve + ramp) — it sets the play
guide's turn bands.

### Step 2 — Tag every card (one or more tags, ordered tiers)
Using `references/tags.md`, tag each non-commander card with **every category it genuinely belongs to** — a
card that does several jobs gets several tags (e.g. an evasive creature that's also a draw engine *and*
removal). Build tags in **two ordered tiers**: a **numbered engine** (`1) … 2) … 3) …`) naming *how this deck
wins* in execution order, in the **flavour of the deck** (tasteful, never cringe — `3) Ninjutsu - Targets`,
not `3) Sneaky Backstab Bois`), and the **lettered support pillars** (`A) Mana Advantage`, `B) Card Advantage`,
`C) Interaction`, `D) Resilience`, `E) Lands`) for the universal jobs, lands last. The prefixes force
Moxfield's Group-by-Tag view to render in deliberate order. **Never tag the commander** — Moxfield labels it in
its own zone, so the commander line gets no tag.

### Step 3 — Write the per-card lines
**One tight line per card, in the context of *this* deck** — its job here, not its generic Oracle text. Give
**marquee/engine cards 2–3 lines**. Every nonland card and every nonbasic/utility land gets a line; **collapse
basic lands to one summary line** (`6 Forest · 6 Swamp — fixing`), never one line per basic. In the prose,
group each card under its **most-defining** category (prefer the engine tier when a card spans both tiers).

**Card names are Moxfield card links, never code blocks.** Every time a card is named *anywhere* in
`primer.md` — per-card lines, "How it wins", the play guide, the rating's cheapest-fixes note, weaknesses,
everywhere — wrap the exact card name in double square brackets: `[[Sheoldred, Whispering One]]`, **not**
`` `Sheoldred, Whispering One` `` and not bare text. Moxfield renders `[[Name]]` as a hover-preview link to the
card image; backticks render as dead monospace and waste the feature. The text inside the brackets must be the
real card name including punctuation (matching is case-insensitive); keep any annotation outside the brackets —
`[[Guardian Project]] (€2)`. Reserve backticks for things that are **not** card names: mana costs (`{2}{U}{B}`),
the basic-land summary line, and literal file/code snippets.

### Step 4 — Write the play guide
- **Mulligan / opening hand** — what to keep, what to ship.
- **Early / Mid / Late** — three phases with **deck-tuned turn bands** (default ≈T1–4 / T4–8 / T8+; shift them
  for a fast or slow deck). Each phase covers: *what to prioritise · your lines & options · what to watch out
  for · counterplay vs other players* (multiplayer politics, board wipes, archenemy heat).
- **Common misplays** — a short callout of the traps specific to piloting this deck.

### Step 5 — Rate it (★ scorecard at the top of the primer)
**Every primer includes a rating — there are no exceptions.** Score the deck against its **target bracket**
with the five-dimension rubric in `references/rating.md` (structure & consistency, synergy density, staples &
card quality, win conditions, bracket calibration) — do **not** restate the rubric here, follow it — using the
`analyze_deck.py` numbers + `references/brackets.md`. This is the same rubric the **mtg-edh-analyze** skill
uses; the primer reports a **compact summary** of it, not a full analysis.

Render the result as a **Rating block placed right after the header**, in three parts:

1. A **one-line headline**, e.g. `Rating: ★★★★☆ (4/5) — strong Bracket 3` (use half-stars; state the deck's
   *actual* bracket if it differs from the target).
2. A **compact per-dimension scorecard table** — the five dimensions, each with its stars **and the numbers
   behind the score** (e.g. `Structure ★★★★ — 37 lands, 11 ramp, 13 draw, 9 removal + 3 wipes`). One row each;
   keep it tight.
3. **One line** naming the **biggest gaps + their cheapest fixes** (e.g. "Thin draw (9, want 12+) and only one
   wipe — cheapest fixes: Guardian Project (€2), Blasphemous Act (€1).").

Always pair the stars with the bracket and state this rule plainly beside them:

> **★ ≠ bracket.** The stars rate how good the deck is *within its bracket*; the bracket is its absolute power
> tier. A **2★ Bracket 4** deck is more powerful than a **5★ Bracket 2** deck.

If the deck is mis-bracketed (e.g. Game Changers above its bracket's cap, or an early infinite combo), say so
and report the bracket it actually sits at. Keep the whole block short — it's the primer's summary scorecard,
not the full report `mtg-edh-analyze` would write.

## The deliverables

Write `primer.md` and a role-tagged `import.txt` into `.mtg/decks/edh/<slug>/`. **Leave `deck.md` untouched**
(that's build/upgrade's *private* status notes). You **do** (re)write `import.txt` — appending each
non-commander card's role tags — but keep every card's name (and `(SET) collector#` printing, if present)
byte-for-byte identical; only add the trailing ` #…` tags. (There is no separate `moxfield-import.txt` — the
tagged `import.txt` is both the importable list and the Moxfield tag source.)

> **Budget variants:** if the deck is one of several **budget variants** of the same deck (a labelled ladder —
> see `mtg-edh-build`'s "Budget variants" section), each variant is its **own self-contained subfolder**
> `<slug>/<label>/` (label = the variant's € budget, or `base`). Write this variant's `primer.md` and
> `import.txt` **into that variant's subfolder** (plain names, not suffixed), cross-link the sibling variants
> from the primer, and leave that variant's own `deck.md` untouched. Update the identity folder's `README.md`
> ladder index if the variant set changed. Never invent variants the user didn't ask for.

1. **`primer.md`** — the publish-ready primer, in this order:
   - **Header:** deck name + commander; the **`Rating: ★★★★☆ (4/5) — strong Bracket 3`** headline + the
     ★≠bracket note; colors; total value.
   - **Rating** *(right after the header — Step 5)* — the compact per-dimension scorecard table (each dimension's
     stars + the numbers behind it) and the one-line biggest-gaps + cheapest-fixes note. Short; it's the
     summary, not a full analysis.
   - **TL;DR** — 2–3 sentences: archetype, how it plays, how it wins.
   - **How it wins** — the named win conditions (Step 1).
   - **Card roles & tags** — a one-line legend naming the deck's **numbered engine tiers** and the lettered
     support pillars, then cards grouped by their most-defining tag with one-line explanations (Step 3). The
     **same tags (one or more per card)** are in `import.txt`, grouped by tier so the deck reads in
     deliberate order.
   - **Play guide** — mulligan, early/mid/late, common misplays (Step 4).
   - **Strengths & weaknesses** — and how to play around the weaknesses.
   It's plain Markdown that pastes straight into Moxfield's Notes/Primer tab. **Every card name is a
   `[[Card Name]]` link** (Step 3), so the published primer shows a hover preview of each card.
2. **`import.txt` (role-tagged)** — the 100-card list where each non-commander card carries **one or more**
   deck-defining tags (see `references/tags.md`): a **numbered engine** (`1) … 2) …`, deck-flavoured, in
   execution order) plus the **lettered support pillars** (`A) … E) Lands`), each tag written `#…` (no
   quoting — Moxfield ends a tag at the next `#`) and ordered by tier on the line. Append the tags to the deck's
   existing card lines so each line — name **and** its exact
   `(SET) collector#` printing (if present) — stays byte-for-byte identical (only the trailing `#…` tags are added).
   **The commander comes first and carries no tag** (Moxfield labels it in its own zone), then a blank line,
   then the 99.

Do **not** add a Moxfield how-to / "Using these files in Moxfield" usage box to `primer.md` — the primer is
just the deck guide (rating, win conditions, card roles, play guide). Skip import/Bulk-Edit/command-zone
instructions entirely.

**Never put repo/upgrade context in `primer.md`.** The primer is the **public, publish-ready deck guide** —
how the deck works and how to pilot it. Anything about the *building/upgrading process* or the *workspace* must
**never** appear in it and belongs **only in the private `deck.md`**: swap/cut reasoning ("replaced X with Y
because…"), upgrade history or diffs vs a previous list, budget math and price tracking, buylists, target-vs-actual
bracket working notes, TODOs, sync/commit/version metadata, file paths, slugs, and any other build-time
bookkeeping. If the source material (a pasted deck, a `deck.md`, an upgrade summary) contains such notes, **leave
them out of the primer** — the reader gets the finished deck explained, not the story of how it was assembled.

Use the file-presentation tool to share both once written.

## Quality bar

- **Grounded:** every win condition and per-card line reflects the actual Oracle text (from `analyze_deck.py`),
  not the card name.
- **Hover-linked cards:** every card name in `primer.md` is wrapped as a `[[Card Name]]` Moxfield link (never a
  backtick code block), so each renders as a hover-preview card; backticks are reserved for mana costs, the
  basic-land summary, and literal snippets.
- **Complete & tagged:** every nonland card + notable land has a line; basics are summarised; **every
  non-commander card in `import.txt` carries one or more fitting tags (numbered engine + lettered
  pillars, written `#…` unquoted), the commander line carries none**, and each line (name + `(SET) collector#`
  printing) matches `import.txt` exactly (it still sums to 100).
- **No Moxfield how-to box:** `primer.md` contains no "Using these files in Moxfield" / import / Bulk-Edit /
  command-zone usage instructions — it's the deck guide only.
- **No repo/upgrade context:** `primer.md` contains no build/upgrade process notes — no swap/cut reasoning,
  upgrade history or diffs, budget math, price tracking, buylists, sync/commit/version metadata, file paths, or
  slugs. All of that lives **only** in the private `deck.md`; the primer explains the finished deck, not how it
  was assembled.
- **Honest rating:** the primer opens with the rating — a one-line headline, the compact per-dimension
  scorecard with the numbers behind each score, and the biggest-gaps + cheapest-fixes line — scored against the
  rubric at the stated bracket, with the ★≠bracket rule shown and mis-bracketing called out.
- **Scoped:** `deck.md` (private notes) is untouched; the skill writes `primer.md` and the role-tagged
  `import.txt` (tags appended to the existing card lines, card list unchanged).