Skip to content

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

Support additional document formats

zuwasi9cf57458034f
diff --git a/SKILL.md b/SKILL.md
index 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 tha
Three 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
```bash
test -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 document
Run 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 installed
This 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 unde
Read `<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 tokens
diff --git a/scripts/extract.py b/scripts/extract.py
index 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 quality
2. 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 text
OUTPUT_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__":