What Document Formats Does book-to-skill Support for Extraction?

book-to-skill supports five document formats for extraction: PDF, EPUB, DOCX, HTML, and plain text files, each handled by dedicated parser modules that convert source files into normalized UTF-8 text for skill generation.

The virgiliojr94/book-to-skill repository implements a modular parser architecture where each document type receives specialized handling. The extraction pipeline reads source files, cleans raw content, and emits a standardized full_text.txt output that feeds into Agent Skill generation.

Supported Document Formats for book-to-skill Extraction

The extractor processes five core formats through dedicated implementations in the book_to_skill/parsers/ directory.

PDF (Portable Document Format)

Files with the .pdf extension are processed by book_to_skill/parsers/pdf.py. This module uses either pypdf for metadata and page-by-page extraction or pdftotext for fast OCR-free text dumps. The parser automatically detects page numbers, footers, and boilerplate content for removal.

EPUB (E-book Format)

The .epub parser in book_to_skill/parsers/epub.py opens the ZIP archive structure and walks the internal OEBPS hierarchy. It extracts XHTML chapters while preserving chapter boundaries and concatenates them into linear text.

DOCX (Microsoft Word)

Microsoft Word documents (.docx) route through book_to_skill/parsers/docx.py. This implementation leverages python-docx or lower-level zipfile plus XML parsing to extract text runs, handling tables and footnotes appropriately.

HTML (Web Pages)

Web documents with .html or .htm extensions process through book_to_skill/parsers/html.py. The parser strips tags, scripts, and style blocks while respecting block-level semantics to preserve heading structures in the extracted text.

Plain Text

Raw .txt files pass through book_to_skill/parsers/plain.py (built-in). This parser reads files verbatim, normalizes Unicode characters, removes invisible control characters, and enforces UTF-8 encoding consistency.

How the Parser Selection Works

The scripts/extract.py CLI entry-point serves as the dispatch center for format detection. When you provide input files, the system inspects file extensions and maps them to the appropriate parser class. You can verify parser selection using the --debug flag to see which module handles your specific document.

Command-Line Extraction Examples

Process multiple formats simultaneously using the CLI:

book-to-skill extract \
    my-book.pdf \
    novel.epub \
    notes.txt \
    report.docx \
    page.html \
    --output-dir ./skill-output

Inspect parser selection for debugging:

book-to-skill extract my-book.pdf --debug

Programmatic Python API Usage

Import the extraction library directly in Python code:

from book_to_skill import extract

paths = [
    "my-book.pdf",
    "novel.epub",
    "notes.txt",
    "report.docx",
    "page.html",
]

full_text_path = extract(paths, mode="text")
print(full_text_path.read_text(encoding="utf-8"))

The extract() function accepts a list of paths and returns a Path object pointing to the generated full_text.txt file containing normalized content from all input documents.

Summary

• Five supported formats: PDF, EPUB, DOCX, HTML, and plain text
• Dedicated parsers: Each format has a specific implementation in book_to_skill/parsers/ (pdf.py, epub.py, docx.py, html.py, plain.py)
• CLI entry point: scripts/extract.py handles argument parsing and parser dispatch
• Output standardization: All parsers produce UTF-8 encoded full_text.txt regardless of input format
• Extension-based routing: File extensions determine parser selection automatically

Frequently Asked Questions

Does book-to-skill support scanned PDFs requiring OCR?

No. The PDF parser in book_to_skill/parsers/pdf.py relies on pypdf and pdftotext, which extract embedded text only. Scanned documents without text layers require external OCR processing before ingestion.

Can I add support for additional document formats?

Yes, but the architecture intentionally limits extensions to maintain determinism. Adding formats requires creating a new parser module in book_to_skill/parsers/ and updating the command-line dispatcher in scripts/extract.py to recognize the new file extension.

What encoding does book-to-skill use for extracted text?

All parsers output normalized UTF-8 encoded text. The plain-text parser in book_to_skill/parsers/plain.py specifically enforces UTF-8 consistency and removes invisible Unicode control characters during extraction.

How does the tool handle mixed format batches?

The CLI processes heterogeneous file lists automatically. Each file routes to its appropriate parser based on extension, and the system concatenates outputs into a single full_text.txt file in the specified output directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}