Book-to-Skill Converter
Turn any technical book PDF, document folder, or source collection into a structured agent skill — 24–51× fewer tokens than dumping the book into context.
SKILL.md itself shows least-privilege and user-confirmation habits: destination roots are confirmed rather than silently defaulted, dependency installs default to 'ask', a cost estimate gates generation, processing is local with README/SECURITY explicitly ruling out uploads; no covert exfiltration signals. Deductions: the generated skill writes to several filesystem locations, overwrite paths could be mis-triggered, no explicit rollback/removal mechanism in SKILL.md, and allowed-tools is intentionally omitted so permissions depend on first-use host prompts.
Instructions are self-consistent with numbered steps and explicit failure paths (missing args, unsupported files, missing extract.py, scanned-PDF early abort); per-PID workdirs prevent concurrent clobbering. Deductions: static review cannot execute key paths, extract.py source is not in evidence, and the SKILL.md text is truncated mid-sentence in the cheatsheet section, leaving Step 9+ unverifiable against script behavior.
Trigger conditions are precise (four modes with explicit Triggers), input formats, output structure and non-fit ranges (scanned PDFs need OCR; books without explicit chapter headings do not auto-segment) are disclosed; multi-host environment fit is thorough including CJK token estimation and CJK/Thai/Korean ToC detection, plus a Simplified Chinese README. Deductions: technical mode depends on docling and other formats on pip/Calibre, which may be unreachable or slow from mainland-China networks, with no mirror guidance.
Docs are well layered (lean SKILL.md spec, README/FAQ/architecture split), MIT license is explicit, changelog is generated via git-cliff with semver, ownership and update paths are clear, and CI validates SKILL.md conformance. Deductions: AGENTS.md mandates leanness yet the file is long and truncated in this evidence, so full completeness and latest consistency cannot be confirmed; generated-artifact governance relies on runtime behavior not statically checkable.
The core path (extract → structure → on-demand chapter files) is well designed with argued marginal value (24×–51× token savings, Discovery Loop Tax) and transparent cost pre-flighting. Deductions: nothing executed, so generated-output quality (chapter fidelity, cheatsheet completeness) is unverifiable; the truncation hides Step 9/10 and quality rules; headline claims come from self-authored docs without representative outputs in evidence.
Strong primary material exists: CI workflows (pytest matrix, dependency-free smoke, bandit, CodeQL, dependency-review), a test suite, and reproducible-looking measurements in the changelog (Korean heading detection precision 0.999/recall 1.000, Gutenberg benchmark), plus a use-cases repo pattern. Deductions: static review cannot execute; the shown test file covers only eval manifests, not the generation key path; benchmark claims are self-reported, so the cap of 5 applies.
- Static review only; nothing was executed. SKILL.md is truncated mid-sentence in the cheatsheet section — Step 9 and later instructions are not visible, so runtime behavior may differ from the doc.
- Technical mode requires docling; several formats need pip packages or Calibre. Downloads may fail or be slow from mainland-China networks — preflight with extract.py --check and arrange mirrors yourself.
- Generated skills are written to multiple candidate directories and existing skills may be overwritten; verify the target path, and removal/rollback is manual.
- Keep skills generated from copyrighted books private; do not redistribute them. The project itself ships no book content.
What does this skill do, and when should you use it?
book-to-skill is an open-source (MIT) agent skill that converts books and documents — PDF, EPUB, DOCX, HTML, Markdown, RTF, and MOBI/AZW — into structured agent skills. Rather than producing summaries, it extracts the author's named frameworks, principles, techniques, anti-patterns, and mental models into on-demand per-chapter files. The output works in any host that reads the Agent Skills standard, including GitHub Copilot CLI, Amp, Claude Code, and Hermes Agent. All processing runs locally and the tool ships no book content itself.
Once installed, run /book-to-skill <path-or-glob> [skill-name] in a supported agent. The workflow: it asks whether the source is technical or text-heavy; runs scripts/extract.py to pull text (Docling for technical PDFs, preserving tables and code blocks at ~1.5s/page; pdftotext/pypdf/pdfminer for prose, instant), then presents a token-cost estimate; analyzes title, author, and chapter structure; generates per-chapter summary files (frameworks, code examples, reference tables, decision points) plus glossary.md, patterns.md, cheatsheet.md, and a master SKILL.md (~4,000 tokens); writes everything to ~/.copilot/skills/, ~/.agents/skills/, or ~/.claude/skills/; then runs a security scan and cleans up its temp work directory. It can also fold new material into an existing skill (Update/Fold-in) and optionally publish to GitHub via the gh CLI.
- An engineer who bought Pro Git or Think Python wants chapter-accurate answers while coding, without digging through the PDF
- A team folds a folder of internal architecture decision records, runbooks, or onboarding docs into one queryable skill
- A brand or design system guide becomes a skill the team can ask questions of instead of skimming a 60-page PDF
- A researcher merges a stack of papers plus personal notes into one unified skill, updated incrementally as new material arrives
- A practitioner who repeatedly applies a book's methodology (influence frameworks, systems thinking) wants the agent to invoke them as 'Use X when Y' rules
What are this skill's strengths and limitations?
- Measured 24–51× fewer tokens than a context dump and 2.4–15.6× fewer than a discovery loop (reproducible via tools/discovery_tax.py)
- Extracts structure, not summaries: named frameworks, decision rules, and anti-patterns grounded in your actual copy, not training data
- Chapters load on demand — resident cost is ~5,000 tokens; a full conversion costs roughly $1 per book
- Cross-host: one SKILL.md works across Copilot CLI, Amp, Claude Code, and Hermes Agent via the open standard
- Local processing, no book content shipped; supports incremental Update/Fold-in; MIT licensed
- Chapter auto-detection requires explicit 'Chapter N' / 'Capítulo N' headings; books using section titles or roman numerals (Pro Git, Moby-Dick) won't auto-segment
- Docling extraction for technical PDFs is slow (~1.5s/page), so long books take minutes
- Benchmarks cover only three books and one model's pricing; real-world costs for other books and models are unverified
- Skills generated from third-party copyrighted books must stay private — public redistribution is off the table per the README's copyright policy
- EPUB images are not read (counted and dropped); MOBI support depends on externally installed Calibre, not pip
How do you install this skill?
Install as an agent skill (gives you the /book-to-skill command):
- GitHub Copilot CLI: git clone https://github.com/virgilijr94/book-to-skill.git ~/.copilot/skills/book-to-skill (correct URL: https://github.com/virgiliojr94/book-to-skill.git), then run /skills reload in a session
- Cross-agent path (found by Copilot CLI and Amp): clone into ~/.agents/skills/book-to-skill
- Claude Code: clone into ~/.claude/skills/book-to-skill, or paste the install prompt from the README into a session
Plain text/Markdown/reStructuredText/AsciiDoc need no extra deps; run python3 scripts/extract.py --check to see which optional extractors to install for PDF, EPUB, DOCX, RTF, etc.
How do you use this skill?
In an agent session: /book-to-skill ~/books/my-book.pdf (folders, globs, and multi-file lists also work; an optional trailing slug names the skill). Once generated, use it like any skill: /your-book-skill loads core frameworks; /your-book-skill replication finds and explains a topic; /your-book-skill ch05 dives into a chapter; /your-book-skill "what chapters do you have?" lists the index. In Copilot CLI you may need /skills reload before the new skill appears; Claude Code and Amp pick it up on the next session.
How does this skill compare with similar options?
The README positions book-to-skill against: dumping the PDF into context (recurs every turn regardless of window size); RAG tools like CandleKeep (wide-and-shallow retrieval across many books); and NotebookLM (searching across a large library). book-to-skill targets the narrow-and-deep case — mastering one book or a tight cluster of sources — and is complementary to RAG, not competing.