| name | from-pdf-skill-builder |
| description | Build a high-quality Claude Code skill from one or more PDFs using vision-based page-by-page extraction. Use when converting reference material (technical manuals, certificates, policy documents, magazines, books, regulations) into a skill with structured markdown chapters, bundled diagrams, and a navigable SKILL.md. Triggers on requests like "convert this PDF to a skill", "make a skill from these manuals", "build a knowledge base from these documents", "vision-extract this PDF into a skill", or when the user has decided to turn PDF reference material into a Claude Code skill. |
| metadata | {"version":"1.0.0"} |
Build a skill from PDF(s) via vision
This skill is the playbook for converting one or more PDF reference documents into a high-quality Claude Code skill. The output is a skill folder where:
- Source PDFs are bundled (the skill is self-contained and portable)
- Each chapter/section is a structured markdown file (real headings, tables, blockquotes, inline diagram references)
- Diagrams are extracted as PNG and named by content
SKILL.md has frontmatter triggers, navigation, quick-lookup tables, and "common questions → file" pointers
The defining technique is vision extraction via a general-purpose subagent per chapter. Reading PDF pages as images and writing structured markdown gives dramatically higher quality than pdftotext for any document with tables, multi-column layouts, callouts, or diagrams.
Target skill structure
<skill-name>/
├── SKILL.md # Frontmatter + navigation + quick-lookup
├── <source>.pdf # Bundled original (or multiple)
├── kapitler/ # Use original-language word: "chapters", "kapitler", "kapitel", "luvut"...
│ ├── 01-<slug>.md
│ ├── 02-<slug>.md
│ └── ...
└── diagrammer/ # Match source-language word as for chapters
├── <content-name>.png
└── ...
Optional subfiles for related but distinct topics that don't fit the chapter model (e.g. a verbatim certificate forsikringsbevis.md alongside curated redningsselskapet.md).
Process
1. Setup
- Choose a kebab-case skill name that names the domain, not the document title (e.g.
motor-yamaha-f100, not yamaha-f100-owners-manual-2010).
- Create folder structure:
SKILL.md, kapitler/, diagrammer/.
- Copy source PDF(s) into the skill folder. Rename to descriptive slugs (e.g.
manual.pdf, policy.pdf, loggen.pdf) — not their original filenames.
2. Discover document structure
Before extracting, identify chapters/sections:
- Read the TOC page or sample a few pages with
pdftotext -f N -l N <pdf> - to get titles and ranges.
- Note any difference between physical PDF pages (what
pdftoppm uses) and logical pages (what the document prints). Vehicle/machinery manuals often have a 6-page offset; magazines and books usually match.
- Map each chapter to a physical page range. Save this mapping — every subagent needs its range.
3. Vision-extract chapters in parallel
For each chapter, spawn one general-purpose subagent using the template at templates/subagent-vision-prompt.md. Fill in the placeholders, then invoke.
Send all subagent invocations in a single message so they run in parallel. Wall-clock time is bounded by the longest chapter (typically 10-15 minutes for a 20+ page chapter, 1-3 minutes for short chapters).
Token cost is roughly 40-70k per chapter; budget accordingly for large documents.
Each subagent returns a brief report:
- Pages processed
- Suggested new diagrams (with proposed slug and description)
- Uncertain transcriptions to verify
- Quality verdict
Collect the diagram suggestions across all subagents.
4. Extract diagrams
Render suggested diagrams (and any obvious whole-page figures you want available):
pdftoppm -png -r 200 -f N -l N source.pdf /path/to/diagrammer/<content-name>
- 200 DPI is the default — good balance of quality and file size.
- 300 DPI for verification of suspect text or fine detail.
- Name PNGs by what the figure shows, not its page number.
greasing-points-f80bet.png, not page-80.png.
pdftoppm zero-pads the resulting filename with 2 or 3 digits depending on the page range — handle both when renaming:
for f in *.png; do
new=$(echo "$f" | sed -E 's/-[0-9]{2,3}\.png$/.png/')
[ "$f" != "$new" ] && mv "$f" "$new"
done
Verify each rendered diagram by opening it with the Read tool — confirm it shows what the chapter file references.
5. Build SKILL.md
Use the skeleton at templates/skill-md-skeleton.md.
Key choices:
- Description language: write the frontmatter
description in the user's likely query language, not the document's language. A Norwegian user querying about an English manual will type in Norwegian; the description must match those queries to trigger.
- Description content: list explicit trigger phrases — synonyms, specific identifiers (policy numbers, model codes), product names. The combined
description + when_to_use is capped at 1,536 characters, so be dense.
- Quick-lookup tables: put the most-asked facts directly in SKILL.md (specs that change rarely, key numbers, contacts). These avoid loading a full chapter for a one-line answer.
- Navigation table: every chapter and diagram should be linked from SKILL.md so users can jump straight in. Include short descriptions of what each contains.
- Common questions → file: add a table like "Where is X? → [chapter Y]". This is a learned-question map; populate from real or anticipated queries.
Keep SKILL.md under 500 lines per Anthropic guidance. Move detail to chapter files or topical subfiles.
6. Validate
7. Correct OCR errors
When subagent reports flag uncertain transcriptions, re-render the suspect page at 300 DPI and verify with the Read tool. Apply targeted edits to the chapter file. See "OCR error patterns" below.
Conventions
Faithfulness to source
- Do not translate. Source-language content stays in source language. Only the SKILL.md navigation layer (descriptions, quick-lookup labels) uses the user's language.
- Do not paraphrase or summarize. Chapter files are verbatim transcriptions.
- Preserve original typos. Do not "correct" the source author. (This is part of validation honesty.)
[unreadable: see source.pdf page N] rather than guess.
Filename language
Match the source document's language:
| Source language | Chapter folder | Diagram folder |
|---|
| English | chapters/ | diagrams/ |
| Norwegian | kapitler/ | diagrammer/ |
| German | kapitel/ | diagramme/ |
| Swedish | kapitel/ | diagram/ |
Within each folder, use English filenames matching the document's own chapter/diagram terminology. So an English boat manual's chapter 5 "Characteristics and use" becomes chapters/05-characteristics-and-use.md.
Bundling
Always bundle the source PDF(s) into the skill folder. The skill is then portable and self-verifiable — anyone can compare extracted markdown against the source. Symlinks are brittle; copy the files.
Quality rules
Vision rendering
- Default 200 DPI. Higher DPI = sharper text but larger PNGs and more processing.
- 300 DPI for verification of dense small text or where subagent flagged uncertainty.
- Re-render is cheap. When in doubt, look at the page image again.
Two-column / multi-column layouts
This is the single biggest reason to use vision instead of pdftotext. The subagent prompt explicitly instructs: read each column top-to-bottom completely before moving to the next column, never interleave.
Numbers and exact values
Safety- and finance-critical numbers must be exact. For each number transcribed, the subagent should be able to re-read it from the page image without ambiguity. The prompt includes "re-read each torque/capacity/voltage" and "preserve units exactly (mm vs in, L vs US qt, Nm vs ft-lb)".
OCR error patterns
Vision occasionally misreads visually-similar glyphs. Watch for:
| Misreading | Actual | Context |
|---|
benner | tenner | Norwegian "ignites" |
From | Pump | Imperative verb start of sentence |
runde | runder | Trailing letter dropped |
dieksom | dersom | Mid-word confusion |
1.0.1.1 mm | 1.0–1.1 mm | Hyphen vs en-dash |
Latin-glyph confusions: 0/O, 1/l/I, b/h/k, m/n/rn | various | Especially in serif fonts at low DPI |
When the subagent reports an uncertain word, re-render at 300 DPI and trust the image.
Page chrome
Strip from every chapter:
- Page numbers (e.g. "12 (36)")
- Repeating headers (chapter title bars, magazine name)
- Repeating footers (URL, organization name)
- Logos and decorative elements
- Book/file identifiers (e.g.
U6D777E0.book Page 39 Wednesday, April 7, 2010 8:33 AM)
Form feed characters (\f) prefix some page headers in pdftotext output and break naive regex anchored with ^. Not an issue for vision extraction directly, but if you ever fall back to text-based cleanup, run tr -d '\f' first.
Diagram embedding
In each chapter file, embed an inline diagram reference at the natural reading point:
For diagrams that exist but the subagent's chapter doesn't naturally reference, list them in SKILL.md's diagram-overview table only.
For very small inline figures (single icons, single arrows), the subagent should describe in prose rather than insert a placeholder.
For useful figures the subagent identifies but that don't exist as PNGs yet, the subagent should insert a placeholder line:
*[Figure: <description>, see source.pdf page <N>]*
…and flag it in its final report. You then extract those PNGs in step 4 and either replace the placeholders or leave them as references.
When NOT to use vision
Use simpler tools when:
- The document is pure prose, single-column, no figures, no tables. Plain
pdftotext (no flags) handles this in seconds.
- A single-page document. Manual transcription may be faster than spinning up a subagent.
- The document is already structured markdown or HTML. Convert directly without vision.
Even in these cases, the structure conventions (SKILL.md navigation, quick-lookup, faithfulness) still apply.
Multi-PDF skills
When a skill covers several related PDFs:
- Bundle all PDFs in the skill folder with descriptive slugs.
- Either keep separate chapter folders per source (
chapters-manual/, chapters-policy/) or merge into one chapters/ with a source-prefixed naming scheme.
- SKILL.md navigation lists each PDF and its chapters/sections explicitly.
- Cross-reference between sources where they touch (e.g. policy mentions a procedure documented in manual).
Templates and references
Notes on subagent usage
- Subagent has zero shared memory with the parent. Every prompt is self-contained: PDF path, page range, output path, available diagrams, faithfulness rules, expected report format.
- Use
general-purpose as the subagent type. It has full tool access including Read (which handles PNGs as images) and Bash (for pdftoppm and cleanup).
- One subagent per chapter — not per page, not per document. Per-chapter scope keeps each task bounded (5-50 pages) and parallelizable.
- Send all subagent invocations in one message to run them in parallel. Sequential is much slower.
- Each subagent uses a unique
/tmp/<prefix>- for its rendered PNGs to avoid collisions when running in parallel.
- Subagents clean up their own temp files as the last step.
Iteration
Skills mature through revision:
- First pass often surfaces things you didn't know about the document.
- Keep a backup of the first extraction during conversion (e.g.
chapters-raw/) until you've validated quality, then delete.
- Re-run individual chapter subagents when you find quality issues — much cheaper than re-running everything.
- SKILL.md grows as you encounter more "common questions" that should be in the quick-lookup.
