book-to-skill

book-to-skill

English · Русский · 简体中文

Turn any technical book, document folder, or collection of sources into a unified agent skill — ready to study, reference, and use while you work in GitHub Copilot CLI, Amp, Claude Code, Codex, Hermes Agent, OpenCode, or OpenClaw.

Why · What it generates · Beyond books · How it works · Usage · Install · FAQ · Performance · Architecture · Changelog

24×–51× fewer tokens than dumping the book into context to answer one question, measured on real books (how it's measured).

How it works, in 3 steps:

1. Point it at a file, folder, or glob — /book-to-skill ./my-book.pdf
2. It distills the book into a skill — frameworks, decision rules, anti-patterns, and per-chapter files. Structure, not a summary.
3. Your agent loads it on demand — ask /my-book replication and it reads the right chapter and answers from the real content, no hallucination.

---

🤔 Why

You buy a great technical book. You read it once. Three months later you can't remember chapter 7 existed.

The usual workarounds don't help:

• 📄 "Let me just search the PDF" → you get a list of pages, not answers
• 🧠 "I'll ask the agent about this book" → it either hallucinates or says it doesn't have the content
• 📝 "I'll take notes as I read" → you end up with a 200-line doc you never open again

book-to-skill solves this by turning the book into a structured skill your agent loads on demand.

Once installed, you just type /your-book-slug replication and the agent reads the right chapter and answers from the actual content. No hallucination. No digging through PDFs. The book becomes part of your workflow.

Works with any host that supports the open Agent Skills standard — GitHub Copilot CLI, Amp, Claude Code, Codex, Hermes Agent, OpenCode, and OpenClaw all read the same SKILL.md format.

📦 What it generates

Running /book-to-skill your-book.pdf (or a folder, glob, or list of files) creates a full skill in the user-level cross-agent skills directory ~/.agents/skills/<slug>/ — one copy that Copilot CLI, Amp, Codex, OpenCode, and OpenClaw discover natively (OpenCode also reads its own managed root ~/.config/opencode/skills/<slug>/; OpenClaw also discovers it when using its default state directory, with a non-default OPENCLAW_STATE_DIR use the active state's skills/ root instead). When run under Claude Code, the converter also attempts a verified symlink at ~/.claude/skills/<slug>/ — Claude Code sees the skill when the link read-back confirms it; otherwise the run report says so. Hermes Agent partitions its personal skills by category and does not scan the cross-agent root, so a Hermes install lands in /skills/<category>/<slug>/ instead. OpenClaw-managed, OpenCode-managed, and project-local destinations remain available when explicitly requested:

File	Purpose	Size
SKILL.md	Core mental models + chapter index	~4,000 tokens
chapters/ch01-*.md …	One file per chapter, loaded on-demand	~1,000 tokens each
glossary.md	Every key term, alphabetically sorted with chapter refs	~1,500 tokens
patterns.md	All techniques, algorithms, and design patterns	~2,000 tokens
cheatsheet.md	Decision tables and quick-reference rules	~1,000 tokens

Chapter files are loaded on-demand — they don't count against the skill budget until you ask about that topic.

---

🏢 Beyond books

The name says "book", but the input is any structured prose. The same extraction works on knowledge you own and re-read constantly:

• Internal documentation — architecture decision records, runbooks, onboarding guides. Fold a whole docs/ folder into one skill and ask it while you code.
• Brand & design systems — voice guidelines, tone-of-voice docs, component principles. Turn a brand book into a skill your team queries instead of skimming a 60-page PDF.
• Research clusters — a stack of papers plus your own notes, merged into a single unified skill and updated as new material lands (see Update / fold-in).
• Specs & standards — RFCs, API contracts, compliance docs you reference but never memorize.

If you re-open a document often enough to wish you'd memorized it, it's a candidate.

---

🧾 The Discovery Loop Tax

A PDF-reading agent doesn't just read — it navigates: it re-fetches the ToC, backtracks, and re-processes all of it on every turn. book-to-skill pays that structuring cost once, at conversion, so queries stay proportional to the answer — 24×–51× fewer tokens than dumping the book into context, measured on real books.

📊 Full methodology, numbers, and per-book tables → docs/performance.md

---

⚙️ How it works

Two halves: a deterministic Python extractor (document → clean text + metadata) and a spec-driven generator (your agent follows SKILL.md to turn that into a structured skill). On-demand chapter files keep the loaded skill small.

🔧 Full walkthrough (Steps 0–10, extraction modes, token budgets) → docs/how-it-works.md

---

🚀 Usage

/book-to-skill [skill-name] — plus analyze-only, generate-from-analysis, and update/fold-in modes. After a conversion, the converter can publish the skill to GitHub (private by default) so any host installs it with npx skills add.

▶️ All modes and examples → docs/usage.md

💬 In practice → use cases — a DevEx book became a survey of 300+ engineers; a scanned PDF that stalled became #130. Add yours: the account lives in your own Gist, the index takes a one-line PR.

---

📥 Install

# One command, any host — via the cross-agent