How to Turn PDF or EPUB Into Agent Skill

Wetin you go get when you turn technical book into agent skill

To turn technical book into agent skill, you point converter to PDF, EPUB, DOCX export, or folder of internal documents wey you already own. 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 dey enter context window. Na the index dey enter.

This na opposite work from writing agent skill from scratch, where you encode procedure wey you already know. Here, the knowledge dey exist but nobody fit reach am: 800-page vendor PDF, or handbook wey nobody don open since the person wey write am leave. The work na compression and indexing. If the word skill new to you, read wetin agent skill really be first.

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 August 2026 na v1.4.0. The structure wey e produce matter pass the tool itself, and the last section before the 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.

[
  {
    "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, pin am release

The skill na git repository. Clone am enter the skills directory of the agent wey you dey use. The directory name become the slash command, so the clone path no be matter of taste.

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 checks out v1.4.0 and nothing wey come later. Pin am, because skill na set of instructions wey your agent dey follow, and any unreviewed change to 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/.

Another one-line install dey, npx skills add virgiliojr94/book-to-skill, wey go fetch anything wey current. Use am test the tool. Use the pinned clone for anything wey you go run again.

Now confirm which extractors the box get:

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check dey report which extractors dey installed and e dey print the install command for each one wey no dey. The package need Python 3.9 or newer.

If /book-to-skill no show for autocomplete after cloning, restart your agent. Claude Code dey watch the skill directories wey exist when the session start, so e no dey watch ~/.claude/skills/ wey you create two minutes ago 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, the time wey waste na to install extractors wey you no need.

• pdftotext, from poppler-utils package, dey handle PDFs wey get plenty text and e dey almost instant. Install am with sudo apt install poppler-utils.
• pypdf and pdfminer.six na the Python fallbacks for PDF.
• docling na for technical PDFs wey their main value dey inside tables and code listings. The project measure am at about 1.5 seconds per page.
• ebooklib with beautifulsoup4 dey read EPUB well. Without dem, the tool go fall back to the stdlib zipfile reader.
• python-docx dey read DOCX and striprtf dey read RTF.
• Calibre ebook-convert dey required for MOBI and AZW files.
• ocrmypdf dey run OCR (optical character recognition) on scanned book wey no get text layer at all.

For Ubuntu 24.04, plain pip3 install pypdf go stop with this:

error: externally-managed-environment

This no mean say pip don spoil. Ubuntu and Debian mark system Python as managed by apt, so pip no gree write inside am. Two answers 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, so the python3 wey the skill call na 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]"
claude

The repository declare the extras pdf, epub, docx, rtf, technical and all, where technical na docling. The project install page still show pip install "book-to-skill[pdf,epub,docx]", but that name no dey published for PyPI as of August 2026, so install from your own checkout as shown above.

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 for folder wey get documents, including headless

The command dey take file, folder, quoted glob, or multiple paths at once, followed by optional skill name. Anything wey you fit put inside one directory go work, including RFC set (request for comments, 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-research

Quote the glob so your shell no expand am before the skill see am. If you point the command to existing skill directory, 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 mainly text, wey go decide the extractor. Whether you want reference depth or study depth, wey go decide the budget for each chapter. Wetin the skill name suppose be, and which skills root e suppose enter. E go also show token and time estimate before generation, then wait for you to confirm.

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 dey pre-approve the tools wey the run need, because permission prompt when no terminal dey attached na run wey no go ever finish. If you add --output-format json, e go put total_cost_usd inside the result. Na client-side estimate be that, no be your bill.

Extraction dey 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 mean say run fit report success even when e read fewer files than the ones you provide. Compare the file inventory for the final report with wetin dey inside the folder. If chapter no dey, na usually source no dey.

Give the run server wey you dey comfortable to hand over to an agent. How to run Claude Code safely on a VPS explain the permission side of that.

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 cover the converter, no be the book

Make sure say you understand this well, because the problem no be technical one.

• MIT license cover the converter code and the skill definition. E no talk anything about the document wey you give am.
• If you run the converter for a book wey you buy, on 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 permission to distribute anything wey come from another person book.
• The output na derivative work. Frameworks and chapter takeaways still come from the source, and source copyright still govern derivative work.
• If you build a skill from material wey you no fit redistribute, leave am for the machine wey build am. No put am for public repository. No share am for team marketplace.
• Publish only when the source na your own or e get open license: documentation wey your team write, or standard wey the terms allow people to redistribute.

The tool design follow this principle. E no ship with book content, extraction dey run locally, and the publish step ask repository visibility as separate question. E only accept the exact word public or private; e no dey guess one. Treat that prompt 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 fit read whenever e need am. Read the generated files one time before you commit dem, and see how to keep secrets out of your AI agents.

Wetin be the cost of one conversion?

The numbers below na the project own published measurements, no be our own measurements.

[
  {
    "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 on Claude Sonnet 4.5, using token counts from tiktoken with cl100k_base, and dem publish am for the project docs/performance.md as of August 2026. Your own amount go change based on your model and your prices.

The project also document say e take 24 to 51 times fewer tokens to answer one question from the skill than from the whole book wey dem paste 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 structural point still dey: 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.

Failure modes, and the strings you go see

A scanned PDF no dey produce anything. The extractor dey check the opening pages for text layer and e go stop with explanation instead of grinding 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 the system Python. Use the virtual environment wey dey above, or install poppler-utils and skip pip completely.

The chapters no come out correctly. Chapter detection dey look for clear headings like Chapter 7 and the language variants wey go with am. Book wey use bare section titles or roman numerals fit give bad split. To fix am, tell the run where the chapters start instead of hoping say e go guess.

The command no exist. If /book-to-skill no dey show for autocomplete, e mean say the skills directory dey created after your session start. Restart the agent.

Docling dey take forever. For about 1.5 seconds per page, e fit use many minutes of CPU time for long book. For shared server, that run go compete with every other thing wey you 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 quietly. If file no fit read, the process go skip am so the batch fit finish. The run go then report success for fewer sources than the ones wey you give am. Na only the file inventory for the final report go show this.

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.

1. 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.
2. 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.
3. 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 give 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 sources wey get open license. The tool also ask repository visibility as separate question, and e accept only bare public or private, so you go make the decision deliberately.

I need docling, or pdftotext enough?

pdftotext from poppler-utils enough for prose and e dey finish almost immediately. Install docling when the important content for the book dey inside tables and code listings, because plain text extractor dey drop exactly those parts. The trade-off na speed: the 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 to install inside am and e print error: externally-managed-environment. Create virtual environment with python3 -m venv ~/.venvs/book-to-skill, activate am, install the extractors there, then start your agent from that same shell. The skill call python3, so e use whichever interpreter dey for your PATH. For this case, na the interpreter inside the virtual environment dey there.

Why my generated skill no dey show as slash command?

Two causes dey. Command name come from directory name, so skill must dey for ~/.claude/skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.md, and SKILL.md must spell exactly that way. If path correct, 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 don start.