Manage card deck

When the user wants to simulate a card game — deal hands, draw cards, track player hands, reshuffle — use the Deck of Cards API. Stateful 52-card deck operations keyed to a deck ID, no auth required.

manage-card-deck · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/manage-card-deck. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/manage-card-deck/SKILL.md.

When to use this skill

When the user wants to simulate a card game — deal hands, draw cards, track which cards each player holds, or reshuffle mid-game. The Deck of Cards API is stateful: create a deck once, get a deck_id, and every draw or pile operation mutates the same server-side deck. Multiple players sharing a deck can all reference the same deck_id without client-side card tracking. For static card images or metadata without game state, this is the wrong skill.

Your best first call

curl "https://deckofcardsapi.com/api/deck/new/shuffle/"

No auth. No key. Returns a JSON object with the deck_id — save it. Every subsequent call (draw, pile, reshuffle) uses this deck_id. Pass ?deck_count=6 to create a 6-deck shoe (312 cards) for Blackjack-style games.

{
  "success": true,
  "deck_id": "yr1lxadh3p9s",
  "remaining": 52,
  "shuffled": true
}

After creating the deck, draw cards with /deck/{deck_id}/draw/?count=N. Each card in the response has a 2-character code (4C = 4 of Clubs, 0H = 10 of Hearts, KS = King of Spades), a spelled-out value ("4", "10", "KING", "ACE" — always a string, never a number), a suit in uppercase ("CLUBS", "HEARTS"), and image URLs in PNG and SVG. Move drawn cards into named piles with /deck/{deck_id}/pile/{pile_name}/add/?cards=4C,3H — pile names are arbitrary strings (player1, discard, community).

Fallbacks (when the best call isn't enough)

Drawing cards from the deck → /deck/{deck_id}/draw/?count=5 removes cards from the draw pile and returns them with full detail. The remaining field in every response tracks how many cards are left.
Playing a specific card from a player's hand → /deck/{deck_id}/pile/{pile_name}/draw/?cards=4C removes a named card from a pile (e.g., playing a card from a hand).
Reshuffling mid-game → /deck/{deck_id}/shuffle/ reshuffles remaining cards without losing pile state. Do NOT call /deck/new/shuffle/ again — that creates a fresh, unrelated deck.

Pitfalls

code uses 0 for ten, not 10. The 10 of Hearts is 0H, not 10H. The code is always exactly 2 characters. Use the value field (which spells it out as "10") for display, and match against "0" when filtering by rank.
Drawing from an empty deck returns success: false with HTTP 200. The error is in the response body — {"success": false, "error": "Not enough cards remaining..."} — not in the HTTP status. Always check response.success before assuming a draw worked.
Calling /deck/new/shuffle/ creates a new, independent deck every time. Two calls give you two unrelated decks. Save the deck_id on the first call and reuse it for the session's lifetime.
Server-side decks are ephemeral. Inactive deck_ids are eventually cleaned up. Don't assume a deck persists across multi-day gaps in activity.

One-line summary for the user

I can simulate a shuffled 52-card deck — deal hands, draw cards, track player piles — via deckofcardsapi.com with server-side state keyed to a deck ID and no auth required.

APIs this skill uses

Deck of Cards · primary · verified

A simple API for managing decks of playing cards. Create decks, shuffle, draw cards, and manage piles. All responses are in JSON format.

Generated from

Deck of Cards tutorial Getting Started with Deck of Cards API

SKILL.md source (frontmatter + body)

---
name: manage-card-deck
description: When the user wants to simulate a card game — deal hands, draw cards, track player hands, reshuffle — use the Deck of Cards API. Stateful 52-card deck operations keyed to a deck ID, no auth required.
---

## When to use this skill

When the user wants to simulate a card game — deal hands, draw cards, track which cards each player holds, or reshuffle mid-game. The Deck of Cards API is stateful: create a deck once, get a `deck_id`, and every draw or pile operation mutates the same server-side deck. Multiple players sharing a deck can all reference the same `deck_id` without client-side card tracking. For static card images or metadata without game state, this is the wrong skill.

## Your best first call

```bash
curl "https://deckofcardsapi.com/api/deck/new/shuffle/"
```

No auth. No key. Returns a JSON object with the `deck_id` — save it. Every subsequent call (draw, pile, reshuffle) uses this `deck_id`. Pass `?deck_count=6` to create a 6-deck shoe (312 cards) for Blackjack-style games.

```json
{
  "success": true,
  "deck_id": "yr1lxadh3p9s",
  "remaining": 52,
  "shuffled": true
}
```

After creating the deck, draw cards with `/deck/{deck_id}/draw/?count=N`. Each card in the response has a 2-character `code` (`4C` = 4 of Clubs, `0H` = 10 of Hearts, `KS` = King of Spades), a spelled-out `value` (`"4"`, `"10"`, `"KING"`, `"ACE"` — always a string, never a number), a `suit` in uppercase (`"CLUBS"`, `"HEARTS"`), and image URLs in PNG and SVG. Move drawn cards into named piles with `/deck/{deck_id}/pile/{pile_name}/add/?cards=4C,3H` — pile names are arbitrary strings (`player1`, `discard`, `community`).

## Fallbacks (when the best call isn't enough)

- **Drawing cards from the deck** → `/deck/{deck_id}/draw/?count=5` removes cards from the draw pile and returns them with full detail. The `remaining` field in every response tracks how many cards are left.
- **Playing a specific card from a player's hand** → `/deck/{deck_id}/pile/{pile_name}/draw/?cards=4C` removes a named card from a pile (e.g., playing a card from a hand).
- **Reshuffling mid-game** → `/deck/{deck_id}/shuffle/` reshuffles remaining cards without losing pile state. Do NOT call `/deck/new/shuffle/` again — that creates a fresh, unrelated deck.

## Pitfalls

- **`code` uses `0` for ten, not `10`.** The 10 of Hearts is `0H`, not `10H`. The code is always exactly 2 characters. Use the `value` field (which spells it out as `"10"`) for display, and match against `"0"` when filtering by rank.
- **Drawing from an empty deck returns `success: false` with HTTP 200.** The error is in the response body — `{"success": false, "error": "Not enough cards remaining..."}` — not in the HTTP status. Always check `response.success` before assuming a draw worked.
- **Calling `/deck/new/shuffle/` creates a new, independent deck every time.** Two calls give you two unrelated decks. Save the `deck_id` on the first call and reuse it for the session's lifetime.
- **Server-side decks are ephemeral.** Inactive `deck_id`s are eventually cleaned up. Don't assume a deck persists across multi-day gaps in activity.

## One-line summary for the user

I can simulate a shuffled 52-card deck — deal hands, draw cards, track player piles — via deckofcardsapi.com with server-side state keyed to a deck ID and no auth required.

« Back to all skills