Spellbook

CLI skills framework for AI coding assistants — give Claude Code, Cursor, and Copilot real-world superpowers

---

The Problem

AI coding assistants live inside your terminal. They can read files, write code, and run commands — but they can't do things in the real world:

• Send a message to your team
• Create a note in Apple Notes
• Check the weather
• Take a screenshot
• Set a reminder
• Search the web

Spellbook fixes this. It's an open-source skills framework that gives your AI assistant real-world actions through simple CLI commands.

┌──────────────────────────────────────────────────┐
│                Your AI Assistant                  │
│          (Claude Code / Cursor / Copilot)         │
│                                                   │
│    "Send a message to the team about the deploy"  │
│                       │                           │
│                       ▼                           │
│              spellbook cast telegram              │
│              --chat 123456789                     │
│              --message "Deploy complete"          │
│                                                   │
│    ┌─────────┐ ┌─────────┐ ┌─────────┐          │
│    │messaging│ │  notes  │ │ system  │           │
│    │         │ │         │ │         │           │
│    │imessage │ │ apple-  │ │ screen- │           │
│    │whatsapp │ │ notes   │ │ shot    │           │
│    │telegram │ │         │ │ weather │           │
│    └─────────┘ └─────────┘ └─────────┘          │
│    ┌──────────┐ ┌─────────┐                      │
│    │automation│ │ search  │   + your custom       │
│    │          │ │         │     spells             │
│    │reminders │ │web-srch │                       │
│    │          │ │summarize│                       │
│    └──────────┘ └─────────┘                      │
└──────────────────────────────────────────────────┘

---

Quickstart

# List all available spells
npx spellbook-ai list

# Cast a spell
npx spellbook-ai cast weather --city "Tokyo"

# Create your own spell
npx spellbook-ai create

Or install globally:

npm install -g spellbook-ai
spellbook list
spellbook cast imessage --to "+1234567890" --message "Hello from AI"

---

Built-in Spells

Messaging

Spell	Platform	Description
imessage	macOS	Send iMessages and SMS via Messages app
whatsapp	macOS/Linux	Send WhatsApp messages (via wacli)
telegram	All	Send Telegram messages via Bot API

Notes

Spell	Platform	Description
apple-notes	macOS	Create, search, and list Apple Notes

Automation

Spell	Platform	Description
reminders	macOS	Add and list Apple Reminders

Search

Spell	Platform	Description
web-search	All	Search the web via DuckDuckGo (no API key)
summarize	All	Summarize URLs, files, or text

System

Spell	Platform	Description
screenshot	macOS	Capture screenshots with region/window selection
weather	All	Get weather forecasts (no API key needed)

---

Creating Custom Spells

spellbook create

This creates a spell template in ~/.spellbook/spells/ with:

• spell.json — manifest (name, description, platform, dependencies)
• run.sh (or .js/.py) — the spell logic

Spell Structure

my-spell/
├── spell.json      # Manifest
├── run.sh          # Entry point (bash/node/python)
└── README.md       # Documentation

spell.json Format

{
  "name": "my-spell",
  "description": "What this spell does",
  "version": "1.0.0",
  "category": "automation",
  "platforms": ["darwin", "linux"],
  "requires": ["curl", "jq"],
  "entry": "run.sh",
  "usage": "spellbook cast my-spell --flag <value>",
  "examples": [
    "spellbook cast my-spell --name test"
  ]
}

---

Integration with Claude Code

Add this to your CLAUDE.md to make Claude aware of available spells:

spellbook claude-md >> CLAUDE.md

This generates a section listing all installed spells with usage examples. Claude Code will then use them naturally when appropriate.

Example CLAUDE.md Section

## Spellbook Skills

### Messaging
- **imessage** — Send iMessages. Usage: `spellbook cast imessage --to <phone> --message <text>`
- **telegram** — Send Telegram messages. Usage: `spellbook cast telegram --chat <id> --message <text>`

### System
- **weather** — Get weather forecasts. Usage: `spellbook cast weather --city <name>`

---

How It Works

spellbook cast <spell> [args]
        │
        ▼
  Load spell.json manifest
        │
        ▼
  Check platform compatibility
        │
        ▼
  Verify dependencies (requires)
        │
        ▼
  Execute entry script (bash/node/python)
        │
        ▼
  Output to stdout (AI reads the result)

Key design decisions:

1. No daemon. Spells are stateless CLI commands — run and done.
2. Multi-language. Write spells in bash, Node.js, or Python.
3. Platform-aware. Spells declare supported platforms and dependencies.
4. Zero config. Built-in spells work out of the box on macOS.
5. AI-native. Output is designed for LLMs to parse and act on.

---

vs. Alternatives

Feature	Spellbook	OpenClaw	Custom scripts
Structured manifests	Yes	No	No
Platform checks	Yes	No	Manual
Dependency validation	Yes	No	Manual
Spell categories	Yes	Limited	No
CLAUDE.md generation	Yes	No	No
Custom spell creator	Yes	CLI only	Manual
Multi-language support	bash/node/python	Varies	Varies
No daemon required	Yes	No	Yes

---

Contributing

1. Fork this repo
2. Add your spell to spells/<category>/<name>/
3. Include spell.json + entry script + README
4. Submit a PR

Wanted spells: Slack, Discord, Notion, Google Calendar, Spotify, Home Assistant, Docker management, AWS CLI helpers.

---

Related

• claude-enchant — Auto-triggering behavioral rules for Claude Code
• awesome-claude-md — Curated CLAUDE.md examples + generator
• claude-hooks-kit — Copy-paste hook recipes for Claude Code

---

License

MIT

_{Built by Anuar AX}