Book‑to‑Skill Supported Document Formats: The Complete List of File Types You Can Convert

Book‑to‑skill supports PDF, DOCX, EPUB, HTML/HTM, RTF, plain‑text, and any e‑book format recognized by Calibre (including AZW3, MOBI, FB2, LIT, CHM, and DJVU).

Book‑to‑skill is an open‑source Python tool that transforms source documents into a structured Skill data model. Each supported format has a dedicated parser module under book_to_skill/parsers/, and the CLI automatically routes files to the correct extractor based on their extension. Below is a complete breakdown of every format, its implementation, and how to use it.

---

PDF Documents (.pdf)

PDF support is the most robust, with four fallback extraction methods in book_to_skill/parsers/pdf.py:

• extract_with_pdftotext — fastest, uses the Poppler pdftotext binary
• extract_with_pypdf — pure‑Python fallback
• extract_with_pdfminer — handles complex layouts
• extract_with_docling — optional ML‑based extraction for scanned documents

The parser tries each method in order until clean text is returned, with de‑hyphenation applied to fix line breaks.

from book_to_skill import cli

pdf_text = cli.convert_file("research_paper.pdf")
print(len(pdf_text))  # total characters extracted

python -m book_to_skill research_paper.pdf > output.txt

---

Microsoft Word Documents (.docx)

Word files are parsed using python‑docx in book_to_skill/parsers/docx.py. The extract_with_docx function iterates through document paragraphs and tables, preserving reading order.

python -m book_to_skill contract.docx > contract.txt

---

EPUB E‑books (.epub)

EPUB parsing happens in book_to_skill/parsers/epub.py via extract_with_epub. The parser reads the ZIP archive, parses OPF metadata, and extracts XHTML content using lxml.

python -m book_to_skill novel.epub > novel.txt

---

Web Pages (.html, .htm)

HTML files are processed by extract_with_html in book_to_skill/parsers/html.py. Tags are stripped and whitespace normalized to produce readable plain text.

python -m book_to_skill article.html > article.txt

---

Rich Text Format (.rtf)

RTF support uses pyrtf‑parser through extract_with_rtf in book_to_skill/parsers/rtf.py.

python -m book_to_skill notes.rtf > notes.txt

---

Plain Text Files (.txt and Others)

UTF‑8, UTF‑16, and UTF‑32 text files are handled by read_text_file in book_to_skill/parsers/text.py, with automatic BOM detection and removal.

python -m book_to_skill README.txt > README_clean.txt

---

Calibre‑Supported E‑book Formats (Catch‑All)

The most powerful parser is book_to_skill/parsers/calibre.py, which delegates to Calibre's ebook‑convert CLI. This enables conversion of dozens of proprietary formats without dedicated parsers:

Extension	Format
.azw3, .azw	Amazon Kindle
.mobi	Mobipocket
.fb2	FictionBook 2
.lit	Microsoft Reader
.chm	Compiled HTML Help
.djvu	DjVu
.prc, .pdb	Palm/Plucker

Use extract_with_calibre programmatically or simply pass any supported file to the CLI:

python -m book_to_skill manuscript.azw3 > manuscript.txt
python -m book_to_skill reference.chm > reference.txt

---

How Format Selection Works

The dispatcher logic in book_to_skill/cli.py maps file extensions to parser functions:

Extension	Parser Module	Function
.pdf	pdf.py	extract_with_pdftotext (with fallbacks)
.docx	docx.py	extract_with_docx
.epub	epub.py	extract_with_epub
.html, .htm	html.py	extract_with_html
.rtf	rtf.py	extract_with_rtf
.txt	text.py	read_text_file
anything else	calibre.py	extract_with_calibre

If an extension is unrecognized, the CLI automatically falls back to Calibre.

---

Summary

• Core formats: PDF, DOCX, EPUB, HTML/HTM, RTF, plain‑text — each with a dedicated parser in book_to_skill/parsers/
• Extended formats: Any Calibre‑compatible e‑book (AZW3, MOBI, FB2, LIT, CHM, DJVU, and more) via calibre.py
• Automatic routing: cli.py dispatches files by extension, falling back to Calibre when needed
• Uniform output: All parsers return clean, de‑hyphenated text ready for Skill model ingestion

---

Frequently Asked Questions

How does book‑to‑skill handle corrupted or scanned PDFs?

Scanned PDFs without embedded text are processed by extract_with_docling in pdf.py, which uses ML‑based OCR if the Docling library is installed. If Docling fails, the parser returns an empty result rather than garbled text, allowing upstream code to flag the file for manual review.

Can I convert password‑protected documents?

No. The PDF, DOCX, and Calibre parsers do not implement decryption. Password‑protected files will raise an extraction error that propagates to the CLI with a clear message indicating the failure reason.

Is there a file size limit?

There is no hardcoded limit in book‑to‑skill itself. However, Calibre's ebook‑convert may time out on extremely large archives (>500 MB), and pdftotext can struggle with PDFs containing millions of vector objects. For large documents, consider splitting them before conversion.

What encoding does the output use?

All parsers return Python str objects (UTF‑8 internally). When writing to files via the CLI, the encoding defaults to UTF‑8. The text.py parser specifically handles UTF‑8, UTF‑16, and UTF‑32 BOMs to prevent mojibake in source files.

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