# Mtg Card Finder > >- - **Type:** Skill - **Install:** `agentstack add skill-guuse-claude-mtg-skills-mtg-card-finder` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [guuse](https://agentstack.voostack.com/s/guuse) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [guuse](https://github.com/guuse) - **Source:** https://github.com/guuse/claude-mtg-skills/tree/main/mtg-skills/skills/mtg-card-finder ## Install ```sh agentstack add skill-guuse-claude-mtg-skills-mtg-card-finder ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # MTG Card Finder & Deck Problem-Solver This skill helps a player **find the right cards** — and figure out which cards those even are. It is not a deckbuilder (that's `mtg-edh-build` / `mtg-std-build`) and not a full-list upgrader (`mtg-edh-upgrade` / `mtg-std-upgrade`). It is the **consultative step before or beside those**: a focused, conversational search for the cards a specific player needs for a specific purpose — a commander to build around, the missing piece in a category, the synergy engine for a theme, or the fix for a problem a deck keeps running into. Two ideas drive everything here: 1. **Brainstorm to find the *real* need, not the stated one.** Players usually arrive with a guess at the solution ("I need more removal", "I need a bigger finisher"). Often the guess is wrong — the deck dies to board wipes because it overcommits, not because it lacks protection; it "can't close" because it runs out of cards three turns before the kill, not because the finisher is too small. **Your job is to diagnose the underlying need by talking with the user**, then find cards for *that*. Treat the opening request as a symptom to investigate, not a spec to fulfill. 2. **Research card text exhaustively to find cohesion.** Great recommendations come from reading the actual **Oracle text and type lines** of many cards and noticing which ones share *multiple* points of contact with the user's deck and with each other. A card that touches the theme three different ways is worth ten that touch it once. The whole value of this skill over a generic "good cards" list is that it reads the wording closely and finds the cards that genuinely cohere. **This is a conversation, not a one-shot lookup.** Don't dump a list and leave. Pin the purpose, brainstorm the context, research, then present a *shortlist with reasoning* and refine it with the user. Default to asking a sharp question over assuming. ## The shape of a session Work through these phases in order. Phases 1–2 (purpose + brainstorm) are what make the recommendations *theirs*; Phase 3 (deep card research) is what makes them *good*. Full detail and the diagnostic playbook live in `references/methodology.md` — **read it before recommending anything** — and the synergy-scoring loop that decides which cards make the cut is in `references/synergy.md` (**read this too; it is the core craft**). The Scryfall query cookbook is in `references/scryfall-syntax.md`. ### Phase 1 — Establish the purpose Before anything else, find out **what kind of card-finding this is.** Ask the user (or infer from their prompt and confirm) which of these they're after — these are the modes the skill serves: - **Find a commander** — they want a legendary creature (or other commander) to build a deck around, by vibe/playstyle rather than a named card. - **Fill a gap** — an existing deck is short in a specific area they can name (not enough lands, thin on ramp, no board wipes, weak mana fixing) and they want the best cards to fill it. - **Add / improve a category** — they want the best **card advantage**, **ramp**, **removal**, **counterspells**, **protection**, **recursion**, or **finishers** in a given color identity / format. - **Find synergy pieces** — they have a theme, engine, combo, or a specific card and want cards that **synergize** with it (this is the deep-research sweet spot). - **Solve a problem** — a symptom, not a category: "I run out of cards", "I can't close games", "I flood / screw constantly", "I lose to a particular table/deck", "my deck is too slow / too fragile". **This mode needs the most brainstorming**, because the stated symptom rarely names the real fix. If the request spans several modes, that's fine — name them and handle them in priority order. If you can't tell which mode it is, **ask**. Keep this light: one or two sentences to lock the purpose, then move on. ### Phase 2 — Gather context by brainstorming (branch by mode) Now gather the context the search needs — **as a brainstorm, not an intake form.** Ask a few pointed questions, react to the answers, and follow the interesting threads. The goal is to understand the player and the deck well enough to find cards *they* will love and that *fit*. Tailor the questions to the mode: **Finding a commander — ask about the player, not just the deck:** - **Playstyle** — do they like to attack, grind value, control the table, combo off, go wide with tokens, go tall with one big threat, play politics/group-hug, durdle and build an engine? - **What they enjoy and what they hate** — favorite past decks and *why*; play patterns they find boring or miserable (mana screw, durdling, getting archenemy'd, non-games). - **Gimmicks and pet themes** — a tribe, a mechanic (sacrifice, +1/+1 counters, lifegain, mill, spellslinger, reanimator, blink, artifacts, lands-matter), an aesthetic, a character they love. - **Colors** — preferred colors or color count, or "surprise me"; how much they mind a hard 3–5-color mana base. - **Constraints** — budget, power bracket/table level, whether they want something off-meta or proven, and any "don't be that guy" lines (no stax, no MLD, no infinite combo) — see `references/brackets.md`. - Then **propose a few candidate commanders by the rule of cool** (most fun for *this* player) tempered by "don't pick something that stops the table playing", with the exact Oracle text and what each would *play like*, and let them react. Narrowing to the right commander is itself the deliverable here. **Filling a gap / adding a category / finding synergy / solving a problem — anchor on the deck:** - **Get the deck.** Ask them to **paste the decklist** if they have one (a Moxfield/Archidekt export or a `1 Card Name` list) — or if they give a Moxfield/Archidekt **link**, run `scripts/import_deck.py ` to pull it via the site JSON API (falls back to asking for a paste if the deck is private/unreachable). Otherwise have them describe the commander/archetype, colors, and game plan. Pull the commander's (and any keystone card's) real Oracle text from Scryfall so you work from exact wording. - **Understand the engine and game plan** — what the deck is *trying to do*, how it currently wins, what its best turns look like. You can't judge cohesion without knowing the machine you're adding to. - **Probe the actual symptom (especially in problem-solving mode).** Don't accept the first diagnosis. Ask *when* it goes wrong and *against what*: which turns feel bad, what the board looks like when they lose, whether it's a consistency problem (happens every game) or a matchup problem (one table). Trace the symptom to a cause before naming cards — see the diagnostic playbook in `references/methodology.md`. - **Constraints** — color identity (hard limit), format/legality, budget (Cardmarket EUR), power bracket/table level, pet cards to keep, and cards already tried that didn't work. **Pinpoint the real need before you search.** Reflect back what you heard as a crisp problem statement — *"so the real issue is you have plenty of threats but no way to refuel after a wipe, and you want cheap, repeatable card advantage that survives a board reset"* — and get the user to confirm or correct it. If your read differs from their opening request, **say so and explain why**, and let them decide. Only search once you both agree on what you're actually looking for. ### Phase 3 — Research the card pool deeply (synergy scoring) This is the skill's craft, and it follows one disciplined loop — **read → extract → map → search → intersect → score** — documented in full in `references/synergy.md`. **Read that file; it is the heart of this skill.** The non-negotiable rule it enforces: **every card you recommend must share at least 2–3 synergies ("points of contact") with the deck/commander and ideally with the other cards — and the more points of contact, the better.** Rank candidates by synergy count and take the densest. 1. **Read the card (this is the irreplaceable, Claude-only step).** Pull the **exact Oracle text and type line** of the commander/centerpiece and every serious candidate (`--named "Card Name"`). *You* interpret what the card actually does — a tag search can't decide what matters; it only finds what you tell it to. 2. **Extract the key elements** — every actionable concept the card produces or rewards: triggers (*enters, attacks, a creature dies, landfall, lifegain*), actions (*sacrifice, create a token, +1/+1 counter, draw, blink, recur*), the **types/subtypes** it cares about, **keywords**, and numeric axes. This list is the deck's **synergy vocabulary** / shopping list. 3. **Map each element to a Scryfall handle.** Prefer the most specific that exists: curated **Tagger tags** `function:` / `otag:` for well-known roles (`otag:sacrifice-outlet`, `function:card-advantage`, `otag:token-maker`, `function:ramp`, `otag:flicker`); **oracle text** `o:"…"` for specific phrases; **types** `t:…`; **keywords** `keyword:…`. Tags are curated to catch a *role* across different wordings — the fast path — and route to the live API automatically; when a tag is thin, union it with the `o:"…"` phrasing. (See the mapping table in `references/synergy.md`.) 4. **Search each element within the color identity, then INTERSECT.** Combine handles in one query (`id"` — its high-"synergy" ranking is gold here), then use **Scryfall** to fill gaps and dig up spicy multi-synergy cards the aggregate buries; for other formats, lean on Scryfall plus the model's meta knowledge (flagged unverified). **Vet color identity and legality as you go** — `id` (NOT `c:`, which matches off-identity multicolor cards), glance at the **CI** column; one off-identity pip makes a card illegal in a Commander deck. ### Phase 4 — Present a shortlist with reasoning, then refine Hand back a **focused shortlist** (not a data dump) — usually **5–15 cards**, or **a handful of commanders** in commander-finding mode — each with: - the **card name, mana value, type line, color identity, and Cardmarket EUR price**; - a **one-to-two-line reason** that names the *specific* synergy or problem it addresses — the points of contact you found, e.g. *"hits both your 'creature dies' and 'sacrifice' triggers, and refuels after a wipe — three points of contact"*; - where useful, **what it would replace or how it slots in**, and any **trade-off** (fragile, slow, pricey). Group the shortlist by the need it serves, and **lead with the cards that address the real (diagnosed) need** — if that differs from the user's opening ask, show both but explain the reorder. Where there's a genuine choice, offer **2–3 options with the trade-off** rather than dictating one (e.g. budget vs. premium, fast vs. resilient). Then **invite reaction** — too expensive, already own it, want spicier/safer, want to go deeper on one thread — and iterate. Re-query and refine until the user has the cards they actually want. ## The deliverable The primary deliverable is the **refined shortlist in the conversation** — this skill is a search, and most sessions end when the user has the cards they wanted. **Don't write files unless the user asks** (or the shortlist is large enough that they'd clearly want to keep it). When they do want it saved, write a single findings file and share it with the `present_files` tool: `.mtg/finds/.md` in the resolved workspace (slug = the commander/theme/problem, kebab-case). It should contain the **problem statement you agreed on**, the **shortlist grouped by need** (name · MV · type · CI · EUR · reason), the **total price** of the picks, and a short "how these fit" note. If the user instead wants these cards turned into a full deck or slotted into an existing list, **hand off to the appropriate deckbuilding skill** (`mtg-edh-build` / `mtg-edh-upgrade` / `mtg-std-build` / `mtg-std-upgrade`) carrying the context you gathered — don't rebuild a whole deck inside this skill. ## The `.mtg` workspace This skill only writes when the user asks for a saved findings file; even so, its I/O lives in the same **workspace** the other MTG skills use, resolved in this order: 1. **`$MTG_HOME`**, if set — the user's portable data location (e.g. a private `mtg-data` git repo; see the repo's `SYNCING.md`). Use it even if subfolders don't exist yet — create them. 2. Otherwise the nearest **`.mtg/`** at or above the current working directory (conventionally git-ignored). Run **`python "${CLAUDE_SKILL_DIR}/scripts/scryfall_search.py" --paths`** to print the resolved `decks/`/`collection/`/`database/` paths as JSON (it creates nothing); findings go in a sibling `finds/` folder. **If `$MTG_HOME` is unset and there's no clear working directory** and the user *does* want a file saved, ask where the workspace should live first. (Pure search sessions that write nothing don't need this.) Reading a `collection/` file, if one exists, is a nice touch — prefer cards the user already owns when two picks are otherwise close, and flag which shortlisted cards they'd need to buy. ## How to drive the data sources Same backbone as the deckbuilding skills — **EDHREC's JSON API** (`scripts/edhrec_fetch.py`) for proven inclusions, **Scryfall** for deep text/type search, color-identity vetting, and **pricing** (`prices.eur` = Cardmarket EUR). Full endpoint/fallback table: `references/data-sources.md`. EDHREC is fetched from `json.edhrec.com` with a descriptive UA + retry/backoff — never the Cloudflare HTML; on 403/404 fall back to the local Scryfall DB ordered by EDHREC rank and say so. **Scryfall reads come from the local card database.** `scripts/scryfall_search.py` queries a **local SQLite database** (`.mtg/database/cards.sqlite`, built from Scryfall bulk data — see the **mtg-db** skill) instead of the API. It's built **automatically on first use** (one-time ~540 MB download); just call the script. If it reports the data is **stale (>30 days)**, mention prices may have moved and **ask** whether to refresh before continuing. `function:`/`otag:` (Tagger) tags route to the live API automatically. Retrieval, in order of preference: - **Code execution with network** → `python "${CLAUDE_SKILL_DIR}/scripts/scryfall_search.py" "" --limit 30` (reads the local DB, auto-builds on first use; prints name, MV, type, CI, cheapest-printing EUR; `--named "Sol Ring"` for one card's full text + price). Fastest path; `function:` queries use the live API transparently. **Use `--named` liberally here** — reading exact Oracle text is the core of Phase 3. - **No code-exec network, but web tools** → `web_fetch` the **JSON** endpoints directly (`https://json.edhrec.com/pages/commanders/.json`) and the Scryfall search page; `web_search` first if `web_fetch` needs a search-sourced URL. No DB can be built here — that's the expected fallback. - **Neither** → tell the user the environment needs network to `api.scryfall.com` and `json.edhrec.com`, and offer to proceed from known MTG knowledge with the caveat that prices, proven inclusions, and the newest cards won't be verified. ## Quality bar before you recommend - **The recommendations target the *diagnosed* need**, not just the literal opening request — and if those differ, you said so and the user agreed on the direction. - **Every recommended card clears the ≥2–3 synergy floor** (except pure structural utility — lands/ramp/ catch-all removal), and its reason **names the specific points of contact** it hits, drawn from its actual Oracle text / type line — no vague "it's a good card". You read the wording and counted the contacts. - **Color identity & legality check out** for every pick (vet with `id<=`, glance at the **CI** column; one off-identity pip makes a card illegal in a Commander deck), and prices are shown (Cardmarket EUR; note `null` prices rather than guessing). - **The list is a shortlist, not a dump** — focused, grouped by need, with trade-offs an … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [guuse](https://github.com/guuse) - **Source:** [guuse/claude-mtg-skills](https://github.com/guuse/claude-mtg-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-guuse-claude-mtg-skills-mtg-card-finder - Seller: https://agentstack.voostack.com/s/guuse - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.