book-to-skill README

The project's README from github.com/virgiliojr94/book-to-skill. As one markdown file: README.md.

Booklin, the book-to-skill wizard, holding an open book whose pages scatter into sparkles that settle into an ordered grid

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.

Latest release Agent Skills standard Formats supported MIT License Sponsor

virgiliojr94%2Fbook-to-skill | Trendshift virgiliojr94%2Fbook-to-skill | Trendshift (daily, Python) Star History Rank

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

Booklin — the book-to-skill mascot, a purple wizard holding a book

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:

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:

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 <path|folder|glob> [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 skills CLI:
npx skills add virgiliojr94/book-to-skill

# Or manually — clone into your skills folder (registers /book-to-skill):
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# (Copilot CLI: ~/.copilot/skills/ · Amp/cross-agent: ~/.agents/skills/)
# (Hermes Agent: ${HERMES_HOME:-$HOME/.hermes}/skills/<category>/)
# (OpenClaw: ${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/skills/; ~/.agents/skills/ only with default state)
# (OpenCode: ~/.agents/skills/ — it also reads ~/.config/opencode/skills/)

📥 All hosts, optional extractors, and the standalone CLI → docs/install.md

❓ FAQ

Common questions — "why not just dump the PDF?", cost, privacy, non-book inputs, multi-file books.

❓ Answers → docs/faq.md

🔧 Requirements

The extractor tries tools in order per format and uses the first available. If nothing is installed, it tells you which command to run. Plain text, Markdown, reStructuredText and AsciiDoc need no extra deps.

Check your setup in one command: python3 scripts/extract.py --check prints which extractors are installed for every format and the exact command to install anything missing — no file needed.

PDF — choose by book type:

Book type Tool Install Speed
Text-heavy (prose, few tables) pdftotext (poppler) sudo apt install poppler-utils ⚡ instant
Text-heavy fallback pypdf pip3 install pypdf ⚡ instant
Text-heavy fallback pdfminer.six pip3 install pdfminer.six ⚡ instant
Technical (code, tables, formulas) docling pip3 install docling ~1.5s/page

Before extraction begins, the skill asks you whether the book is technical or text-heavy and picks the right tool automatically. Docling preserves markdown tables and code blocks; pdftotext is faster for prose-only books.

Scanned PDFs need OCR first. A PDF that is page images with no text layer — a photographed or scanned book — has nothing for these tools to extract. The extractor checks the first pages and stops immediately with an explanation, rather than working through the whole book to produce an empty skill. Run OCR yourself, then convert the result:

ocrmypdf input.pdf output.pdf

EPUB:

Tool Install Quality
ebooklib + beautifulsoup4 pip3 install ebooklib beautifulsoup4 ⭐⭐⭐ Best
stdlib zipfile built-in — no install needed ⭐⭐ Always available

Other formats:

Format Tool Install
DOCX python-docx (fallback: stdlib ZIP/XML) pip3 install python-docx
HTML beautifulsoup4 (fallback: stdlib html.parser) pip3 install beautifulsoup4
RTF striprtf (fallback: regex) pip3 install striprtf
MOBI / AZW / AZW3 Calibre ebook-convert (external app, not pip) https://calibre-ebook.com/download
TXT / Markdown / reStructuredText / AsciiDoc built-in —
📁 Repository structure 
book-to-skill/
├── SKILL.md              # Skill definition + step-by-step instructions (the generator spec)
├── scripts/
│   ├── extract.py        # Thin entrypoint wrapper
│   └── extractor/        # Modular extraction package
│       ├── config.py     # Extensions, paths, dependency constants
│       ├── dependencies.py  # optional-dep probing + --check
│       ├── exceptions.py # ExtractionError (per-source failures, batch-safe)
│       ├── utils.py      # CLI parsing, multi-source resolution, chapter detection, runner
│       └── parsers/      # Format-specific parsers (pdf, epub, docx, html, rtf, calibre, text)
├── tools/
│   ├── discovery_tax.py  # measures token cost vs context-dump / discovery loop
│   └── validate_skill.py # checks a generated SKILL.md against host rules (--lens claude|copilot|amp|hermes|opencode)
├── tests/                # pytest suite (extraction, detection, discovery tax)
├── docs/
│   ├── performance.md    # measured benchmarks, discovery tax, cost
│   └── architecture.md   # pipeline + component map
├── CHANGELOG.md          # release history (semver)
├── CONTRIBUTING.md       # dev setup, PR conventions, release process
├── SECURITY.md           # vulnerability reporting
└── README.md             # This file

book-to-skill ships no book content — not a single page. It's a converter you point at files you already own.

When in doubt, follow the license or terms of the source document. This project is a tool; how you use it is on you.

💖 Sponsors

Booklin celebrating

book-to-skill is free and MIT-licensed, maintained on personal time. If it saves you tokens or study hours, consider sponsoring its upkeep: PR reviews, multilingual fixes, releases, and docs.

Become a sponsor → github.com/sponsors/virgiliojr94

Every sponsor is listed in BACKERS.md. Thank you for keeping open, privacy-first tooling alive. ✨

License

MIT — applies to the converter (code + skill definition) in this repository, not to any book or document you process with it.

book-to-skill (virgiliojr94/book-to-skill)

Searching Database…

35.1K ·GitHub
Book-to-skill
Что это такое?book-to-skill превращает PDF-файл технической книги (или папку/glob с документами) в структурированный «скилл», то есть набор файлов, который такие агенты, как Claude Code, GitHub Copilot CLI, Amp или Hermes Agent, могут подгружать по необходимости, чтобы отвечать на вопросы по реальному содержанию, а не выдумывать ответы.
Это конвертер или готовое приложение?Это инструмент из двух частей: детерминированный экстрактор на Python, который извлекает чистый текст из исходных файлов, и генератор по спецификации, который запускает ваш агент, чтобы превратить этот текст в скилл на основе SKILL.md. Отдельного графического интерфейса или сервера нет.
Как превратить книгу в скилл?Укажите слеш-команде /book-to-skill файл, папку или glob внутри поддерживаемого агента, например /book-to-skill ./my-book.pdf. Результат (SKILL.md и файлы по главам) появится в каталоге скиллов этого агента, после чего вы обращаетесь к нему командой /your-book-slug.
Что нужно установить, чтобы извлекать текст из PDF?Нужен Python 3. Для PDF используются pdftotext (poppler), pypdf, pdfminer.six или docling, в зависимости от того, текстовая книга или техническая, а также похожие инструменты для форматов EPUB, DOCX, HTML и RTF. Команда python3 scripts/extract.py --check покажет, чего не хватает, и точную команду для установки.
Работает ли это со сканами PDF?Нет. Скан, который состоит только из изображений страниц без текстового слоя, содержит нечего извлекать, поэтому инструмент сразу останавливается и объясняет причину, не создавая пустой скилл. Сначала текст нужно распознать самостоятельно (OCR).
Загружается ли содержимое моей книги куда-нибудь?Нет: извлечение и анализ выполняются локально на вашем компьютере, и инструмент никогда не загружает ваши файлы. Если модель, на которой работает ваш агент, облачная, то только текст, который вы ей передаёте, подпадает под обычные условия этого провайдера, как и любой промпт.
Можно ли поделиться готовым скиллом по книге, которую я купил?Лицензия MIT распространяется только на код конвертера, но не на книги, которые вы обрабатываете. Распространение сгенерированного скилла по защищённой авторским правом книге стороннего автора может нарушать права правообладателя, поэтому такие скиллы лучше хранить в закрытом доступе.
Что ещё, кроме книг, можно превратить в скилл?Помимо книг, инструмент работает с внутренней документацией: руководствами по эксплуатации (runbook), ADR, PDF с правилами бренда и дизайна, подборками научных статей, спецификациями и RFC. Словом, с любым материалом, который вы перечитываете так часто, что хочется запомнить его наизусть.
Насколько скилл экономит токены по сравнению с тем, чтобы загрузить PDF целиком в контекст?По замерам на реальных книгах запрос к готовому скиллу расходует в 24–51 раз меньше токенов, чем загрузка всей книги в контекст для одного вопроса, поскольку файлы глав подгружаются только по необходимости.
Можно ли обновить скилл после добавления новых глав или источников?Да, есть режимы обновления и дополнения: они вливают новый материал в существующий скилл, а не генерируют его заново с нуля.
Какие агенты действительно могут запустить сгенерированный скилл?Любой хост, который реализует открытый стандарт Agent Skills. Сейчас это GitHub Copilot CLI, Amp, Claude Code и Hermes Agent, так как все они читают один и тот же формат SKILL.md.
What are similar projects?docling, marker, qiaomu-anything-to-notebooklm, ai-aug-edu, OpenKB, patent-disclosure-skill, chubbyskills, SenseNova-Skills
Which topics is it in?docx, epub, knowledge-management, context-engineering, document-processing, knowledge-base, pdf, rag, html, markdown, agent-skills, claude-code
Creator
virgiliojr94
Size
2.7 MB
Stars
35.1K
Updated
CommitOct 12Releasev1.4.0Aug 10
Age
5mo
Commits · 90 Days