Turn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.
Python agent-skillsai-agentsbook-to-skillcontext-engineeringdocument-processingedtechknowledge-baseknowledge-managementllmpdf-to-markdownragself-studystudy-tools
feat: ask book type before extraction to choose pdftotext vs Docling
Virgilio Borges3a489cff1d0c
diff --git a/SKILL.md b/SKILL.mdindex bde790f..aa31260 100644--- a/SKILL.md+++ b/SKILL.md@@ -73,17 +73,43 @@ If the file is not found or the format is not supported, stop with a clear error---+## Step 1.5 — Identify book type++Before extracting, ask the user:++> "What kind of content does this book have? This helps me choose the best extraction method.+>+> 1. **Technical** — has code blocks, tables, formulas, diagrams (e.g. programming books, academic papers, architecture guides)+> 2. **Text-heavy** — mostly prose, few or no tables/code (e.g. management, productivity, narrative non-fiction)+> 3. **Not sure** — I'll use the fast method and warn you if quality seems limited"++Store the answer as `BOOK_TYPE`:+- Option 1 → `BOOK_TYPE=technical`+- Option 2 → `BOOK_TYPE=text`+- Option 3 → `BOOK_TYPE=text`++**If `BOOK_TYPE=technical`**, inform the user before proceeding:+> "📐 Technical mode selected — using Docling for structure-aware extraction (tables, code blocks, formulas preserved as markdown). This takes ~1.5s per page, so expect a few minutes for longer books. Starting now…"++**If `BOOK_TYPE=text`**, inform:+> "📄 Text mode selected — using fast extraction (pdftotext). Ready in seconds."++---+## Step 2 — Extract text from PDF or EPUB-Run the extraction script:+Run the extraction script, passing the book type:```bash-python3 ~/.claude/skills/book-to-skill/scripts/extract.py "$0"+python3 ~/.claude/skills/book-to-skill/scripts/extract.py "$0" --mode <BOOK_TYPE>```+- `--mode technical` → uses Docling (layout-aware, preserves tables and code blocks as markdown)+- `--mode text` → uses pdftotext → PyPDF2 → pdfminer fallback chain (fast, plain text)+This creates:- `/tmp/book_skill_work/full_text.txt` — full extracted text-- `/tmp/book_skill_work/metadata.json` — title, estimated pages, token count, size+- `/tmp/book_skill_work/metadata.json` — title, estimated pages, token count, size, extraction_modeRead `/tmp/book_skill_work/metadata.json` to understand what was extracted.@@ -204,7 +230,11 @@ For EACH chapter/major section identified in Step 3:Read the corresponding section of `/tmp/book_skill_work/full_text.txt` (use character offsets or grep for chapter headings).-Create `~/.claude/skills/<skill_name>/chapters/ch<NN>-<slug>.md` with this structure:+Create `~/.claude/skills/<skill_name>/chapters/ch<NN>-<slug>.md` using the structure below.++**Adapt emphasis based on `BOOK_TYPE`:**+- `technical` → prioritize "Code Examples", "Reference Tables", and "Commands & APIs" sections; preserve exact syntax+- `text` → prioritize "Frameworks Introduced", "Mental Models", and "Key Takeaways"; skip empty technical sections```markdown# Chapter N: <Full Title>@@ -227,6 +257,16 @@ Create `~/.claude/skills/<skill_name>/chapters/ch<NN>-<slug>.md` with this struc## Anti-patterns- **<What to avoid>**: <why it fails>+## Code Examples *(technical books only — omit if BOOK_TYPE=text)*+<!-- Copy the most instructive snippet from the chapter. Preserve indentation exactly. -->+```<language>+<key code example from this chapter>+```+- **What it demonstrates**: <one line>++## Reference Tables *(technical books only — omit if BOOK_TYPE=text)*+<!-- Reproduce any comparison matrix, parameter table, or decision table from the chapter in markdown. -->+## Key Takeaways1. <Actionable insight>2. <Actionable insight>diff --git a/scripts/extract.py b/scripts/extract.pyindex fe117fa..b27ef47 100644--- a/scripts/extract.py+++ b/scripts/extract.py@@ -242,13 +242,47 @@ def detect_structure(text: str) -> dict:}+def extract_with_docling(pdf_path: str) -> str | None:+ """Layout-aware extraction using Docling. Best for technical books with tables and code."""+ try:+ from docling.document_converter import DocumentConverter+ from docling.datamodel.pipeline_options import PdfPipelineOptions+ from docling.datamodel.base_models import InputFormat+ from docling.document_converter import PdfFormatOption++ pipeline_options = PdfPipelineOptions()+ pipeline_options.do_ocr = False+ pipeline_options.do_table_structure = True++ converter = DocumentConverter(+ format_options={+ InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)+ }+ )+ result = converter.convert(pdf_path)+ return result.document.export_to_markdown()+ except ImportError:+ return None+ except Exception:+ return None++def main():if len(sys.argv) < 2:- print("Usage: extract.py <path-to-pdf-or-epub>", file=sys.stderr)+ print("Usage: extract.py <path-to-pdf-or-epub> [--mode technical|text]", file=sys.stderr)sys.exit(1)input_path = sys.argv[1]+ # Parse --mode flag+ extraction_mode = "text"+ if "--mode" in sys.argv:+ idx = sys.argv.index("--mode")+ if idx + 1 < len(sys.argv):+ extraction_mode = sys.argv[idx + 1].lower()+ if extraction_mode not in ("technical", "text"):+ extraction_mode = "text"+if not os.path.exists(input_path):print(f"ERROR: File not found: {input_path}", file=sys.stderr)sys.exit(1)@@ -281,37 +315,49 @@ def main():pages_label = "spine_items"else:print(f"Extracting PDF: {input_path}")- print("Trying pdftotext...", end=" ", flush=True)- text = extract_with_pdftotext(input_path)+ if extraction_mode == "technical":+ print("Mode: technical — using Docling (layout-aware)...", end=" ", flush=True)+ text = extract_with_docling(input_path)+ if text:+ method = "docling"+ print("OK")+ else:+ print("not available, falling back to pdftotext")+ extraction_mode = "text"++ if extraction_mode == "text":+ print("Mode: text — using pdftotext...")+ print("Trying pdftotext...", end=" ", flush=True)+ text = extract_with_pdftotext(input_path)- if text:- method = "pdftotext"- print("OK")- else:- print("not available")- print("Trying PyPDF2...", end=" ", flush=True)- text = extract_with_pypdf2(input_path)if text:- method = "PyPDF2"+ method = "pdftotext"print("OK")else:print("not available")- print("Trying pdfminer.six...", end=" ", flush=True)- text = extract_with_pdfminer(input_path)+ print("Trying PyPDF2...", end=" ", flush=True)+ text = extract_with_pypdf2(input_path)if text:- method = "pdfminer"+ method = "PyPDF2"print("OK")else:- print("FAILED")- print(- "\nERROR: Could not extract text from PDF.\n"- "Install one of: poppler-utils (pdftotext), PyPDF2, or pdfminer.six\n"- " sudo apt install poppler-utils\n"- " pip3 install PyPDF2\n"- " pip3 install pdfminer.six",- file=sys.stderr,- )- sys.exit(1)+ print("not available")+ print("Trying pdfminer.six...", end=" ", flush=True)+ text = extract_with_pdfminer(input_path)+ if text:+ method = "pdfminer"+ print("OK")+ else:+ print("FAILED")+ print(+ "\nERROR: Could not extract text from PDF.\n"+ "Install one of: poppler-utils (pdftotext), PyPDF2, or pdfminer.six\n"+ " sudo apt install poppler-utils\n"+ " pip3 install PyPDF2\n"+ " pip3 install pdfminer.six",+ file=sys.stderr,+ )+ sys.exit(1)pages = count_pages(input_path)pages_label = "pages"@@ -328,6 +374,7 @@ def main():"filename": Path(input_path).name,"format": "epub" if is_epub else "pdf","extraction_method": method,+ "extraction_mode": extraction_mode,"file_size_mb": round(file_size_mb, 2),pages_label: pages,"chars": len(text),