Skip to content

Architecture

Overview

Spellbook provides a multi-platform skill system with these core components:

spellbook/
├── skills/           # Reusable workflow definitions
├── commands/         # Slash commands
├── agents/           # Specialized agent definitions
├── rules/            # Installable rule modules (global behavioral instructions)
├── spellbook/    # MCP server for skill discovery
├── lib/              # Shared JavaScript utilities
├── installer/        # Installation components
└── extensions/       # Platform-specific extensions

Skill Resolution

Skills are resolved in priority order:

  1. Personal skills ($CLAUDE_CONFIG_DIR/skills/) - User customizations
  2. Spellbook skills (<repo>/skills/) - This repository

Namespace Prefixes

Skills can be explicitly namespaced:

  • spellbook:skill-name - Force spellbook version
  • personal:skill-name - Force personal version
  • skill-name - Use priority resolution

Platform Integration

Claude Code

Native integration via: - Skills loaded from ~/.claude/skills/ - Commands from ~/.claude/commands/ - MCP server for runtime skill discovery - Session initialization via CLAUDE.md context file

OpenCode

Native integration via AGENTS.md and MCP: - Context installed to ~/.config/opencode/AGENTS.md - MCP server registered in ~/.config/opencode/opencode.json - Skills read natively from ~/.claude/skills/* (no separate installation needed)

Codex

Native skill integration via AGENTS.md and MCP: - MCP server registered in ~/.codex/config.toml - Context installed to ~/.codex/AGENTS.md - Skills symlinked to ~/.codex/skills/ for native discovery

Gemini CLI

Native extension system: - Extension linked via gemini extensions link to extensions/gemini/ - Extension provides MCP server config and GEMINI.md context - Skills symlinked in extensions/gemini/skills/ for native discovery

Note: Native skills support is pending GitHub Issue #15327. As of January 7, 2026, this feature is unreleased. Skills will be auto-discovered once the epic lands in an official Gemini CLI release.

MCP Server

The spellbook/ directory contains a FastMCP server providing 100+ tools across these categories:

  • Session management - initialization, mode switching, context ping, compaction checks
  • Input gates - injection pattern detection for Bash commands, spawn-session calls, and workflow state saves
  • Memory - store, recall, consolidate, forget
  • Fractal thinking - graph creation, node management, worker dispatch, synthesis
  • Forge (autonomous development) - project initialization, iteration management, roundtable convening
  • Experiments / A-B testing - create, start, pause, complete, view results
  • PR distillation - fetch PRs, diff analysis, pattern matching and blessing
  • Notifications - native OS notifications
  • Workflow state persistence - save, load, update workflow state across sessions
  • Focus tracking - stint push, pop, check, replace
  • Configuration management - get/set config values, skill instructions
  • Health checks and analytics - health check, analytics summary, telemetry controls
  • Session spawning - launch new Claude sessions with custom prompts

File Formats

SKILL.md

---
name: skill-name
description: When to use - what it does
---

## Skill content...

Command Files

Markdown files in commands/ are exposed as /<filename> slash commands.

Agent Files

Markdown files in agents/ define specialized agent behaviors.

Rule Modules

Markdown files in rules/ are the global behavioral instructions the installer delivers to each platform. Each file is named XX-<id>.md, where the numeric prefix sets delivery order and <id> is a stable identifier that survives renumbering. YAML frontmatter declares the module's id, name, class (mandatory or preference), default state, description, benefit, and related artifacts.

Delivery depends on what the harness can read:

  • Directory-capable platforms (Claude Code, Antigravity, OpenCode) receive one symlink per selected module, named XX-spellbook-<id>.md, so module identity survives at the destination.
  • Flat platforms (Codex, ForgeCode, Gemini CLI, Pi) receive a generated concatenation written at the harness's real instruction path, because they cannot follow a reference.

Mandatory modules install unconditionally. Preference modules are offered during installation and recorded under rules.module.<id> config keys, whose tri-state semantics (true kept / false declined / absent never offered) let a re-install pre-check newly added modules without resurrecting declined ones.