ai-divination-skills

Three thousand years ago, Shang kings carved their divinations into bone — the first auditable record of an oracle at work. Oraclebone brings the same discipline to AI agents: audited scripts produce the draw, the hexagram, the pillars; the model only interprets what it is given. It never invents the result.

🔮 Open-source divination toolkit for AI agents, formerly known asai-divination-skills(renamed in v8.0.0 — the old PyPI package is frozen; installoracleboneinstead).

oracleboneis a practical skill collection for tarot, I Ching, Xiao Liu Ren, and future symbolic systems. It is built for agent workflows that need auditable randomness, clear method boundaries, and reusable interpretation templates.

This project treats divination as symbolic reasoning and reflection, not deterministic prediction.

Install Oraclebone for this agent: https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/docs/install.md

Or install directly for Claude-style local skills:

curl -fsSL https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/install.sh | bash

The default target is~/.claude/skills. SetAI_SKILLS_DIRfor another agent skill directory.

Most AI divination prompts let the model invent the result. This repo separates the two jobs:
- A local script produces the card draw, hexagram, or Xiao Liu Ren position.
- The AI agent interprets that generated result with clear safety boundaries.

That makes readings easier to test, reproduce, audit, and reuse across agents.

The core rule is simple: scripts or user-provided physical casts generate the divination result; AI interprets that result and does not generate the divination result.

This is not scientific proof of divination efficacy. It is a stricter workflow for symbolic reasoning:

- real readings use system randomness by default
- seeded mode is only for tests and reproducible demos
- traditional methods and limitations are documented per skill
- JSON outputs include enough metadata to audit the method
- approximate modes emit warnings instead of pretending to be traditional

The GitHub Pages site now defaults to Simplified Chinese. Use the page header switcher there when you want English or Japanese.

https://sapuyou45-bit.github.io/oraclebone/

ai-divination tarot --deck major --spread three-card --reversals ai-divination iching --method yarrow ai-divination xiaoliuren --method numbers --month 3 --day 12 --hour 7

Ask for an agent interpretation template:

from oraclebone.tarot import draw from oraclebone.iching import cast from oraclebone.xiaoliuren import cast_numbers

You can still run the underlying scripts directly:

python3 skills/tarot/scripts/draw.py --deck major --spread three-card --reversals python3 skills/iching/scripts/cast.py --method coins python3 skills/iching/scripts/cast.py --method yarrow python3 skills/xiaoliuren/scripts/cast.py --method numbers --month 3 --day 12 --hour 7

python3 skills/tarot/scripts/draw.py --spread decision --seed demo python3 skills/iching/scripts/cast.py --method yarrow --seed demo

For AI-agent-guided setup, use the remote install runbook:

Install Oraclebone for this agent: https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/docs/install.md

curl -fsSL https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/install.sh | bash

The installer copiestarot,iching, andxiaoliureninto~/.claude/skillsby default. To target another agent, setAI_SKILLS_DIRbefore running it.

Manual install is just copying the folders you want into your agent's skill directory:

mkdir -p ~/.claude/skills cp -R skills/tarot ~/.claude/skills/tarot cp -R skills/iching ~/.claude/skills/iching cp -R skills/xiaoliuren ~/.claude/skills/xiaoliuren

skills/name/ SKILL.md agents/openai.yaml scripts/ references/

Install individual folders, not the entire repository, when you only want one skill.

Each skill script also works in single-folder mode. If the Python package is installed, the script delegates to the package runtime. If only the skill folder is copied, it falls back to the bundled standalone script in that skill.

Every skill ships four adapter files inskills/<skill>/agents/:

All four adapters route through the same auditedai-divination <skill>CLI, so the agent host never invents the result.

🧠 Use it from Claude Desktop / Codex / any MCP host

oracleboneships a built-inMCP server(ai-divination-mcp). AnyModel Context Protocolhost — Claude Desktop, Codex, Continue, Cursor — can mount it with a single config line, and the model gets five tools:tarot_draw,iching_cast,xiaoliuren_cast,bazi_cast, andinterpretation_template.

{ "mcpServers": { "divination": { "command": "ai-divination-mcp" } } }

- Claude Desktop
- Codex CLI
- Cursor
- Continue

- Releases:https://github.com/sapuyou45-bit/oraclebone/releases
- Roadmap:ROADMAP.md
- Discussions:https://github.com/sapuyou45-bit/oraclebone/discussions
- Issues: pick agood first issueor propose anew-skill
- Security: seeSECURITY.mdfor private vulnerability reporting

Provides tarot card readings, including single card draws, multi-card spreads, and full deck access.