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

> Learn how book-to-skill processes MOBI, AZW, and AZW3 files. Discover its Calibre integration for seamless text extraction and content conversion. Optimize your e-book workflow today.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: internals
- Published: 2026-09-01

---

**`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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py), the project defines a frozen set that explicitly enumerates which formats require Calibre processing:

```python

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) at lines 823-827:

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/calibre.py). The function executes a subprocess call to Calibre's command-line tool:

```python

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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

```bash

# Successful extraction

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

```

### Missing dependency error

```bash
$ 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

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) | Defines `CALIBRE_EBOOK_EXTENSIONS` (lines 39-44) |
| [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) | Routes MOBI files and validates `ebook-convert` availability (lines 823-827) |
| [`book_to_skill/parsers/calibre.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/calibre.py) | Implements `extract_with_ebook_convert()` conversion wrapper |
| [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) | Documents hard Calibre requirement (lines 68-70) |
| [`tests/test_book_to_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/config.py) and explicitly routes these extensions to `extract_with_ebook_convert()` in [`calibre.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/dependencies.py).