← all skills

tarot-single-card

/home/avalon/.hermes/skills/astrology/tarot-single-card/SKILL.md · raw

Tarot — Single Card Draw

When to use

Use when Alex asks for a single-card tarot pull, daily card, quick reading, or "draw me a card." This is the first skill in the tarot bundle; multi-card spreads will be separate skills.

Parameters

When context is provided, the reading MUST explicitly weave the card's meaning into that specific situation. When context is absent, give a general / open reading of the card and don't fabricate a focus the user didn't state. If unsure, ask — never invent. - reversals (optional) — default 30% reversal rate. Override only if Alex asks (e.g. "no reversals", "50/50").

App location

The app does NOT expose a draw-card endpoint — it only has layout summary / interpretation endpoints. So this skill draws locally from the deck JSON.

Card data shape

Each entry in cards[]:

{
  "name": "The Magician",
  "number": "1",
  "arcana": "Major Arcana",          // or "Minor Arcana"
  "suit": null,                       // or "Cups" / "Wands" / "Swords" / "Pentacles"
  "img": "m01.jpg",                   // filename in public/cards/
  "qualities": "Manifestation, skill, ..."
}

Time context (required)

Before drawing, capture wall-clock time in the user's timezone so the framing is honest (morning / evening / day-of-week). Alex's TZ is America/Los_Angeles.

TZ=America/Los_Angeles date '+%Y-%m-%d %H:%M %Z (%A)'

Do NOT infer time from voice transcript artifacts. Only frame day/night if the hour supports it.

Required workflow

Run the draw from a tool, not mentally. Use Python's secrets module for the RNG — this is a real cryptographic random draw, not seeded and not deterministic, so the pull is genuine divination rather than a narrative pick. Default reversal probability: 30% (toggleable; Alex can ask "no reversals" or "with reversals 50/50").

Before drawing, note whether a context string was supplied. If yes, record it verbatim and shape the reading around it. If no, do a general reading and say so plainly.

from hermes_tools import terminal
import json, secrets

deck = json.load(open('/home/avalon/apps/alexTarot/public/tarot-images.json'))['cards']
assert len(deck) == 78, f'expected 78 cards, got {len(deck)}'

card = secrets.choice(deck)
reversed_ = secrets.randbelow(100) < 30   # ~30% reversal rate

img_path = f"/home/avalon/apps/alexTarot/public/cards/{card['img']}"
print(json.dumps({'card': card, 'reversed': reversed_, 'img_path': img_path}, indent=2))

Reply formatting

Lead with the card itself — image and name — so Alex sees what was drawn before any interpretation. Mirror the iching-api-reading structure (story first, mechanics below).

Order (strict):

  1. Card image — ABSOLUTE FIRST LINE of the reply, with NOTHING before it. Format: MEDIA:/home/avalon/apps/alexTarot/public/cards/<img> on its own line. Do not put any prose, time stamp, italics, or framing text above this line — Telegram needs the MEDIA token at the very top for the image to render above the rest of the message. The time stamp, "no context supplied" note, and any framing belong AFTER the header and details, inside the reading section.
  2. Prominent card-name header — on its own line, e.g.: - # 🎴 The Magician - # 🎴 The Magician — Reversed
  3. Compact details line directly under the header, e.g. Major Arcana · — · 1 or Minor Arcana · Cups · 5 (arcana · suit · number; use — for suit on majors).
  4. The Reading (composite story) — weave the card's core meaning (from qualities + Rider-Waite symbolism), how orientation (upright/reversed) inflects it, and — if context was supplied — apply it explicitly to that situation. If no context, read openly.
  5. Expanded details / qualities — base qualities string from the deck JSON, any extra symbolism worth surfacing, time-context framing if it actually applies.
  6. One-breath summary — single closing line distilling the message.

If reversed, frame as inversion / blockage / shadow side / inward expression of the upright meaning — not automatic "bad." Stay grounded in traditional Rider-Waite reading conventions.

Example — with context

Context: "about today's creative work"

MEDIA:/home/avalon/apps/alexTarot/public/cards/m01.jpg

# 🎴 The Magician

Major Arcana · — · 1

(reading explicitly tied to today's creative work…)

Example — without context

MEDIA:/home/avalon/apps/alexTarot/public/cards/m01.jpg

# 🎴 The Magician

Major Arcana · — · 1

(open / general reading of The Magician, no invented focus)

Pitfalls

Verification