How to Turn PDF or EPUB Into Agent Skill
Turn PDF, EPUB, DOCX or internal docs into an on-demand agent skill. See install steps, token budget, headless runs, chapter indexing and licensing.
How to turn technical book into agent skill: wetin you go get
To turn technical book into agent skill, point converter to PDF, EPUB, DOCX export, or folder wey contain internal documents wey you already get. E go write skill directory: one entry file wey hold the named frameworks plus chapter index, and one file for each chapter wey agent go read only when your question need am. The book no go enter context window. The index go enter.
This work different from writing agent skill from scratch, where you encode procedure wey you already know. For here, the knowledge dey but nobody fit reach am: 800-page vendor PDF, or handbook wey nobody don open since the person wey write am comot. The work na compression and indexing. If the word skill new to you, first read wetin agent skill actually be.
The converter wey we use here na book-to-skill, an MIT-licensed skill wey dey run for your own machine. The current tag as of October 2026 na v1.4.0. The structure wey e produce matter pass the tool itself, and the last section before FAQ show how to build the same structure by hand.
Why token budget dey drive the whole design
A book wey you paste inside context window go cost its full size for every conversation wey need am. Skill go cost its entry file one time, plus any chapter wey the question actually touch. The project documents budget for each file wey e generate.
Di data wey dey behind dis chart
[
{
"label": "SKILL.md entry file",
"tokens": "4,000"
},
{
"label": "One chapter file",
"tokens": "1,000"
},
{
"label": "glossary.md",
"tokens": "1,500"
},
{
"label": "patterns.md",
"tokens": "2,000"
},
{
"label": "cheatsheet.md",
"tokens": "1,000"
}
]The entry file, SKILL.md, get limit of 4,000 tokens, and e carry the named frameworks plus chapter index. Each chapter file dey around 1,000 tokens, and e dey disk until something ask for am. The supporting files dey similar: 1,500 tokens for glossary.md, 2,000 for patterns.md, and 1,000 for cheatsheet.md.
These budgets match how Claude Code dey use context. A skill's description dey inside skill listing, so the model know say the skill dey exist. The body go load when dem invoke the skill, and once e load, e remain inside context for the rest of the session. So every line for the entry file na recurring cost. Supporting files go load only when the agent read dem, and na this one make separate chapter files cheap.
There dey one harder limit behind that entry-file number. When auto-compaction summarise long conversation, Claude Code go attach the most recent invocation of each skill again after the summary. E go keep the first 5,000 tokens of each, inside combined budget of 25,000 tokens across every skill wey e attach again. Entry file wey fit inside 5,000 tokens go survive compaction complete. Entry file wey get 20,000 tokens go come back as the first quarter, and nothing go tell you which three quarters disappear.
Na progressive disclosure be this: small index wey always worth the cost, while the main material dey behind door wey the agent go open only when e decide to. How Claude Code dey manage im context window cover the rest of that accounting.
Install the converter for your VPS, lock am for one release
The skill na git repository. Clone am go the skills directory of the agent wey you dey use. The directory name go become the slash command, so the clone path no be matter of personal choice.
git clone --depth 1 --branch v1.4.0 \
https://github.com/virgiliojr94/book-to-skill.git \
~/.claude/skills/book-to-skill--branch dey accept tag, so this one go checkout v1.4.0 and nothing wey come later. Lock am because skill na set of instructions wey your agent dey follow, and any change wey you no review for those instructions na change to wetin go run for your server. GitHub Copilot CLI dey read ~/.copilot/skills/ instead, and Amp dey read ~/.agents/skills/.
One-line install dey too, npx skills add virgiliojr94/book-to-skill, wey dey fetch anything wey current. Use am test the tool. Use the pinned clone for anything wey you go run again.
Now confirm which extractors dey for the box:
cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check--check dey report which extractors dey installed and e dey print wetin you need install for anything wey dey missing: one combined pip command for the missing Python packages, plus hint for each missing system tool. The package need Python 3.9 or newer.
If /book-to-skill no show for autocomplete after cloning, run /reload-skills or restart your agent. Claude Code dey watch the skill directories wey exist when the session start, so any ~/.claude/skills/ wey you create two minutes ago never dey watched yet.
Which extractors you really need?
Nothing dey required apart from Python, because every format get fallback for standard library. The fallbacks no good reach, and for small server, na time dey waste when you install extractors wey you no go use.
pdftotext, frompoppler-utilspackage, dey handle PDFs wey mostly get text, and e dey almost instant. Install am withsudo apt install poppler-utils.pypdfandpdfminer.sixna the Python fallbacks for PDF.doclingna for technical PDFs wey their main value dey inside tables and code listings. The project measure am at about 1.5 seconds per page.ebooklibwithbeautifulsoup4dey read EPUB well. Without dem, the tool go fall back to the stdlibzipfilereader.python-docxdey read DOCX, whilestriprtfdey read RTF.- You need Calibre
ebook-convertfor MOBI and AZW files. ocrmypdfdey run OCR (optical character recognition) over scanned book wey no get text layer at all.
For Ubuntu 24.04, plain pip3 install pypdf go stop with this:
error: externally-managed-environmentThis one no mean say pip don break. Ubuntu and Debian mark system Python as managed by apt, so pip no go write inside am. Two solutions dey work. sudo apt install poppler-utils dey install binary and e no need pip at all, while pdftotext fit handle most prose PDFs by itself. For the Python extractors, build virtual environment and start your agent from inside am. This one make the python3 wey the skill call be the interpreter wey get the packages.
python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claudeThe pinned v1.4.0 checkout declare the extras pdf, epub, docx, rtf, technical and all, where technical na docling. The project install page still document standalone command-line install directly from GitHub, pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git", followed by book-to-skill --check to list the extractors wey dem install. This one no need PyPI release, but e install the project's default branch instead of v1.4.0, and e give you only the extractor command, no be the /book-to-skill skill. For pinned setup, install from your own checkout as described above. Plain pip install book-to-skill no go work, because that name no dey published for PyPI as of October 2026.
Leave docling out until book need am. E dey pull machine learning stack, so check free disk for small plan before you install am.
Run am over folder of documents, including headless
The command fit take one file, one folder, one quoted glob, or several paths at once, followed by optional skill name. Anything wey fit dey inside one directory go work, including an RFC set (request for comments, the documents wey define internet protocols).
/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-researchQuote the glob so your shell no expand am before the skill see am. If you point the command to skill directory wey already exist, e go add the new sources to that skill instead of creating another one.
Interactive run go ask you questions. Whether the material technical or text-heavy go decide the extractor. Wetin you want the skill help you do go set reference or study depth, plus the per-chapter budget. E go ask wetin the skill name suppose be, and, when skills root no dey yet or more than one dey, which root e suppose use. E also go show token and time estimate before generation, then wait for your confirmation.
Headless run no get person to answer those questions. User-invocable skills dey work for claude -p: put the slash command inside the prompt string, and Claude Code go expand am before the run start. So answer the questions inside the same prompt.
claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
--allowedTools "Bash,Read,Write,Edit"--allowedTools pre-approves the tools wey the run need, because permission prompt wey no get terminal attached na run wey no go ever finish. If you add --output-format json, e go put total_cost_usd inside the result. This one na client-side estimate, no be your bill.
Extraction go consolidate every source into temporary work directory under /tmp before any model read am, and the last step of the run go delete that directory. If source fail to extract, e go skip am so the batch fit continue. This means run fit report success even though e read fewer files than the ones you supply. Compare the file inventory for the final report with wetin dey inside the folder. If chapter dey missing, source dey missing most times.
Give the run server wey you trust to hand over to an agent. How to run Claude Code safely on a VPS explain the permission side of this.
Wia output dey go so your coding agent fit find am
The generated skill dey enter a skills root. Two of dem matter.
~/.claude/skills/<skill-name>/na personal one, and e dey available for every project for that machine..claude/skills/<skill-name>/dey inside repository and e dey move together with am.
Inside any of dem, you go get SKILL.md, a chapters/ directory wey get one file for each chapter, plus the supporting files. The directory name na the command, so ~/.claude/skills/platform-handbook/ go give you /platform-handbook, and you fit follow am with topic or plain question.
Choose the root based on licensing, no be convenience. Skill wey you build from book wey you buy belong for your personal directory. Skill wey you build from documentation wey your own team write belong for the repository. That one turn sharing one skill across several repositories into the next problem to solve.
One cost dey increase every time you add skill. Description for each skill dey remain inside skill listing so the model fit decide whether to use am. The combined description text dey truncate to 1,536 characters per entry, and the whole listing get budget. Ten book skills mean say ten descriptions dey compete for the budget. For the ones wey you always call by name, add one line to the generated frontmatter:
---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---With disable-model-invocation: true, the description no dey enter context at all, and the skill still loads complete when you type /platform-handbook. You lose automatic discovery, but your context window go quieter.
Licensing: MIT dey cover converter, no be book
Make this point clear, because the problem no be technical one.
- MIT license dey cover converter code and the skill definition. E no talk anything about the document wey you give am.
- If you run converter over book wey you buy, for hardware wey you control, na you dey make notes from your own copy.
- Publishing the result na distribution, and MIT license for the tool no give you any right to distribute anything wey come from another person book.
- The output na derivative work. Frameworks and chapter takeaways still dey shaped by the source, and source copyright still govern derivative work.
- If you build skill from material wey you no fit redistribute, e suppose remain for the machine wey build am. No be public repository. No be shared team marketplace.
- Publish only when the source na your own or e get open license: documentation wey your team write, or standard wey terms allow redistribution.
Dem build the tool around this rule. E no ship any book content, and extraction dey run locally. The pinned v1.4.0 only prints optional gh skill publish line and e never ask about visibility, so na you alone get the final decision there. The project's default branch don later add publish step wey asks repository visibility as separate one-word question, and e go create public repository only when the reply na the bare word public; anything else go remain private. Treat that step as the licensing decision, because na exactly wetin e be.
Internal handbooks get another problem. Dem dey contain credentials more often than people admit, and converter fit turn PDF wey nobody dey open into file wey your agent reads whenever e need am. Read the generated files once before you commit dem, and see how to keep secrets away from your AI agents.
Wetin be the cost for one conversion?
The figures below na the project own published measurements, no be our own measurements.
Di data wey dey behind dis chart
[
{
"label": "Think Python 2",
"cost_usd": 0.88
},
{
"label": "Working Backwards",
"cost_usd": 0.96
},
{
"label": "Pro Git",
"cost_usd": 1.23
},
{
"label": "Moby-Dick",
"cost_usd": 1.42
}
]For the 4 books wey the project measure, one conversion cost between 0.88 and 1.42 US dollars, while Pro Git cost 1.23. Dem measure the figures for Claude Sonnet 4.5, using token counts from tiktoken with cl100k_base, and dem publish am for the project docs/performance.md as of October 2026. Your own figure go change based on your model and your prices.
The project still document say e take 24 to 51 times fewer tokens to answer one question from the skill than to answer am from the whole book pasted into context. Understand this as the general shape of the saving, no be promise, because e depend on the book and the question. The main point remain the same either way: you pay for conversion once, but you pay for context dump again for every conversation wey need the book.
Why you no go paste the PDF or build RAG index?
Pasting dey work, and na the correct answer for one question about one document. E stop to be the correct answer when you need the same book on Tuesday and again on Friday, because you go pay for the full size every time.
Retrieval, or RAG (retrieval augmented generation), dey search when you ask question and return the passages wey match your words. E strong when you need the exact sentence. E weak when the useful thing na framework wey spread across one chapter, because no single passage contain am. Skill dey do this extraction once, during conversion, and store the structure instead of the passages.
The honest limit be say: na model dey write generated skill as lossy summary. E be study aid, and the source still be the source. When exact wording get legal or protocol importance, keep the PDF and quote from am. Skills wey dem compare with MCP servers and rules files cover where each approach fit belong.
Wetin fit fail, and the strings wey you go see
Scanned PDF no produce anything. The extractor dey check the opening pages for text layer and e go stop with explanation instead of struggling through 400 pages of images. Run ocrmypdf input.pdf output.pdf first, then give am the output file.
pip no gree install. error: externally-managed-environment for Ubuntu 24.04 na apt dey protect system Python. Use the virtual environment wey dey above, or install poppler-utils and no use pip at all.
The chapters dey come out wrong. Chapter detection dey look for clear headings like Chapter 7 and the language variants, and e also dey recognise roman numerals like Chapter IV or IV. Title. Book wey use plain section titles without numbers fit split badly. To fix am, tell the run where the chapters start instead of hoping say e go guess correctly.
The command no exist. If /book-to-skill no dey show for autocomplete, e mean say skills directory na after your session start dem create am. Run /reload-skills, or restart the agent.
Docling dey take too long. For about 1.5 seconds per page, long book fit use minutes of CPU time. For shared server, the run go compete with every other service wey you dey host. Answer "text-heavy" when the run ask about content type, or pass --mode text when you dey run scripts/extract.py yourself. --mode technical na the answer wey select docling.
A source disappear without noise. If file no fit read, the process go skip am so batch fit finish. The run go then report success for fewer sources than the ones wey you give am. The only place wey show this na file inventory for final report. This habit of checking completed run against wetin you really give am dey useful beyond this tool. The unlazy skill's Depth Tree method na one way to make agent hold itself to the same standard instead of declaring the work done too early.
Apply the same pattern by hand
This tool na just convenience. Na the structure wey you fit reuse, and text editor fit build am for any reference material wey belong to you.
- Write one entry file and keep am near 4,000 tokens wey the converter dey target. Put the named concepts inside am with their exact formulations, plus one index wey list every detail file and the topics wey each file contain.
- Split the material into files of about 1,000 tokens, one topic per file. Name dem so the filename alone go tell you wetin dey inside.
- Describe each of those files from the entry file, for the sentence wey explain when to read am.
Step 3 na the part wey people dey skip, and na am make the pattern work. The agent dey choose wetin to open by reading the index, so if the index no describe a file, the agent no go ever open am. The index na the product, while the chapter files na storage.
Keep the entry file inside the compaction budget, and the whole structure go survive long session. This rule still apply whether converter write the files or na you write dem.
FAQ
I fit publish skill wey I build from book wey I buy?
No, unless license for that book allow redistribution. MIT license for converter cover converter code, e no cover material wey you feed am, and generated skill na derivative work of the book. Keep am for ~/.claude/skills/ for your own machine. You fit publish documentation wey you write yourself or openly licensed sources. The pinned v1.4.0 no ever ask about visibility, but project's default branch now ask am as im own question and e go public only for bare public, so either way, na decision wey you make deliberately.
I need docling, or pdftotext enough?
pdftotext from poppler-utils enough for prose and e nearly instant. Install docling when main value of the book dey inside tables and code listings, because plain text extractor dey drop exactly those ones. The trade-off na speed: project measure docling at roughly 1.5 seconds per page, so 300-page manual fit take several minutes of CPU time for VPS.
Why pip dey fail with externally-managed-environment for my VPS?
Ubuntu 24.04 and current Debian mark system Python as managed by apt, so pip refuse install inside am and e print error: externally-managed-environment. Create virtual environment with python3 -m venv ~/.venvs/book-to-skill, activate am, install extractors inside there, then start your agent from that same shell. The skill dey call python3, so e use whichever interpreter dey for your PATH, wey now na the one inside virtual environment.
Why my generated skill no dey show as slash command?
Two causes dey. Command name dey come from directory name, so skill must dey for ~/.claude/skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.md, with SKILL.md spelled exactly that way. If path correct, run /reload-skills or restart the agent. Claude Code dey pick edits inside skill directories wey e already dey watch, but e no dey watch skills directory wey you create after session start until you do am.