Can book-to-skill Handle Image-Rich EPUBs? A Deep Dive into the Parser

No—book-to-skill is a text-only extractor that detects images but does not extract or embed them in the generated skill output.

The book-to-skill repository provides deterministic EPUB parsing for creating structured skills, but its architecture explicitly excludes binary resource handling. According to the source code in virgiliojr94/book-to-skill, the EPUB parser processes XHTML content for textual narrative while flagging—not processing—embedded images.

How the EPUB Parser Handles Image Content

The core parsing logic resides in book_to_skill/parsers/epub.py. When processing an EPUB archive, the parser walks through XHTML documents and applies a text-first extraction strategy.

Image Detection Without Extraction

The parser identifies <img> tags during traversal and sets an internal flag, but it never extracts the actual image files from the EPUB container:

from book_to_skill.parsers.epub import EPUBParser

parser = EPUBParser("image-heavy-book.epub")
parser.parse()

# The parser records image presence but returns no image data

print("Images present:", parser.has_images)  # → True

print("Image count:", parser.image_count)    # → Number of <img> tags found

This design choice reflects the tool's deterministic philosophy: reproducible text output takes precedence over multimedia fidelity.

Extracting Skills from Image-Rich EPUBs

The high-level extract() function follows the same text-only pattern. Any visual content in the source EPUB is intentionally omitted:

from book_to_skill import extract

# EPUB with diagrams, photos, or illustrations

epub_path = "technical-manual.epub"

skill = extract(epub_path)

# Output contains structured text only

print(skill.content)        # Plain-text narrative

print(skill.metadata)       # Contains "contains_images": True

The generated skill follows the schema defined in SKILL.md, which specifies no image fields in the output structure.

Verifying Image Reporting Behavior

The test suite confirms this limitation. Run the dedicated image-reporting test to observe the parser's behavior:

pytest tests/test_epub_image_reporting.py -v

This test validates that:

• has_images is set to True when <img> tags are encountered
• No image binary data is returned in the parse result
• Image file paths from src attributes are logged but not resolved

Why Images Are Excluded

The architectural decision stems from docs/architecture.md, which positions book-to-skill as a deterministic text extractor optimized for downstream language model consumption. Key constraints include:

• Determinism: Binary extraction would introduce variability based on image formats and encoding
• Schema simplicity: The skill format prioritizes searchable, token-efficient text
• Scope boundary: Image handling would require additional dependencies (PIL, image hash libraries) and storage infrastructure

Workarounds for Image-Rich Sources

If your workflow requires visual content from EPUBs, you must extend the parser manually:

1. Extract images separately using zipfile or ebooklib to pull resources from the EPUB's OEBPS/Images/ directory
2. Store images externally in a media folder with deterministic naming (e.g., hash-based filenames)
3. Reference images in skill markup by extending the skill schema to include image URLs or base64 data
4. Use alt text fallback where the parser already captures alt attributes from <img> tags into the text stream

Summary

• book-to-skill detects images via has_images flag in EPUBParser but does not extract them
• Generated skills contain only text, following the schema in SKILL.md with no image fields
• The parser source at book_to_skill/parsers/epub.py shows explicit exclusion of binary resource handling
• Extension required: Image support demands custom modifications to both parser and skill schema

Frequently Asked Questions

Does book-to-skill extract alt text from images?

Yes. When the parser encounters <img alt="description"> tags, the alt attribute text is included in the extracted content stream as plain text. This preserves descriptive context even when the visual asset is discarded.

Can I modify book-to-skill to include images in skills?

Yes, but it requires substantive changes. You would need to extend EPUBParser.parse() to extract binary resources from the EPUB zip structure, modify the skill schema in SKILL.md to accommodate image references, and update serialization logic. No plugin hooks exist for this currently.

What happens to EPUBs where images contain critical information?

The text-only output will be incomplete for such sources. Diagram captions, figure references, and surrounding textual context are preserved, but visual data (charts, photographs, illustrations) is lost. Evaluate source material before processing; image-dense textbooks may need alternative extraction pipelines.

Is there a configuration flag to enable image extraction?

No. The extract() function and EPUBParser class expose no parameters for image handling. This is architectural, not configurable—the deterministic text focus is embedded in the design principles documented in docs/architecture.md.

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