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
Support additional document formats
zuwasi9cf57458034f
diff --git a/SKILL.md b/SKILL.mdindex 79ca3c2..c3d7f2d 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,6 +1,6 @@---name: book-to-skill-description: "Converts a technical book (PDF or EPUB) into a structured agent skill, extracting frameworks, mental models, principles, techniques, and anti-patterns. Use when the user wants to study a book through Amp or Claude Code, apply an author's frameworks while working, or build a reusable knowledge base from any PDF or EPUB."+description: "Converts books and documents (PDF, EPUB, DOCX, HTML, Markdown, plain text, RTF, MOBI/AZW with Calibre) into structured agent skills, extracting frameworks, mental models, principles, techniques, and anti-patterns. Use when the user wants to study a document through Amp or Claude Code, apply an author's frameworks while working, or build a reusable knowledge base from a file."compatibility: "Amp skill directories (.agents/skills, ~/.config/agents/skills, ~/.config/amp/skills) and Claude Code skill directories (~/.claude/skills)."allowed-tools:- shell_command@@ -8,7 +8,7 @@ allowed-tools:- Write- Glob- Grep-argument-hint: <path-to-pdf-or-epub> [skill-name-slug]+argument-hint: <path-to-document> [skill-name-slug]---# Book-to-Skill Converter@@ -37,7 +37,7 @@ Books contain crystallized expertise: frameworks, principles, and techniques thaThree paths available. Route based on what the user asks:### 1. Full Conversion (Default)-**Trigger:** User provides a PDF path without special instructions+**Trigger:** User provides a supported document path without special instructions**Action:** Run all steps below (Steps 0–9)**Output:** Complete skill with SKILL.md, chapters/, glossary, patterns, cheatsheet@@ -68,8 +68,8 @@ Generated skills should default to `~/.config/agents/skills/` for Amp unless the## Step 0 — Out-of-scope check-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]`"+If the argument is NOT a path to a supported document file, stop and respond:+> "book-to-skill requires a supported document path. Usage: `book-to-skill /path/to/book.pdf [skill-name]`, `book-to-skill /path/to/book.epub [skill-name]`, or another supported format such as `.docx`, `.md`, `.txt`, `.html`, `.rtf`, `.mobi`, or `.azw3`."Throughout the workflow, treat the first argument as `BOOK_PATH` and the optional second argument as `SKILL_NAME`.@@ -79,10 +79,13 @@ Throughout the workflow, treat the first argument as `BOOK_PATH` and the optiona```bashtest -f "$BOOK_PATH" && echo "FILE_OK" || echo "FILE_NOT_FOUND: $BOOK_PATH"-file "$BOOK_PATH" | grep -iE "pdf|epub|zip" && echo "FORMAT_OK" || echo "FORMAT_UNKNOWN"+case "${BOOK_PATH##*.}" in+ pdf|PDF|epub|EPUB|docx|DOCX|txt|TXT|md|MD|markdown|MARKDOWN|rst|RST|adoc|ADOC|asciidoc|ASCIIDOC|html|HTML|htm|HTM|rtf|RTF|mobi|MOBI|azw|AZW|azw3|AZW3) echo "FORMAT_OK" ;;+ *) echo "FORMAT_UNKNOWN" ;;+esac```-Check the file extension (`.pdf` or `.epub`) or magic bytes (`%PDF` or `PK` zip header).+Check the file extension (`.pdf`, `.epub`, `.docx`, `.txt`, `.md`, `.markdown`, `.rst`, `.adoc`, `.html`, `.htm`, `.rtf`, `.mobi`, `.azw`, `.azw3`) or magic bytes (`%PDF` or `PK` zip header for EPUB/DOCX).If the file is not found or the format is not supported, stop with a clear error message listing supported formats.@@ -107,11 +110,11 @@ Store the answer as `BOOK_TYPE`:> "📐 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."+> "📄 Text mode selected — using the fastest suitable extractor for this file type. Plain text/Markdown/HTML are usually ready in seconds; PDFs use pdftotext when available."----## Step 2 — Extract text from PDF or EPUB+## Step 2 — Extract text from the source documentRun the extraction script, passing the book type:@@ -142,8 +145,14 @@ fi"$PYTHON_BIN" "$SCRIPT_PATH" "$BOOK_PATH" --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)+- PDF `--mode technical` → uses Docling (layout-aware, preserves tables and code blocks as markdown)+- PDF `--mode text` → uses pdftotext → PyPDF2 → pdfminer fallback chain (fast, plain text)+- EPUB → uses ebooklib + BeautifulSoup4, then stdlib ZIP/HTML fallback+- DOCX → uses python-docx, then stdlib ZIP/XML fallback+- TXT/Markdown/reStructuredText/AsciiDoc → reads directly as text+- HTML → uses BeautifulSoup4, then stdlib HTML fallback+- RTF → uses striprtf, then a basic regex fallback+- MOBI/AZW/AZW3 → uses Calibre `ebook-convert` when installedThis creates:- `<tempdir>/book_skill_work/full_text.txt` — full extracted text@@ -158,8 +167,8 @@ Read the `output_text` path in `<tempdir>/book_skill_work/metadata.json` to undeRead `<tempdir>/book_skill_work/metadata.json` and present the user with an estimate **before doing any generation**:```-📖 Book detected: <filename> (<format: PDF or EPUB>)-📄 Pages/Spine items: ~<N> | Words: ~<N> | Source tokens: ~<N>K+📖 Source detected: <filename> (<format>)+📄 Pages/Spine items/Sections: ~<N> | Words: ~<N> | Source tokens: ~<N>K💰 Estimated token cost (Full Conversion):Input (book reading + prompts): ~<N>K tokensdiff --git a/scripts/extract.py b/scripts/extract.pyindex 56e114f..bd48d04 100644--- a/scripts/extract.py+++ b/scripts/extract.py@@ -1,6 +1,6 @@#!/usr/bin/env python3"""-Extract text from a PDF or EPUB file for book-to-skill processing.+Extract text from a document file for book-to-skill processing.PDF extraction tries methods in order:1. pdftotext (poppler-utils) — best quality@@ -11,6 +11,13 @@ EPUB extraction tries methods in order:1. ebooklib + BeautifulSoup4 — best quality2. zipfile + html.parser — stdlib fallback (no extra deps)+Other supported formats:+ - Plain text / Markdown / reStructuredText / AsciiDoc — direct read+ - HTML — BeautifulSoup4 if available, then stdlib html.parser+ - DOCX — python-docx if available, then stdlib ZIP/XML fallback+ - RTF — striprtf if available, then regex fallback+ - MOBI/AZW/AZW3 — Calibre ebook-convert if available+Outputs:<tempdir>/book_skill_work/full_text.txt — full extracted text<tempdir>/book_skill_work/metadata.json — stats and metadata@@ -41,11 +48,161 @@ OUTPUT_META = OUTPUT_DIR / "metadata.json"WORDS_PER_TOKEN = 0.75 # approximate+TEXT_EXTENSIONS = {".txt", ".text", ".md", ".markdown", ".rst", ".adoc", ".asciidoc"}+HTML_EXTENSIONS = {".html", ".htm", ".xhtml"}+CALIBRE_EBOOK_EXTENSIONS = {".mobi", ".azw", ".azw3"}+SUPPORTED_EXTENSIONS = {+ ".pdf", ".epub", ".docx", ".rtf",+ *TEXT_EXTENSIONS,+ *HTML_EXTENSIONS,+ *CALIBRE_EBOOK_EXTENSIONS,+}+def estimate_tokens(text: str) -> int:return int(len(text.split()) / WORDS_PER_TOKEN)+def supported_formats_message() -> str:+ return ", ".join(sorted(SUPPORTED_EXTENSIONS))+++def read_text_file(path: str) -> str | None:+ for encoding in ("utf-8-sig", "utf-8", "cp1252", "latin-1"):+ try:+ return Path(path).read_text(encoding=encoding)+ except UnicodeDecodeError:+ continue+ except Exception:+ return None+ return None+++def extract_html_content(raw_html: str) -> str:+ try:+ from bs4 import BeautifulSoup+ soup = BeautifulSoup(raw_html, "html.parser")+ for element in soup(["script", "style", "head"]):+ element.decompose()+ return soup.get_text(separator="\n")+ except ImportError:+ parser = _HTMLTextExtractor()+ parser.feed(raw_html)+ return parser.get_text()+++def extract_html_file(path: str) -> str | None:+ raw = read_text_file(path)+ if raw is None:+ return None+ return extract_html_content(raw)+++def extract_docx_with_python_docx(docx_path: str) -> str | None:+ try:+ import docx+ document = docx.Document(docx_path)+ parts = [paragraph.text for paragraph in document.paragraphs if paragraph.text]+ for table in document.tables:+ for row in table.rows:+ cells = [cell.text.strip() for cell in row.cells]+ if any(cells):+ parts.append("\t".join(cells))+ return "\n".join(parts)+ except ImportError:+ return None+ except Exception:+ return None+++def extract_docx_with_zipfile(docx_path: str) -> str | None:+ try:+ import xml.etree.ElementTree as ET++ with zipfile.ZipFile(docx_path) as zf:+ xml_bytes = zf.read("word/document.xml")+ root = ET.fromstring(xml_bytes)+ namespace = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"+ parts: list[str] = []+ for paragraph in root.iter(f"{namespace}p"):+ texts = [node.text for node in paragraph.iter(f"{namespace}t") if node.text]+ if texts:+ parts.append("".join(texts))+ return "\n".join(parts) if parts else None+ except Exception:+ return None+++def extract_docx(docx_path: str) -> tuple[str, str]:+ print("Trying python-docx...", end=" ", flush=True)+ text = extract_docx_with_python_docx(docx_path)+ if text and text.strip():+ print("OK")+ return text, "python-docx"++ print("not available")+ print("Trying stdlib DOCX parser...", end=" ", flush=True)+ text = extract_docx_with_zipfile(docx_path)+ if text and text.strip():+ print("OK")+ return text, "zipfile-docx"++ print("FAILED")+ print(+ "\nERROR: Could not extract text from DOCX.\n"+ "Install python-docx for best results:\n"+ " pip3 install python-docx",+ file=sys.stderr,+ )+ sys.exit(1)+++def strip_rtf_fallback(raw: str) -> str:+ raw = re.sub(r"\\'[0-9a-fA-F]{2}", " ", raw)+ raw = re.sub(r"\\par[d]?", "\n", raw)+ raw = re.sub(r"\\tab", "\t", raw)+ raw = re.sub(r"\\[a-zA-Z]+-?\d* ?", "", raw)+ raw = raw.replace("{", "").replace("}", "")+ return html.unescape(raw)+++def extract_rtf(rtf_path: str) -> tuple[str, str]:+ raw = read_text_file(rtf_path)+ if raw is None:+ print("ERROR: Could not read RTF file", file=sys.stderr)+ sys.exit(1)++ try:+ from striprtf.striprtf import rtf_to_text+ text = rtf_to_text(raw)+ if text.strip():+ return text, "striprtf"+ except ImportError:+ pass+ except Exception:+ pass++ return strip_rtf_fallback(raw), "rtf-regex"+++def extract_with_ebook_convert(input_path: str) -> str | None:+ if not shutil.which("ebook-convert"):+ return None+ output_path = OUTPUT_DIR / "ebook-convert-output.txt"+ try:+ result = subprocess.run(+ ["ebook-convert", input_path, str(output_path)],+ capture_output=True, text=True, timeout=300+ )+ if result.returncode == 0 and output_path.exists():+ text = output_path.read_text(encoding="utf-8", errors="replace")+ if text.strip():+ return text+ except Exception:+ pass+ return None++def extract_with_pdftotext(pdf_path: str) -> str | None:if not shutil.which("pdftotext"):return None@@ -277,7 +434,8 @@ def extract_with_docling(pdf_path: str) -> str | None:def main():if len(sys.argv) < 2:- print("Usage: extract.py <path-to-pdf-or-epub> [--mode technical|text]", file=sys.stderr)+ print("Usage: extract.py <path-to-document> [--mode technical|text]", file=sys.stderr)+ print(f"Supported formats: {supported_formats_message()}", file=sys.stderr)sys.exit(1)input_path = sys.argv[1]@@ -295,33 +453,47 @@ def main():print(f"ERROR: File not found: {input_path}", file=sys.stderr)sys.exit(1)- ext = Path(input_path).suffix.lower()- is_epub = ext == ".epub"- is_pdf = ext == ".pdf"+ input_file = Path(input_path)+ ext = input_file.suffix.lower()+ document_format = ext.lstrip(".")- if not is_epub and not is_pdf:- # Sniff magic bytes as fallback+ # Sniff magic bytes as a fallback for files without useful extensions.+ if ext not in SUPPORTED_EXTENSIONS: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+ ext = ".pdf"+ document_format = "pdf"+ elif header[:2] == b"PK":+ with zipfile.ZipFile(input_path) as zf:+ names = set(zf.namelist())+ if "mimetype" in names and zf.read("mimetype").startswith(b"application/epub"):+ ext = ".epub"+ document_format = "epub"+ elif "word/document.xml" in names:+ ext = ".docx"+ document_format = "docx"+ else:+ print(+ f"ERROR: Unsupported ZIP-based format '{input_file.name}'. Supported: {supported_formats_message()}",+ file=sys.stderr,+ )+ sys.exit(1)else:print(- f"ERROR: Unsupported format '{ext}'. Supported: .pdf, .epub",+ f"ERROR: Unsupported format '{ext or '<none>'}'. Supported: {supported_formats_message()}",file=sys.stderr,)sys.exit(1)OUTPUT_DIR.mkdir(parents=True, exist_ok=True)- if is_epub:+ if ext == ".epub":print(f"Extracting EPUB: {input_path}")text, method = extract_epub(input_path)pages = count_epub_chapters(input_path)pages_label = "spine_items"- else:+ elif ext == ".pdf":print(f"Extracting PDF: {input_path}")if extraction_mode == "technical":print("Mode: technical — using Docling (layout-aware)...", end=" ", flush=True)@@ -369,6 +541,52 @@ def main():pages = count_pages(input_path)pages_label = "pages"+ elif ext in TEXT_EXTENSIONS:+ print(f"Extracting text document: {input_path}")+ text = read_text_file(input_path)+ if text is None or not text.strip():+ print("ERROR: Could not read text document", file=sys.stderr)+ sys.exit(1)+ method = "plain-text"+ pages = 0+ pages_label = "sections"+ elif ext in HTML_EXTENSIONS:+ print(f"Extracting HTML: {input_path}")+ text = extract_html_file(input_path)+ if text is None or not text.strip():+ print("ERROR: Could not extract text from HTML", file=sys.stderr)+ sys.exit(1)+ method = "html-parser"+ pages = 0+ pages_label = "sections"+ elif ext == ".docx":+ print(f"Extracting DOCX: {input_path}")+ text, method = extract_docx(input_path)+ pages = 0+ pages_label = "sections"+ elif ext == ".rtf":+ print(f"Extracting RTF: {input_path}")+ text, method = extract_rtf(input_path)+ pages = 0+ pages_label = "sections"+ elif ext in CALIBRE_EBOOK_EXTENSIONS:+ print(f"Extracting ebook with Calibre: {input_path}")+ text = extract_with_ebook_convert(input_path)+ if text is None or not text.strip():+ print(+ f"ERROR: Could not extract text from {ext}. Install Calibre and ensure ebook-convert is on PATH.",+ file=sys.stderr,+ )+ sys.exit(1)+ method = "ebook-convert"+ pages = 0+ pages_label = "sections"+ else:+ print(+ f"ERROR: Unsupported format '{ext}'. Supported: {supported_formats_message()}",+ file=sys.stderr,+ )+ sys.exit(1)# Write full textOUTPUT_TEXT.write_text(text, encoding="utf-8")@@ -380,7 +598,7 @@ def main():metadata = {"source_file": str(Path(input_path).resolve()),"filename": Path(input_path).name,- "format": "epub" if is_epub else "pdf",+ "format": document_format,"extraction_method": method,"extraction_mode": extraction_mode,"file_size_mb": round(file_size_mb, 2),@@ -395,17 +613,22 @@ 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'}")+ page_label = {+ "spine_items": "Spine items",+ "pages": "Pages",+ "sections": "Sections",+ }.get(pages_label, pages_label.replace("_", " ").title())+ page_line = f" {page_label}: {pages}"+ print("\nExtraction complete:")+ print(f" Format : {document_format.upper()}")print(f" Method : {method}")print(page_line)print(f" Words : {len(text.split()):,}")print(f" Tokens : ~{tokens // 1000}K")print(f" Chapters: {structure['chapters_detected']} detected")print(f" ToC : {'yes' if structure['has_toc'] else 'not detected'}")- print(f"\n Text → {OUTPUT_TEXT}")- print(f" Meta → {OUTPUT_META}")+ print(f"\n Text -> {OUTPUT_TEXT}")+ print(f" Meta -> {OUTPUT_META}")if __name__ == "__main__":