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: add EPUB support (ebooklib + stdlib zipfile fallback)
Virgilio Borgesd88e69e89e6e
diff --git a/SKILL.md b/SKILL.mdindex 02c0567..bde790f 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,13 +1,13 @@---name: book-to-skill-description: Converts a technical book PDF into a structured Claude Code skill — extracting frameworks, mental models, principles, techniques, and anti-patterns the author crystallized. Use when the user wants to study a book through Claude, apply an author's frameworks while working, or build a reusable knowledge base from any PDF.-when_to_use: Trigger phrases — "turn this book into a skill", "create a skill from this PDF", "I want to study X book", "add this book to my skills", "convert PDF to skill", "analyze this book", "extract frameworks from this book". Accepts a path to a PDF and optional skill name slug.+description: Converts a technical book (PDF or EPUB) into a structured Claude Code skill — extracting frameworks, mental models, principles, techniques, and anti-patterns the author crystallized. Use when the user wants to study a book through Claude, apply an author's frameworks while working, or build a reusable knowledge base from any PDF or EPUB.+when_to_use: Trigger phrases — "turn this book into a skill", "create a skill from this PDF", "create a skill from this EPUB", "I want to study X book", "add this book to my skills", "convert PDF to skill", "convert EPUB to skill", "analyze this book", "extract frameworks from this book". Accepts a path to a PDF or EPUB and optional skill name slug.disable-model-invocation: truecontext: forkagent: general-purposeallowed-tools: Bash(python3 *) Bash(pdftotext *) Bash(mkdir *) Bash(cp *) Bash(find *) Bash(wc *) Bash(echo *) Bash(cat *) Bash(date *) Read Write Glob Grep-argument-hint: <path-to-pdf> [skill-name-slug]-arguments: [pdf_path, skill_name]+argument-hint: <path-to-pdf-or-epub> [skill-name-slug]+arguments: [book_path, skill_name]effort: high---@@ -55,8 +55,8 @@ Three paths available. Route based on what the user asks:## Step 0 — Out-of-scope check-If the argument is NOT a path to a PDF, stop and respond:-> "book-to-skill requires a PDF path. Usage: `/book-to-skill /path/to/book.pdf [skill-name]`"+If the argument is NOT a path to a PDF or EPUB file, stop and respond:+> "book-to-skill requires a PDF or EPUB path. Usage: `/book-to-skill /path/to/book.pdf [skill-name]` or `/book-to-skill /path/to/book.epub [skill-name]`"---@@ -64,14 +64,16 @@ If the argument is NOT a path to a PDF, stop and respond:```bashtest -f "$0" && echo "FILE_OK" || echo "FILE_NOT_FOUND: $0"-file "$0" | grep -i pdf && echo "IS_PDF" || echo "NOT_PDF"+file "$0" | grep -iE "pdf|epub|zip" && echo "FORMAT_OK" || echo "FORMAT_UNKNOWN"```-If the file is not found or not a PDF, stop with a clear error message.+Check the file extension (`.pdf` or `.epub`) or magic bytes (`%PDF` or `PK` zip header).++If the file is not found or the format is not supported, stop with a clear error message listing supported formats.----## Step 2 — Extract text from PDF+## Step 2 — Extract text from PDF or EPUBRun the extraction script:@@ -92,8 +94,8 @@ Read `/tmp/book_skill_work/metadata.json` to understand what was extracted.Read `/tmp/book_skill_work/metadata.json` and present the user with an estimate **before doing any generation**:```-📖 Book detected: <filename>-📄 Pages: ~<N> | Words: ~<N> | Source tokens: ~<N>K+📖 Book detected: <filename> (<format: PDF or EPUB>)+📄 Pages/Spine items: ~<N> | Words: ~<N> | Source tokens: ~<N>K💰 Estimated token cost (Full Conversion):Input (book reading + prompts): ~<N>K tokensdiff --git a/scripts/__pycache__/extract.cpython-313.pyc b/scripts/__pycache__/extract.cpython-313.pycnew file mode 100644index 0000000..e889c7cBinary files /dev/null and b/scripts/__pycache__/extract.cpython-313.pyc differdiff --git a/scripts/extract.py b/scripts/extract.pyindex caff726..fe117fa 100644--- a/scripts/extract.py+++ b/scripts/extract.py@@ -1,22 +1,30 @@#!/usr/bin/env python3"""-Extract text from a PDF file for book-to-skill processing.+Extract text from a PDF or EPUB file for book-to-skill processing.-Tries extraction methods in order:+PDF extraction tries methods in order:1. pdftotext (poppler-utils) — best quality2. PyPDF2 — common Python library3. pdfminer.six — thorough fallback+EPUB extraction tries methods in order:+ 1. ebooklib + BeautifulSoup4 — best quality+ 2. zipfile + html.parser — stdlib fallback (no extra deps)+Outputs:/tmp/book_skill_work/full_text.txt — full extracted text/tmp/book_skill_work/metadata.json — stats and metadata"""+import html+import html.parserimport jsonimport os+import reimport shutilimport subprocessimport sys+import zipfilefrom pathlib import PathOUTPUT_DIR = Path("/tmp/book_skill_work")@@ -73,6 +81,123 @@ def extract_with_pdfminer(pdf_path: str) -> str | None:return None+def extract_with_ebooklib(epub_path: str) -> str | None:+ try:+ import ebooklib+ from ebooklib import epub+ from bs4 import BeautifulSoup++ book = epub.read_epub(epub_path)+ parts = []+ for item in book.get_items_of_type(ebooklib.ITEM_DOCUMENT):+ soup = BeautifulSoup(item.get_content(), "html.parser")+ parts.append(soup.get_text(separator="\n"))+ return "\n\n".join(parts)+ except ImportError:+ return None+ except Exception:+ return None+++class _HTMLTextExtractor(html.parser.HTMLParser):+ """Minimal HTML → plain text converter using stdlib only."""++ SKIP_TAGS = {"script", "style", "head"}++ def __init__(self):+ super().__init__()+ self._parts: list[str] = []+ self._skip_depth = 0+ self._current_skip: str | None = None++ def handle_starttag(self, tag, attrs):+ if tag in self.SKIP_TAGS:+ self._skip_depth += 1+ if tag in ("p", "br", "h1", "h2", "h3", "h4", "h5", "h6", "li", "div"):+ self._parts.append("\n")++ def handle_endtag(self, tag):+ if tag in self.SKIP_TAGS and self._skip_depth:+ self._skip_depth -= 1++ def handle_data(self, data):+ if not self._skip_depth:+ self._parts.append(data)++ def get_text(self) -> str:+ return html.unescape("".join(self._parts))+++def extract_with_zipfile(epub_path: str) -> str | None:+ """stdlib-only EPUB extractor: unzip → parse HTML files."""+ try:+ with zipfile.ZipFile(epub_path) as zf:+ names = zf.namelist()+ # Read OPF spine to get reading order, fall back to sorted xhtml files+ spine_order: list[str] = []+ opf_files = [n for n in names if n.endswith(".opf")]+ if opf_files:+ opf_text = zf.read(opf_files[0]).decode("utf-8", errors="replace")+ spine_order = re.findall(r'href=["\']([^"\']+\.(?:xhtml|html))["\']', opf_text)++ html_files = spine_order or sorted(+ n for n in names if n.endswith((".html", ".xhtml"))+ )+ if not html_files:+ return None++ parts = []+ for name in html_files:+ try:+ raw = zf.read(name).decode("utf-8", errors="replace")+ parser = _HTMLTextExtractor()+ parser.feed(raw)+ parts.append(parser.get_text())+ except Exception:+ continue+ return "\n\n".join(parts) if parts else None+ except Exception:+ return None+++def extract_epub(epub_path: str) -> tuple[str, str]:+ """Return (text, method) for an EPUB file."""+ print("Trying ebooklib + BeautifulSoup4...", end=" ", flush=True)+ text = extract_with_ebooklib(epub_path)+ if text and text.strip():+ print("OK")+ return text, "ebooklib"++ print("not available")+ print("Trying stdlib zipfile parser...", end=" ", flush=True)+ text = extract_with_zipfile(epub_path)+ if text and text.strip():+ print("OK")+ return text, "zipfile"++ print("FAILED")+ print(+ "\nERROR: Could not extract text from EPUB.\n"+ "Install ebooklib + beautifulsoup4 for best results:\n"+ " pip3 install ebooklib beautifulsoup4",+ file=sys.stderr,+ )+ sys.exit(1)+++def count_epub_chapters(epub_path: str) -> int:+ """Count spine items (approximate chapter count) without dependencies."""+ try:+ with zipfile.ZipFile(epub_path) as zf:+ opf_files = [n for n in zf.namelist() if n.endswith(".opf")]+ if not opf_files:+ return 0+ opf_text = zf.read(opf_files[0]).decode("utf-8", errors="replace")+ return len(re.findall(r'<itemref\b', opf_text))+ except Exception:+ return 0++def count_pages(pdf_path: str) -> int:# Try pdfinfo firstif shutil.which("pdfinfo"):@@ -119,64 +244,92 @@ def detect_structure(text: str) -> dict:def main():if len(sys.argv) < 2:- print("Usage: extract.py <path-to-pdf>", file=sys.stderr)+ print("Usage: extract.py <path-to-pdf-or-epub>", file=sys.stderr)sys.exit(1)- pdf_path = sys.argv[1]+ input_path = sys.argv[1]- if not os.path.exists(pdf_path):- print(f"ERROR: File not found: {pdf_path}", file=sys.stderr)+ if not os.path.exists(input_path):+ print(f"ERROR: File not found: {input_path}", file=sys.stderr)sys.exit(1)- OUTPUT_DIR.mkdir(parents=True, exist_ok=True)+ ext = Path(input_path).suffix.lower()+ is_epub = ext == ".epub"+ is_pdf = ext == ".pdf"++ if not is_epub and not is_pdf:+ # Sniff magic bytes as fallback+ with open(input_path, "rb") as f:+ header = f.read(8)+ if header[:4] == b"%PDF":+ is_pdf = True+ elif header[:2] == b"PK": # ZIP magic → likely EPUB+ is_epub = True+ else:+ print(+ f"ERROR: Unsupported format '{ext}'. Supported: .pdf, .epub",+ file=sys.stderr,+ )+ sys.exit(1)- print(f"Extracting: {pdf_path}")- print("Trying pdftotext...", end=" ", flush=True)- text = extract_with_pdftotext(pdf_path)+ OUTPUT_DIR.mkdir(parents=True, exist_ok=True)- if text:- method = "pdftotext"- print("OK")+ if is_epub:+ print(f"Extracting EPUB: {input_path}")+ text, method = extract_epub(input_path)+ pages = count_epub_chapters(input_path)+ pages_label = "spine_items"else:- print("not available")- print("Trying PyPDF2...", end=" ", flush=True)- text = extract_with_pypdf2(pdf_path)+ print(f"Extracting PDF: {input_path}")+ print("Trying pdftotext...", end=" ", flush=True)+ text = extract_with_pdftotext(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(pdf_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"# Write full textOUTPUT_TEXT.write_text(text, encoding="utf-8")- pages = count_pages(pdf_path)tokens = estimate_tokens(text)structure = detect_structure(text)- file_size_mb = os.path.getsize(pdf_path) / (1024 * 1024)+ file_size_mb = os.path.getsize(input_path) / (1024 * 1024)metadata = {- "source_file": str(Path(pdf_path).resolve()),- "filename": Path(pdf_path).name,+ "source_file": str(Path(input_path).resolve()),+ "filename": Path(input_path).name,+ "format": "epub" if is_epub else "pdf","extraction_method": method,"file_size_mb": round(file_size_mb, 2),- "pages": pages,+ pages_label: pages,"chars": len(text),"words": len(text.split()),"estimated_tokens": tokens,@@ -187,9 +340,11 @@ def main():OUTPUT_META.write_text(json.dumps(metadata, indent=2, ensure_ascii=False))+ page_line = f" {'Spine items' if is_epub else 'Pages'}: {pages}"print(f"\n📖 Extraction complete:")+ print(f" Format : {'EPUB' if is_epub else 'PDF'}")print(f" Method : {method}")- print(f" Pages : {pages}")+ print(page_line)print(f" Words : {len(text.split()):,}")print(f" Tokens : ~{tokens // 1000}K")print(f" Chapters: {structure['chapters_detected']} detected")