Skip to content

Turn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.

feat: ask book type before extraction to choose pdftotext vs Docling

Virgilio Borges3a489cff1d0c
diff --git a/SKILL.md b/SKILL.md
index 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_mode
Read `/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 Takeaways
1. <Actionable insight>
2. <Actionable insight>
diff --git a/scripts/extract.py b/scripts/extract.py
index 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),