October 4, 2026
How to turn books into AI skills with book-to-skill
By Synthex
You remember reading a useful explanation for the problem you're working on, but you can't remember which chapter it was in. You could search the book or ask an AI, though a confident answer still leaves you wondering whether it matches your copy.
book-to-skill turns books and documents into organized reference files an AI agent can consult while you work. You give it a local file or collection of files, and the agent builds a skill with chapter notes, named methods, and rules for applying the ideas.
Tom Dörr's post (opens in new tab) introduced the project. The book-to-skill repository (opens in new tab) contains the converter and its instructions.
What you'll learn
You'll install the converter in Claude Code, create a book skill, and use it for a question you can check against the source. You'll also see how the reference files work, how to update them, and what to inspect after conversion.
What a book skill actually is
An AI agent is an AI tool that can carry out tasks using tools, such as reading files or running commands. A skill is a folder of instructions and supporting material that tells the agent how to handle a particular task. The Agent Skills format puts the main instructions in a file called SKILL.md. Agent Skills overview (opens in new tab)
For a book about running reliable services, the skill might help an agent review a retry policy, explain a failure mode, or check a proposed design against the author's advice. For a writing handbook, it could provide editing rules and examples.
There are two parts to book-to-skill. A Python program extracts text and metadata from the source files. Your AI agent then follows the converter's instructions to produce the skill. Installing the extractor alone does not complete the AI writing step. How the converter works (opens in new tab)
A generated skill has a main instruction file and supporting references:
| File | What it helps the agent do |
|---|---|
SKILL.md | Read the main ideas and find the relevant chapter or topic. |
chapters/ | Load notes for individual chapters or sections. |
glossary.md | Look up terms and their chapter references. |
patterns.md | Find techniques and recurring approaches. |
cheatsheet.md | Consult compact decision rules. |
These files contain synthesized notes. Keep the original book available for checking a detail, reading an example in full, or understanding an argument the notes condensed. Generated files (opens in new tab)
Claude Code can load a skill when it matches your request, or you can call it directly with /skill-name. Supporting files can stay on disk until the agent needs them. This approach is called progressive disclosure: load the instructions first, then the relevant detail. Claude Code skills (opens in new tab)
Before you start
This walkthrough uses Claude Code in a terminal, the application where you type commands. You'll need:
- A working Claude Code installation and an account that can use it. If you're new to it, follow the official quickstart (opens in new tab), complete login, and confirm that you can start a session.
- Python (opens in new tab) 3.9 or newer for the extractor. That is the project's declared minimum; optional extraction packages may have their own requirements. Package requirements (opens in new tab)
- Node.js (opens in new tab), preferably its LTS release, for the
npxinstallation command below, and Git (opens in new tab) for downloading the repository. - A local book or document you're allowed to process. Start with something you can readily compare against the original.
Open PowerShell on Windows or Terminal on macOS or Linux. Check that the command-line tools are available:
Then check Python. On Windows, try python --version. On macOS or Linux, try python3 --version. Each successful command should print a version. If one is missing, finish installing that application and reopen your terminal before continuing.
The converter is MIT-licensed. Your AI account's usage charges or subscription limits still apply, including the initial conversion. The software license also doesn't grant permission to share material from a book you process. Converter license (opens in new tab)
Step 1: Install the converter
Run this in your ordinary terminal, before opening a Claude Code conversation:
npx runs the skills installer. This command selects book-to-skill, targets Claude Code, and uses --global to install it for your user account across projects. Read the install summary and finish the prompts. Skills CLI installation options (opens in new tab)
Use the exact repository owner shown in the command. The maintainer has reported a malicious re-upload under a different owner. Official repository security notice (opens in new tab)
The agent needs the converter's supporting scripts as well as its SKILL.md, so install the complete folder. Installing the optional Python CLI through pip alone won't register /book-to-skill in your agent. book-to-skill installation guide (opens in new tab)
Step 2: Open a folder containing your book
Create a small working folder in a location you can find again:
Using your file manager, put your document inside book-lab/books. The examples below use the filename your-book.pdf. Substitute your real filename, or rename your copy to match it.
From the book-lab folder, start Claude Code:
Approve access to this folder if prompted. Inside Claude Code, type / and look for book-to-skill among the available skills. If you installed it while an older session was open, start a new session. Using the converter (opens in new tab)
Run terminal commands such as npx at your shell prompt. Type commands beginning with /book-to-skill inside the Claude Code conversation.
Step 3: Convert the document
Inside Claude Code, give it these instructions first:
~ means your user home folder. This explicitly chooses Claude Code's personal skill location. The converter's normal shared location is ~/.agents/skills/; under Claude Code, that shared output needs a working link from ~/.claude/skills/. Choosing the Claude Code folder directly avoids depending on that link for this example. Output locations (opens in new tab)
Then invoke the converter:
book-reference is the skill name you'll use later. You can choose a more specific lowercase name with hyphens. If a path contains spaces, put it in quotation marks.
The converter asks about the content type. Choose technical when the PDF depends on code, tables, or formulas; this uses Docling for extraction that preserves more structure. Choose text-heavy for mostly prose. Install a missing extraction package only after reading the proposed command and its purpose. Extraction requirements (opens in new tab)
Review the estimated usage before agreeing to generation. You can request analyze only if you want to inspect the document analysis first. If asked about depth, choose reference depth for compact guidance or study depth for fuller worked explanations. Conversion modes and depth (opens in new tab)
When generation finishes, ask Claude to show the actual output path and the files it created. Open SKILL.md and one chapter file. Confirm that the source identity and chapter titles match your document.
If the converter's generated-file scan flags content, review its findings before loading the new skill. A document can contain instructions that should remain source material rather than become directions for your agent. Generated-skill review procedure (opens in new tab)
Step 4: Ask a question using the new skill
Start a new Claude Code session so it discovers the generated skill, then try:
The answer should describe the generated chapter index. Check it against the book's contents page before moving on.
For a book covering reliable services, you could ask:
Choose a topic your book actually covers. Naming the file gives you something concrete to inspect; it doesn't prove the answer is correct.
Next, paste a draft retry policy and ask the agent to review it against the book's advice. Ask what supports each recommendation and where the notes don't cover the decision. Follow the chapter references and inspect the reasoning before accepting a suggested change.
Check the conversion before relying on it
Pick a section you know well and compare its generated notes with the original. Then ask a question whose answer you can verify. Look for a missing condition, a reversed recommendation, or an example that lost the detail that made it useful.
For instance, if your source says to retry only certain failures, a note that says "retry failed requests" has removed an important boundary. Ask the agent to correct the note from the original passage, then repeat the question. This checks whether the skill preserves the advice you need for your task.
The repository uses "no hallucination" wording. Generated notes and answers still need checking. Extraction can miss or flatten text; generation and later answers can also distort a correct source or invent a detail. Keeping reference files available does not establish that every response is faithful to the source.
If a question needs an exact quotation or page number, consult the original. Don't assume the synthesized chapter notes retained either.
How to read the token-saving claim
Tokens are the pieces of text an AI model processes. Its context is the material it receives for the current response. Loading fewer reference tokens can leave more room for the current task and reduce input usage.
The project's performance page compares putting an entire book into context with loading roughly 4,000 tokens of core skill material plus a 1,000-token chapter. Its examples report about 24 to 51 times fewer tokens for one targeted question. Performance methodology (opens in new tab)
That comparison uses an approximately 5,000-token skill load. A longer chapter, several relevant chapters, or study-depth notes will change it. The initial conversion also consumes usage. The figures describe the project's reference-token comparison; they don't establish a matching reduction in your total bill, elapsed time, or error rate.
For a book you consult repeatedly, reusable chapter files give the agent a smaller set of material to read for each question. Try the skill on your own recurring task before assuming a particular saving.
Add documents or update an existing skill
The converter also accepts a folder or several files. For example, you could combine your team's onboarding guide and service runbooks into one reference skill:
Keep unrelated sources separate so the resulting instructions have a clear purpose. A brand handbook could support writing reviews; a collection of related papers could support questions about a research topic. Check that the combined notes preserve which source supports an idea.
To add a new document to the skill from this walkthrough, point the converter at its existing folder:
This selects the update/fold-in workflow. Ask it to show revised sections and resolve contradictions between sources, then inspect the affected files. New editions or documents need an explicit update; the converter doesn't monitor the source for you. Multi-file inputs and updates (opens in new tab)
Common problems
Claude can't find the skill
Start a new session, then check that the skill folder contains SKILL.md in a location Claude Code reads. If the converter reports output in ~/.agents/skills/, confirm that its Claude Code link worked. Ask it to inspect the actual path before attempting a repair. Skill discovery troubleshooting (opens in new tab)
The PDF is scanned or important content is missing
A scan may contain page images without a usable text layer. Apply OCR, software that recognizes text in images, before conversion. The project documents ocrmypdf input.pdf output.pdf for readers who already have OCRmyPDF installed. You can also use your PDF application's OCR feature and save a searchable copy. Scanned-PDF guidance (opens in new tab)
Review code indentation and tables after extraction. Technical mode helps preserve their structure, but diagrams still need checking against the original. Chapter detection can also miss unusual headings, so correct a broken chapter map before generating more notes.
A helper script or Python package is missing
Ask the agent to locate the installed converter's scripts/extract.py and run it with --check, using your working Python command. That prints a format-by-format dependency report. Install only what your input needs. If the script itself is absent, reinstall the complete converter rather than just its SKILL.md. Dependency checks (opens in new tab)
Keep the source and output in the right place
Extraction runs locally, but a cloud-hosted agent may send extracted text to its model provider during generation or later use. Check your organization's rules before using internal documents. Local extraction alone doesn't make the whole workflow private. Processing and source rights (opens in new tab)
Keep skills derived from third-party books private unless you have permission to distribute them. A private repository also doesn't authorize sending confidential material to an external service.
I'd start with a document you return to often and a question you can check yourself. Create the skill and compare one section with the source, including the conditions behind its advice. Then use it for a real task and correct any gap you find before relying on that part again.