Analyze and optimize 60-card constructed MTG decks with sideboards for Standard, Alchemy, Historic, Pioneer, Timeless, Modern, Legacy, and Vintage.
Analyze and optimize existing 60-card constructed decks with sideboards for competitive MTG formats. Covers mainboard card evaluation, mana base tuning, sideboard planning against the metagame, and budget-aware upgrade paths.
Never assume what a card does. Always look up oracle text via scryfall-lookup before evaluating a card. Training data may be outdated, cards get errata, and memory conflates similar effects.
Create these top-level todos at session start. Mark in_progress immediately when starting a step, completed immediately when finishing. Never batch updates.
Step 6 expansion: When starting Step 6, expand into sub-todos:
Step 7 expansion: When starting Step 7, expand into sub-todos:
uv sync --directory <skill-install-dir>
download-bulk --output-dir <skill-install-dir>
Subsequent runs skip if .venv exists and bulk data is fresh (24h).
Use the Write tool for any JSON file containing card names. Apostrophes in names break shell quoting. Write tool permissions are cacheable; python3 -c "..." re-prompts every time.
Reuse these stable paths within a session: /tmp/cuts.json, /tmp/adds.json, /tmp/sideboard-cuts.json, /tmp/sideboard-adds.json.
Critical: Files at /tmp/ persist across sessions. Always Read a scratch file before the first Write in a new session.
Alchemy uses digitally rebalanced card versions prefixed with A- (e.g., A-Teferi, Time Raveler). These have different oracle text from their paper counterparts. When tuning Alchemy decks, search for both "<Card Name>" and "A-<Card Name>" via scryfall-lookup to verify which version is legal and what its current oracle text says. The rebalanced version is the one that matters for Alchemy gameplay.
The AskUserQuestion tool supports at most 4 options. If you have more than 4 choices (common in Step 9 close calls), either present the most relevant 4 (mention others exist) or present the information as text and ask a follow-up question.
uv rebases the working directory to the skill install.<working-dir>/.cache, not the skill install directory.scryfall-lookup --batch. The cache is SHA-keyed; old caches go stale silently.The rarity field in hydrated card data is the Scryfall default printing's rarity, which drifts from Arena's actual wildcard cost. Always use price-check --format <fmt> --bulk-data <path> for Arena wildcard budgeting.
| Task | Tool |
|---|---|
| Find format-legal cards by oracle text, type, CMC | card-search --format <fmt> |
| Look up a specific card's oracle text | scryfall-lookup "<Card Name>" |
| View card table (mainboard) | card-summary <hydrated.json> [--nonlands-only] [--lands-only] [--type <T>] |
| View card table (sideboard) | card-summary <hydrated.json> --deck <deck.json> --sideboard |
| Find combos in the deck | combo-search <deck.json> |
| Find combos by card or outcome | combo-discover --card "<Name>" --format <fmt> |
| Check deck legality | legality-audit <deck.json> <hydrated.json> |
| Check mana base health | mana-audit <deck.json> <hydrated.json> |
| Compare mana before/after | mana-audit <old.json> <old-hyd.json> --compare <new.json> <new-hyd.json> |
| Price check (paper) | price-check <deck.json> --bulk-data <path> |
| Price check (Arena wildcards) | price-check <deck.json> --format <fmt> --bulk-data <path> |
| Apply mainboard + sideboard changes | build-deck <deck.json> <hyd.json> --cuts <c.json> --adds <a.json> --sideboard-cuts <sc.json> --sideboard-adds <sa.json> |
| Compare deck versions | deck-diff <old.json> <new.json> <old-hyd.json> <new-hyd.json> |
| Export for import | export-deck <deck.json> |
| Research metagame/strategy | WebSearch + WebFetch (or web-fetch script) |
parse-deck <path> --format <format> --output <working-dir>/deck.json
sideboard field (separate from cards)parse-deck: 60 cards, 15 sideboard -> /path/to/deck.jsonIf the user has an Arena collection:
mark-owned <deck.json> <collection.csv> --bulk-data <path> to populate owned_cardsmtga-import only for extracting wildcard counts, not collection datascryfall-lookup --batch <deck.json> --bulk-data <path> --cache-dir <working-dir>/.cache
Returns an envelope with cache_path, card_count, missing, digest. The cache file contains all mainboard + sideboard cards hydrated with oracle text, legalities, prices, etc.
Do NOT Read the cache file directly — it's large and floods context. Use card-summary or scryfall-lookup "<Name>" for targeted reads.
Run in this order (cheapest-to-fail first):
legality-audit <deck.json> <hydrated.json>
Checks: format legality, copy limits (4-of + Vintage restricted), sideboard size, deck minimum. Must PASS before continuing. If FAIL, surface violations and ask user how to fix.
deck-stats <deck.json> <hydrated.json>
Review: total cards, land count, creature count, ramp count, avg CMC, curve distribution, sideboard total. Note any obvious red flags.
card-summary <hydrated.json> --nonlands-only
card-summary <hydrated.json> --lands-only
card-summary <hydrated.json> --deck <deck.json> --sideboard
Scan mainboard and sideboard oracle text. Flag cards with alternative costs (suspend, foretell, etc.) for adjusted CMC evaluation.
mana-audit <deck.json> <hydrated.json>
Uses the constructed land formula. Notes land count status (PASS/WARN/FAIL) and color balance.
Check the sideboard for a Companion card (card-summary <hydrated.json> --deck <deck.json> --sideboard and look for the Companion keyword). If one exists, note its deck-building restriction — all proposed changes must continue to meet it.
If no Companion exists, check whether the deck naturally meets one's restriction. Companions are powerful enough that a deck accidentally qualifying for one (e.g., a low-curve aggro deck meeting Lurrus's "no permanents with mana value > 2") should actively consider adding it. Use card-search --format <fmt> --oracle "Companion" --type "Creature" to find candidates, then check restrictions against the current deck. If one fits, suggest it in Step 8 as an addition (it takes 1 sideboard slot).
Ask one at a time via AskUserQuestion:
Confirm carry-forward context: format, platform, Bo1/Bo3, budget (total/spent/remaining), experience level, archetype, Companion (if any), max swaps. Don't re-ask questions already answered.
For Arena, use compact notation: NM/NR/NU/NC (e.g., 2M/4R/8U/12C = 2 mythic, 4 rare, 8 uncommon, 12 common wildcards).
If the user ran mtga-import, check for wildcards.json in the working directory before asking about budget.
"<format> metagame 2026" or "<format> tier list""<deck archetype> <format> sideboard guide" and "<deck archetype> <format> matchup guide"combo-search <deck.json>
Surface existing combos and near-misses. Note which near-misses could be completed with 1-card additions.
Supplement with WebSearch: combo-search uses Commander Spellbook, which is crowdsourced primarily by Commander players. Combos that are powerful in 1v1 60-card formats but weak in multiplayer Commander may be underrepresented or missing. Search for "<archetype> combo <format>" and "<key card> combo <format>" to catch format-specific interactions the API might miss.
Present your understanding of the deck's:
Ask the user to validate or correct. This alignment prevents wasted analysis on swaps that fight the deck's identity.
mana-audit for quantitative checkUnlike commander (which anchors on the commander), constructed decks must have a consistent game plan visible across the 60 cards.
Step 1 — Identify the build-around cards. Every competitive deck has 1-3 cards that define its archetype (e.g., Monastery Swiftspear for burn, Arclight Phoenix for Izzet Phoenix, Amulet of Vigor for Amulet Titan). These are the constructed equivalent of the commander — the cards the deck is built to maximize.
Step 2 — Evaluate every other card against the build-around. For each non-land card, it should do at least one of:
Cards that don't clearly fit one of these roles are candidates for cuts.
Step 3 — Check for orphaned "Plan B" cards. A common deck-building mistake is including 2-3 cards from a secondary strategy the deck doesn't have the infrastructure to support (e.g., a single planeswalker in an aggro deck with no way to protect it, or a graveyard payoff in a deck with no self-mill).
Step 4 — Scan oracle text systematically. Use card-summary <hydrated.json> --nonlands-only and look for oracle text that doesn't mention the deck's key mechanics. Cards whose text has no mechanical relationship to the build-around are red flags.
Step 5 — Verify structural consistency:
For each proposed cut, evaluate:
Be careful with cuts. Re-read oracle text of both the card and its synergy partners. Articulate the specific underperformance.
Source candidates from:
card-search --format <fmt> for format-legal optionsFor each proposed addition:
Evaluate the current sideboard against the metagame:
Draft sideboard changes alongside mainboard changes.
After drafting all changes (mainboard + sideboard):
mana-audit --compare to verify color balance maintainedprice-check on proposed additionsBefore the self-grill, verify mechanically:
Price check on additions:
price-check /tmp/adds.json --bulk-data <path>
Verify total additions cost is within upgrade budget.
Internal evaluation for each cut (not shown to user):
If you can't articulate why a specific card should be cut, you haven't evaluated it — don't proceed.
HARD GATE. Must use two parallel Agent tool calls (subagent_type: "general-purpose"): one proposer, one challenger, with at least one revision round. This is NOT substituted by mechanical checks (mana-audit, price-check) — those catch quantitative errors; the self-grill catches strategic errors (wrong archetype assessment, missed synergy, weak justification, metagame misread).
Give both agents file paths (they can Read selectively), plus a one-paragraph bottom-line summary:
Required file paths:
Bottom-line summary example: "Proposed 8 mainboard swaps + 4 sideboard swaps for Pioneer Mono-Red. mana-audit PASS; price-check $12.50 of $20 budget; combo-search 0 combos (aggro deck). Key thesis: shift from burn-heavy to creature-heavy for better Sheoldred matchup."
Defend the proposal. Push back on challenger objections unless they provide:
The challenger must verify:
Expect 2-3 rounds minimum. If both agree immediately, the challenger isn't pushing hard enough.
HARD GATE: Write the full proposal as a complete turn BEFORE any AskUserQuestion. Do not bundle a tool call with proposal markdown — the tool executes before text finalizes, and the user approves blind.
Run build-deck to construct the new deck, then mana-audit on the result. If FAIL, revise until PASS.
Present as paired swaps with reasoning. Adapt detail to experience level.
Mainboard changes:
## Mainboard Changes (8 swaps)
**OUT: Shock (4) → IN: Play with Fire (4)**
Shock deals 2 to any target; Play with Fire deals 2 to any target OR scrys 1 when it
deals damage to a player. Strictly better in this deck since we point burn at face.
Cost: $0.50 per copy.
**OUT: Viashino Pyromancer (2) → IN: Eidolon of the Great Revel (2)**
Viashino is a one-shot 2 damage on ETB. Eidolon punishes the opponent for every spell
they cast, often dealing 6-10 damage per game in faster matchups. Key against combo
and low-curve decks.
Cost: $3.00 per copy.
...
Sideboard changes:
## Sideboard Changes (4 swaps)
**OUT: Magma Spray (2) → IN: Roiling Vortex (2)**
Magma Spray is narrow graveyard removal. Roiling Vortex hits free spells (Fury, Force),
lifegain (Sheoldred), and deals 1/turn. Better coverage across more matchups.
Cost: $1.00 per copy.
...
Budget summary:
## Budget
Total additions: $14.50 / $20.00 budget
Remaining: $5.50
HARD GATE. Run BOTH checks on the new deck before presenting close calls. This step catches emergent regressions — cross-swap interactions visible only after all changes are applied together.
deck-diff <old-deck.json> <new-deck.json> <old-hydrated.json> <new-hydrated.json>
Verify:
combo-search <new-deck.json>
Compare to Step 4 results:
If any unintended regression, revise the proposal.
Surface genuinely debatable swaps from the self-grill debate. These are cards where:
Present as user decisions:
## Close Call: Eidolon of the Great Revel vs. Harsh Mentor
**Case for Eidolon:** Hits every spell, higher floor, proven format staple.
**Case for Harsh Mentor:** Cheaper at 2 mana, punishes activated abilities (fetchlands,
planeswalker activations), but doesn't hit spells.
Which do you prefer, or would you like to test both?
Do NOT present obvious decisions as close calls. Only surface genuine disagreements.
export-deck <new-deck.json>
Outputs Moxfield/Arena import format with sideboard section.
price-check <new-deck.json> --bulk-data <path>
For Arena:
price-check <new-deck.json> --format <fmt> --bulk-data <path>
Paper:
Mainboard upgrades: $14.50
Sideboard upgrades: $3.00
Total spent: $17.50 / $20.00 budget
Remaining: $2.50
Owned cards used: 12 (not counted toward budget)
Arena:
| Rarity | Used | Available | Remaining |
|----------|------|-----------|-----------|
| Mythic | 1 | 2 | 1 |
| Rare | 3 | 4 | 1 |
| Uncommon | 4 | 8 | 4 |
| Common | 6 | 12 | 6 |
Construct a matchup-by-matchup sideboard map for the top 3-5 metagame archetypes identified in Step 4. This is a natural output of the analysis already performed — don't skip it.
## Sideboard Guide
### vs. Mono-Red Aggro (IN: 5, OUT: 5)
IN: 2 Surge of Salvation, 3 Temporary Lockdown
OUT: 2 Disdainful Stroke, 1 Negate, 2 Memory Deluge
Rationale: Trade slow counterspells for cheap answers that stabilize before turn 4.
### vs. Azorius Control (IN: 4, OUT: 4)
IN: 3 Mystical Dispute, 1 Negate
OUT: 3 Temporary Lockdown, 1 Surge of Salvation
Rationale: Sweepers are dead; load up on cheap countermagic for the permission war.
### vs. Graveyard Combo (IN: 3, OUT: 3)
IN: 3 Rest in Peace
OUT: 1 Memory Deluge, 2 Absorb
Rationale: Rest in Peace shuts down the entire strategy; trim expensive interaction.
Each entry must specify exact cards in, exact cards out, and a one-line rationale. The in/out counts must match (total mainboard stays at 60).
| Thought | Reality |
|---|---|
| "I know what this card does" | Look it up. Training data drifts. |
| "This is a format staple, it can't be a cut" | Evaluate in context. Staples can underperform in specific shells. |
| "The sideboard is fine, focus on mainboard" | Sideboard wins tournaments. Evaluate it. |
| "Skip the self-grill, the analysis was thorough" | Mechanical checks find numbers. Self-grill finds strategy. Both required. |
| "Skip impact verification, the swaps look clean" | Emergent cross-swap effects only visible post-build. Run the checks. |
| "This card is too expensive to cut" | Sunk cost. Evaluate on merit, not price. |
| "I'll just cut the worst cards" | Worst for what? Evaluate against archetype, matchups, and metagame. |
| "The mana base is close enough" | Run mana-audit. "Close enough" is how you lose to color screw. |
| "Propose changes and ask for approval in one message" | Step 8 is its own turn. AskUserQuestion comes in Step 9. |
| Aspect | Beginner | Intermediate | Advanced |
|---|---|---|---|
| Metagame explanation | Define archetypes, explain matchups | Name archetypes, note key cards | Assume knowledge, focus on novel angles |
| Swap reasoning | Full sentences, explain why old card is worse | Note specific interaction | Concise: "Bolt > Shock (scry 1 upside)" |
| Sideboard guide | Explain what sideboarding means | Provide in/out plan per matchup | Shorthand sideboard map |
| Mana base | Explain land types | Note mana base tradeoffs | Focus on marginal improvements |
parse-deck --format <fmt> <path> — Parse deck list with sideboardscryfall-lookup --batch <deck.json> --bulk-data <path> --cache-dir <dir> — Hydrate card datascryfall-lookup "<Card Name>" --bulk-data <path> — Single card lookupcard-summary <hydrated.json> [--nonlands-only] [--lands-only] [--type <T>] [--deck <deck.json> --sideboard] — Card table displaycard-search --format <fmt> [--oracle <regex>] [--color-identity <CI>] [--type <type>] [--cmc-max <N>] [--price-max <N>] — Search for candidatescombo-search <deck.json> — Find existing combos and near-missescombo-discover [--card "<name>"] [--result "<outcome>"] [--format <fmt>] — Discover comboslegality-audit <deck.json> <hydrated.json> — Check legality, 4-of, sideboard size, deck minimummana-audit <deck.json> <hydrated.json> [--compare <new-deck.json> <new-hydrated.json>] — Mana base auditprice-check <deck.json> [--format <fmt>] --bulk-data <path> [--budget <N>] — Budget checkdeck-stats <deck.json> <hydrated.json> — Deck statisticsbuild-deck <deck.json> <hydrated.json> --cuts <c.json> --adds <a.json> [--sideboard-cuts <sc.json>] [--sideboard-adds <sa.json>] [--bulk-data <path>] — Apply changesdeck-diff <old.json> <new.json> <old-hyd.json> <new-hyd.json> — Compare deck versionsexport-deck <deck.json> — Export Moxfield/Arena format with sideboardmark-owned <deck.json> <collection.csv> [--bulk-data <path>] — Mark owned cardsdownload-bulk --output-dir <dir> — Download Scryfall bulk data{
"format": "pioneer",
"deck_size": 60,
"sideboard_size": 15,
"commanders": [],
"cards": [{"name": "Lightning Bolt", "quantity": 4}, ...],
"sideboard": [{"name": "Roiling Vortex", "quantity": 3}, ...],
"total_cards": 60,
"total_sideboard": 15,
"owned_cards": [{"name": "Lightning Bolt", "quantity": 4}, ...]
}