Tarot Agent Skill — Development skill for Claude Code

Tarot Agent Skill: Reading Tarot Spreads

An [Agent Skill](https://agentskills.io) (open `SKILL.md` format) that runs tarot spreads with real card draws and live sourced meanings.

Full behavior (spread rules, interpretation synthesis, tone, and output format) lives in [`SKILL.md`](./SKILL.md). This README covers installing and running the repo.

Why this skill

• Draws are handled by a real, reproducible algorithm outside the language model, not sampled by the model itself
• Meanings come from a single grounded source, never hardcoded or reconstructed from training data
• Each spread enforces its actual historical drawing rule (suit-restricted pools, calculated cards, optional Significators), not a generic template
• Readings are synthesized as one connected argument, not assembled position by position
• Portable Agent Skill format: works with Claude Code, Codex, Gemini CLI, and other compatible agents

How cards are drawn

An LLM asked to "draw a tarot card" is not actually drawing anything. It is predicting the next likely token, which means the card it picks can drift toward whatever fits the conversation's mood rather than being genuinely random, and there is no way to verify afterward that it was not just a plausible-sounding guess.

That matters more than it sounds. A reading is worth something precisely because the cards were not chosen: something enters the conversation that nobody made fit. A model that produces cards matching the mood of the conversation hands the querent their own situation back with card names attached to it. It looks like a reading and is not one.

This skill draws for real instead. `scripts/draw_cards.py` simulates actual riffle shuffles using the Gilbert-Shannon-Reeds model (the standard model for how a human shuffles a deck), then deals from the top. The number of riffles is calculated per draw with the Bayer-Diaconis formula, about 10 for the full 78 card deck, fewer for smaller pools like Love's 14 Cups cards, fo