---
name: hearthstone-deck-builder
description: Build Hearthstone decks and produce a verified import deck code/deckstring that the Hearthstone client can load from the clipboard. Use this whenever the user asks for a Hearthstone deck, deck list, meta deck, budget deck, Standard/Wild/Twist/Arena-like constructed list, deck code, import code, auto-load code, or wants a Hearthstone deck copied into the game.
---

# Hearthstone Deck Builder

Create Hearthstone decks that are both strategically coherent and importable by the game client.

## Core workflow

1. **Clarify the target only if needed.** Prefer reasonable defaults: latest Standard, competitive ladder, no dust cap, user region not relevant. Ask only when class/archetype/budget/format materially changes the answer.
2. **Use current information.** Hearthstone card pools, balance patches, set legality, and meta decks change often. Browse or use current card/meta sources unless the user explicitly asks for an off-meta/theorycraft list or provides all cards.
3. **Draft the 30-card (or explicitly valid alternate-size) main deck.** Respect class identity, copy limits, legendary limits, sideboard/tourist/rune/etc. restrictions, and current format legality.
4. **Generate the deck code with `scripts/build_deck_code.py`.** Do not hand-invent deckstrings. The script encodes the Hearthstone deckstring format, resolves card names to DBF IDs via HearthstoneJSON or a provided cards JSON, validates common constructed constraints, and prints an import block.
5. **Verify before presenting.** Re-run with `--decode` on the generated code or inspect the script output. If card-name resolution is ambiguous, fix the card by DBF ID/card ID rather than guessing.
6. **Present the result in clipboard-ready form.** Include the deck import block and concise instructions: copy the whole block or just the deck code, open Hearthstone, create a new deck, and accept the detected clipboard deck.

## Using the bundled script

Preferred input is a small JSON deck file:

```json
{
  "name": "Elemental Mage",
  "class": "Mage",
  "format": "standard",
  "cards": [
    {"name": "Example Card", "count": 2},
    {"dbfId": 12345, "count": 1}
  ],
  "sideboard_cards": [
    {"name": "Sideboard Card", "count": 1, "owner": "E.T.C., Band Manager"}
  ]
}
```

Then run:

```bash
python3 <skill-dir>/scripts/build_deck_code.py --input deck.json
```

Useful options:

- `--cards-json path/to/cards.collectible.json` uses a local HearthstoneJSON file.
- `--no-fetch` avoids network and requires each card/hero/sideboard owner to provide DBF IDs.
- `--copy` tries to put the import block on the system clipboard.
- `--decode AAE...` decodes a deck code for verification/debugging.
- `--deck-size 30`, `--deck-size 40`, or `--deck-size none` controls count validation.

For cross-CLI installation/pointer patterns, see `references/ai-cli-install.md`.
For example deck JSON shapes, see `references/deck-json-examples.md`.

## Handling ambiguous cards

Many Hearthstone card names have multiple collectible printings. If the script reports ambiguity:

- Prefer adding `dbfId` to that card entry after checking a current card database.
- If using a meta source that provides deck codes, decode the source deck code and compare DBF IDs.
- Do not silently choose between duplicate names unless the user asked for a casual approximation; import correctness depends on exact IDs.

## Output format

Give the user:

1. Deck name, class, format, and a one-paragraph game plan/mulligan summary.
2. The import block exactly as generated by the script.
3. A short note that the deck code is what Hearthstone reads from the clipboard.

Keep the import block intact; avoid wrapping the deck code across multiple unrelated paragraphs.