How book-to-skill Handles MOBI, AZW, and AZW3 Document Formats

book-to-skill treats all MOBI-family files as Calibre-only formats: it checks for the ebook-convert binary on your system PATH, converts the document to plain text via an external shell call, and returns the extracted content as a string.

The virgiliojr94/book-to-skill repository is a Python CLI tool that converts books into structured skill assessments. For proprietary Amazon formats like MOBI, AZW, and AZW3, the project takes a distinct dependency-driven approach rather than implementing native parsers. This article explains exactly how the extraction pipeline works, what system requirements you need, and where the relevant code lives.

Supported MOBI-Family Extensions

In book_to_skill/config.py, the project defines a frozen set that explicitly enumerates which formats require Calibre processing:

# Lines 39-44 of config.py

CALIBRE_EBOOK_EXTENSIONS: frozenset[str] = frozenset([
    ".mobi",
    ".azw",
    ".azw3",
])

These three extensions are the only formats in book-to-skill that delegate to an external binary rather than pure-Python libraries.

Dependency Verification in the Extraction Pipeline

The central entry point for all document handling is utils.extract(). When processing a file, it routes MOBI-family documents through a strict dependency check before attempting conversion.

From book_to_skill/utils.py at lines 823-827:

if ext in CALIBRE_EBOOK_EXTENSIONS and not shutil.which("ebook-convert"):
    raise ExtractionError(
        "MOBI/AZW/AZW3 extraction requires Calibre's ebook-convert command. "
        "Install Calibre and ensure ebook-convert is on PATH, then rerun this command."
    )

This check runs before any file operation occurs. If the binary is missing, the user receives an immediate, actionable error message.

The Calibre Conversion Implementation

Once dependencies pass, control flows to extract_with_ebook_convert() in book_to_skill/parsers/calibre.py. The function executes a subprocess call to Calibre's command-line tool:

# Lines 13-24 of calibre.py (conceptual structure)

def extract_with_ebook_convert(input_path: Path) -> str:
    output_path = OUTPUT_DIR / "ebook-convert-output.txt"
    
    # Execute external conversion

    subprocess.run(
        ["ebook-convert", str(input_path), str(output_path)],
        check=True,
        capture_output=True
    )
    
    # Read and return extracted plain text

    return output_path.read_text(encoding="utf-8")

The conversion produces an intermediate text file that the parser reads into memory and returns as the document's content. This plain-text output then feeds into the same downstream processing pipeline used for EPUBs, PDFs, and other natively-supported formats.

Error Handling for Failed Conversions

The Calibre wrapper includes defensive checks for command failures and empty output. If ebook-convert exits non-zero or produces no text, the parser logs a warning and returns None, which propagates up as an ExtractionError with diagnostic context.

System Requirements for MOBI/AZW/AZW3 Support

Per book_to_skill/dependencies.py at lines 68-70, Calibre is a hard requirement for these formats—there is no fallback parser. To use book-to-skill with Amazon ebook formats:

1. Download and install Calibre from https://calibre-ebook.com/
2. Verify ebook-convert is available on your system PATH
3. Re-run the extraction command

Code Examples

Basic CLI extraction

# Successful extraction

$ book-to-skill extract novel.mobi
Extracting MOBI: novel.mobi
✅ Extraction succeeded (method: ebook-convert)

Missing dependency error

$ book-to-skill extract textbook.azw3
✖ Extraction failed
MOBI/AZW/AZW3 extraction requires Calibre's ebook-convert command.
Install Calibre and ensure ebook-convert is on PATH, then rerun this command.

Programmatic usage with guard

from pathlib import Path
import shutil
from book_to_skill.utils import extract

# Pre-flight check for MOBI-family files

target = Path("documentation.azw3")

if target.suffix in {".mobi", ".azw", ".azw3"}:
    if not shutil.which("ebook-convert"):
        raise RuntimeError("Install Calibre to process this file")

text, metadata = extract(target)
print(f"Extracted {len(text)} characters from {metadata.title}")

Where the Logic Lives

File	Purpose
book_to_skill/config.py	Defines CALIBRE_EBOOK_EXTENSIONS (lines 39-44)
book_to_skill/utils.py	Routes MOBI files and validates ebook-convert availability (lines 823-827)
book_to_skill/parsers/calibre.py	Implements extract_with_ebook_convert() conversion wrapper
book_to_skill/dependencies.py	Documents hard Calibre requirement (lines 68-70)
tests/test_book_to_skill.py	Marks MOBI as required format with no fallback (line 1570)

Summary

• MOBI, AZW, and AZW3 require Calibre: These formats are explicitly excluded from native Python parsing
• Dependency check runs first: The code validates ebook-convert on PATH before any file operation
• External conversion to plain text: ebook-convert produces a temporary text file that the parser ingests
• Clear error messaging: Missing dependencies trigger immediate, actionable exceptions rather than silent failures
• No built-in fallback: Unlike EPUB or PDF handling, there is no alternative parser for MOBI-family files

Frequently Asked Questions

What happens if I try to extract a MOBI file without Calibre installed?

book-to-skill raises an ExtractionError immediately before touching the file, directing you to install Calibre and ensure ebook-convert is on your system PATH. The error originates from book_to_skill/utils.py at line 823-827.

Can I use a different MOBI parser instead of Calibre?

No. The codebase hard-codes CALIBRE_EBOOK_EXTENSIONS in config.py and explicitly routes these extensions to extract_with_ebook_convert() in calibre.py. There is no pluggable parser interface for MOBI-family formats.

Does the conversion preserve formatting or just extract plain text?

The ebook-convert call outputs plain text only. Any rich formatting, images, or structural metadata from the original MOBI/AZW/AZW3 file is lost during conversion. The result is a UTF-8 encoded string suitable for NLP processing, not layout preservation.

Is Calibre required for other ebook formats like EPUB or PDF?

No. EPUB and PDF use native Python libraries (ebooklib, PyMuPDF, etc.) without external binary dependencies. Only MOBI, AZW, and AZW3 require Calibre according to dependencies.py.

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