File: README.md Copy Chapter

book-to-skill

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 Copy Chapter

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, and Claude Code all read the same SKILL.md format.

📦 What it generates Copy Chapter

Running /book-to-skill your-book.pdf (or a folder, glob, or list of files) creates a full skill in your agent's skills directory (~/.copilot/skills/<slug>/ for Copilot CLI, ~/.agents/skills/<slug>/ for Amp or cross-agent, ~/.claude/skills/<slug>/ for Claude Code):

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

🏢 Beyond books Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

/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 Copy Chapter

# 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/)

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

❓ FAQ Copy Chapter

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:

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:

bash Copy

ocrmypdf input.pdf output.pdf

EPUB:

Other formats:

📁 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)
├── 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

⚖️ Copyright & fair use Copy Chapter

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

• Processing is local. Extraction and analysis run on your machine. Your files are never uploaded by this tool. (If your agent's model runs in the cloud, the text you feed it follows that provider's normal data terms — same as any prompt.)
• You use your own copy. Bring a book you bought, docs your company owns, or papers you have the right to read.
• The output is your notes. A generated skill is a structured, synthesized derivative — framework names, definitions, takeaways — not a reproduction of the text. The skill explicitly never copies raw passages (see Quality Rule #7). Treat it like handwritten study notes: yours, for personal use.
• Don't redistribute. Publishing or sharing a generated skill of a copyrighted work can infringe the rights holder. Keep skills of third-party books private. Internal docs, your own writing, and openly-licensed material are fine to share within the bounds of their license.

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 Copy Chapter

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 Copy Chapter

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

File: docs/ARCHITECTURE.md Copy Chapter

seo_title: "Architecture - How book-to-skill Extracts and Generates" Copy Chapter

Architecture

book-to-skill has two halves: a deterministic extractor (Python) and a
spec-driven generator (the agent following SKILL.md). The extractor turns any
document into clean text + metadata; the agent turns that into a structured skill.

/* Detailed source-code truncated for AI context efficiency. */

Design principles Copy Chapter

1. Extract structure, not summaries — named frameworks, decision rules,
   anti-patterns; never raw passages.
2. Compile-time over runtime — pay navigation/structuring once; at query time
   load only the relevant chapter. See Performance & Cost.
3. On-demand chapters — SKILL.md stays small; chapter files cost tokens only
   when read.
4. Front-loaded SKILL.md — most important content first (compaction truncates
   from the end).
5. Graceful degradation — every format has a stdlib fallback; one bad source is
   skipped, not fatal.

Key components Copy Chapter

Security Copy Chapter

Untrusted documents flow into an agent's context and then into a generated skill
that later loads into other agents — a document→context supply chain. The hardening
is layered:

• Extraction sanitization (book_to_skill/sanitize.py) — strips zero-width
  (U+200B/200C/200D/2060/FEFF) and the Unicode tag block (U+E0000–E007F) from
  every parser's output before metrics or full_text.txt, so invisible
  document-borne instructions never reach the agent. Reports the removal count;
  rejects a source with no visible content left.
• DOCX XXE / Billion-Laughs guard (parsers/docx.py) — rejects any XML part
  declaring a DTD or entities before parsing.
• Subprocess argument-injection — file paths are absolutised before reaching
  pdftotext / pdfinfo / ebook-convert, so a --leading filename can't be read
  as a flag.
• Generated-skill scan (tools/scan_generated_skill.py) — an advisory step in
  the generator (Step 9.5) that flags instruction-override phrases, model-control
  tags, residual invisible Unicode, authority-widening frontmatter, and
  exfiltration-shaped content across the generated SKILL.md, chapters/*.md,
  glossary.md, patterns.md, and cheatsheet.md. Findings name only the rule and
  file location — never the matched text.
• CI — CodeQL, Bandit (gate on HIGH), Zizmor, and dependency CVE review on PRs.

Extending Copy Chapter

• New format → add book_to_skill/parsers/<fmt>.py, register its extension in
  config.py, wire dependency probing in dependencies.py, branch in
  utils.extract_single_file.
• New generation behavior → edit the relevant Step in SKILL.md; keep it lean
  and back the change with evidence (see CONTRIBUTING.md).

File: docs/index.md Copy Chapter

seo_title: "book-to-skill - Turn Any Book Into an AI Agent Skill"
hide:

• navigation
• toc

book-to-skill

Turn any book or document into a structured, on-demand agent skill — named frameworks, decision rules, and anti-patterns. Structure, not a summary.

Get started{ .md-button .md-button--primary }
Skill reference{ .md-button }
GitHub{ .md-button }

Why book-to-skill Copy Chapter

• :material-file-document-multiple:{ .lg .middle } Multi-format

  ---

  PDF, EPUB, DOCX, HTML, Markdown, RTF, MOBI/AZW (via Calibre). Extraction runs
  locally with graceful stdlib fallbacks — no upload, no lock-in.

• :material-brain:{ .lg .middle } Structure, not summaries

  ---

  Named frameworks, mental models, decision rules, and anti-patterns — the
  author's toolkit, captured with their exact terms, not a book report.

• :material-flash:{ .lg .middle } On-demand chapters

  ---

  Per-chapter files load only when the topic is relevant, so a 200-page book
  costs tokens proportional to the question, not the page count.

• :material-robot-happy:{ .lg .middle } Multi-agent

  ---

  One SKILL.md runs on Claude Code, GitHub Copilot CLI, and Amp through the
  open Agent Skills standard.

Install Copy Chapter

As an agent skill (gives you the /book-to-skill command in Claude Code, Copilot CLI, Amp):

npx skills add virgiliojr94/book-to-skill
# or manually:
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# then, in your agent session:
/book-to-skill /path/to/book.pdf [skill-name]

As a standalone CLI (just the text extractor, optional):

# not on PyPI yet — pip takes it from the repository
pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git"
book-to-skill /path/to/book.pdf --mode text

Learn more Copy Chapter

• :material-sitemap:{ .lg .middle } Architecture

  ---

  How the deterministic extractor and the spec-driven generator fit together.

• :material-speedometer:{ .lg .middle } Performance

  ---

  The measured Discovery Loop Tax and real per-conversion token cost.

• :material-book-open-page-variant:{ .lg .middle } Skill Reference

  ---

  The full SKILL.md spec: every step, depth budget, and quality rule.

• :material-heart:{ .lg .middle } Sponsor

  ---

  book-to-skill is free and MIT. Sponsoring funds reviews, releases, and fixes.

File: docs/PERFORMANCE.md Copy Chapter

seo_title: "Performance & Token Cost - book-to-skill Benchmarks" Copy Chapter

Performance & Cost

All numbers below are measured, not estimated, using tiktoken (cl100k_base)
for token counts and tools/discovery_tax.py for the discovery model. Reproduce
any of them with the commands shown.

Extraction (real conversions) Copy Chapter

Measured with pdftotext (PDF) and ebooklib (EPUB):

† Pro Git heads chapters with section titles (no Chapter N), so it does not
auto-segment. Moby-Dick's bodies use bare titles, but its Roman-numeral table of
contents is detected (133) — see Known limitations in the README.

Extraction method matters for technical books. On a 103-page technical PDF:

pdftotext is instant but flattens structure; Docling is ~1.5s/page but preserves
tables and code as markdown. Pick text mode for prose, technical mode for code/tables.

The Discovery Loop Tax Copy Chapter

Tokens entering context to answer one targeted question. book-to-skill loads a
resident core (~4K) plus one compiled chapter (~1K) ≈ 5,000 tokens.

python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5

• The context-dump advantage (24–51×) is the strongest claim: that cost recurs on
  every conversation turn.
• The discovery-loop advantage (2.4–15.6×) is a one-time cost and a model using
  the book's real ToC/chapter sizes; it scales with chapter size.

Generation cost Copy Chapter

One-pass full conversion, estimated from measured tokens (Claude Sonnet 4.5,
$3 / $15 per MTok input/output):

Roughly $1 per book for a full skill — paid once. Re-reading the same PDF into
context every session costs far more over time (see the Discovery Loop Tax above).

Generated-skill output quality Copy Chapter

A before/after of the adaptive-depth change (v1.0.0, #20) on one chapter:

The new spec turns the cheatsheet from a glossary into a decision layer and gives
study-depth chapters a reproduced worked example.