book-to-skill

What It Does

book-to-skill is a Claude Code and Amp skill that converts technical books, documents, and collections of files into structured agent skills. Given a PDF, EPUB, DOCX, or other supported file, it extracts text via a bundled Python pipeline, then walks the agent through a 10-step process to generate chapter summaries, a glossary, a patterns file, a cheatsheet, and a master SKILL.md with a topic index for on-demand loading. It targets developers who read technical books and want the knowledge available as queryable agent skills rather than raw PDFs sitting in a folder.

The Good

Real extraction tooling with format-aware routing. The scripts/extractor/ package contains 8 format-specific parsers (PDF, EPUB, DOCX, HTML, RTF, Calibre, text) plus dependency management and CLI argument parsing. PDF extraction routes through Docling for technical content (preserving tables and code blocks) and pdftotext for prose, with automatic fallback through PyPDF2 and pdfminer.six. EPUB extraction tries ebooklib first, then falls back to stdlib zipfile with OPF-relative href resolution. This is not a stub: it is production-quality Python that handles real-world documents.

38 passing tests across 8 test classes. The test suite covers EPUB tuple-unpack regression, batch resilience (ExtractionError instead of sys.exit on bad files), input order preservation, glob filtering, OEBPS-layout EPUB handling, DOCX zipfile fallback, and argument parsing edge cases. Tests run in 0.08 seconds with zero external dependencies. CI runs the suite across Python 3.10 through 3.13.

Four operational modes with clear routing. The SKILL.md defines Full Conversion (default), Analyze Only, Generate from Prior Analysis, and Update/Fold-in. Each mode has explicit trigger conditions and tells the agent exactly which steps to run or skip. The Update/Fold-in mode handles incremental knowledge building: add new papers to an existing skill and the workflow merges glossaries, appends chapter files, and rebuilds the topic index.

Token-conscious design throughout. The 566-line SKILL.md includes a dedicated section (Step 2.6) on REPL-style access for large books, advising the agent to use grep and sed to pull specific chapter slices instead of loading the full extracted text into context. Token budgets are specified per output file: 800-1,200 for chapter summaries, 1,500 for glossary, 2,000 for patterns, 1,000 for cheatsheet, 4,000 for the master SKILL.md. A pre-flight cost estimate (Step 2.5) shows the user token counts and dollar costs before any generation begins.

Cross-agent compatibility. The skill searches for its helper scripts across four skill directories (Claude Code, Amp project-local, Amp global, Amp legacy) and generates output to whichever the user chooses. The SKILL.md frontmatter includes both allowed-tools (Claude Code) and argument-hint (Amp). The bundled validator (tools/validate_skill.py) explicitly flags cross-agent metadata as WARN rather than ERROR, acknowledging intentional multi-platform design.

The Bad

Generation cost scales with book size, not skill size. The extractor pipeline handles text extraction efficiently, but Steps 3-9 (structure analysis, chapter summarization, glossary extraction, skill generation) all happen inside the agent's context window. A 400-page technical book produces roughly 200K tokens of extracted text. Even with the REPL-style grep/sed approach for individual chapters, the initial structure analysis pass reads the first 8,000 characters and the full chapter list. Users processing large books should expect significant token spend on the generation side.

Single commit, no tagged releases. The entire repo history is one commit from June 4, 2026. There are no version tags, no changelog, and no release artifacts. While the code quality is high for a v1, the lack of release history makes it hard to track what changed between iterations. The README extraction benchmark (103-page technical book, pdftotext 0.1s vs Docling 164s) is a strong quality signal, but the benchmark data could become stale as Docling evolves.

SKILL.md at 566 lines exceeds the 500-line soft guideline. The bundled validator flags this as a WARN. The length is justified by the four operational modes, each with distinct step routing, plus the update/fold-in workflow and quality rules. But agents with aggressive compaction settings may truncate the later sections (Update/Fold-in, Quality Rules), which are precisely the sections that differentiate this skill from a simpler conversion pipeline.

Smoke Test Results

All smoke tests run on macOS (host) against a shallow clone of the repo.

Run A. Extractor with zero optional deps (plain text and markdown)

$ cd /tmp/book-to-skill && pytest tests/ -q
......................................
38 passed in 0.08s
✅ PASS

$ printf '# Test Book\n\nChapter 1\nFramework content.\n\nChapter 2\nPrinciples here.\n' > /tmp/sample.md
$ BOOK_SKILL_WORKDIR=/tmp/work python3 scripts/extract.py /tmp/sample.md --mode text --install-missing no
Extraction complete:
 Sources : 1 processed
 Chapters: 2 detected overall
✅ PASS

$ cat /tmp/work/metadata.json | grep estimated_tokens
 "estimated_tokens": 32,
✅ PASS (token estimation works)

Pass rate: 3 of 3. All zero-dep operations work out of the box.

Run B. Multi-source consolidation

$ printf 'Source alpha.\n\nChapter 1 Alpha.\n' > /tmp/s1.txt
$ printf 'Source beta.\n\nChapter 1 Beta.\n' > /tmp/s2.txt
$ BOOK_SKILL_WORKDIR=/tmp/work2 python3 scripts/extract.py /tmp/s1.txt /tmp/s2.txt --mode text --install-missing no
Extraction complete:
 Sources : 2 processed
 Chapters: 2 detected overall
✅ PASS

$ grep "total_sources" /tmp/work2/metadata.json
 "total_sources": 2,
✅ PASS (multi-source merge works)

$ grep "SOURCE:" /tmp/work2/full_text.txt | wc -l
2
✅ PASS (source boundaries present)

Pass rate: 3 of 3. Multi-source consolidation produces correctly delimited output with per-source metadata.

Run C. Validator and CI checks

$ python3 tools/validate_skill.py SKILL.md
 WARN allowed-tools: ['shell_command'] are not Claude Code tool names
 WARN frontmatter 'compatibility': not a recognized Claude Code key
 WARN frontmatter 'argument-hint': not a recognized Claude Code key
 WARN body: 566 lines > 500 (soft guideline)
✓ SKILL.md: no Claude-breaking issues (4 warning(s))
✅ PASS (validator runs, all warnings are intentional cross-agent metadata)

$ grep -c "def test" tests/test_extractor.py
26
✅ PASS (26 test methods across 8 test classes)

Functional pass rate: 2 of 2. The validator confirms no Claude-breaking issues. The test count confirms substantial coverage.

What the runs tell you

The extraction pipeline works reliably without optional dependencies for text and markdown inputs. Multi-source consolidation produces correctly structured output with source boundaries. The validator confirms the SKILL.md is Claude Code compatible. The parts that could not be tested (PDF extraction with Docling, EPUB with ebooklib, full skill generation from Steps 3-9) require either optional Python packages or a live Claude Code session.

Setup Walkthrough

1. Clone the repo: git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
2. No pip install required. The extractor uses stdlib for text, markdown, HTML, and EPUB (zipfile fallback). PDF needs optional deps: pip3 install PyPDF2 for prose, pip3 install docling for technical content with tables.
3. In a Claude Code session, run /book-to-skill ~/path/to/book.pdf to start the full conversion pipeline.
4. The skill will ask whether the book is technical or text-heavy, present a cost estimate, and proceed through chapter-by-chapter generation.

Optional deps for best results: pip3 install PyPDF2 ebooklib beautifulsoup4 python-docx striprtf. Docling (pip3 install docling) is recommended for technical PDFs with code blocks and tables, though it adds significant install time and processes at ~1.5s per page.

Alternatives

1. teng-lin/notebooklm-py (15,863 stars) - NotebookLM access via Python. Better for multi-book search and Q&A. Does not generate agent skills or structured chapter summaries.
2. deusyu/translate-book (749 stars) - Claude Code skill for translating entire books. Focused on translation rather than knowledge extraction.
3. Raw PDF injection into Claude context - Free, but burns 200K+ tokens per conversation on a 400-page book. No structured retrieval, no on-demand loading, no framework extraction.