When to Use `--mode technical` for PDF Extraction in book-to-skill

Use the --mode technical flag when your PDF contains code blocks, tables, or structured technical content that must retain exact syntax and layout, accepting slower processing (~1.5 seconds per page) in exchange for structural fidelity.

The book-to-skill repository by virgiliojr94 provides a specialized extraction pipeline that processes PDFs into structured agent skills. By default, the tool interactively asks whether your source is technical or text-heavy, but you can override this behavior using the --mode flag to ensure precise handling of documentation, programming manuals, and reference materials.

What --mode technical Does

The book-to-skill extractor supports two distinct processing pathways that handle PDF content fundamentally differently.

Technical mode invokes Docling via the extract_with_docling function to convert PDFs into markdown while preserving tables, code blocks, and exact whitespace. This ensures that programming syntax, API schemas, and tabular data remain intact for downstream processing.

Text mode (the default when unspecified) uses fast, plain-text tools like pdftotext, pypdf, and pdfminer. While significantly faster, these tools strip structural elements and retain only the narrative flow, making them unsuitable for technical documentation.

According to the README.md, the skill "asks you whether the book is technical or text-heavy and picks the right tool automatically," but the --mode flag allows you to bypass this interactive selection when you already know your document type.

When to Choose Technical Mode Over Text Mode

Select --mode technical when your source material contains non-narrative elements that downstream agent skills must reference accurately.

Content Types That Require Technical Mode

Use technical extraction for:

• Programming manuals with code examples
• API reference documentation containing schemas
• Technical standards with specification tables
• Academic papers with complex mathematical layouts
• Any PDF where table structure conveys semantic meaning

The SKILL.md file indicates that technical books provide specialized Code Examples and Reference Tables sections, which rely on the exact markdown output that only Docling can generate. Without technical mode, these structural elements become garbled text, breaking the generated skill's utility.

Performance Trade-offs

Technical mode delivers accuracy at a significant speed cost. A benchmark documented in docs/performance.md reveals that processing a 103-page technical PDF takes approximately 164 seconds in technical mode versus only 48 seconds in text mode.

Additionally, technical sections receive higher token budgets (approximately 1,800 tokens) compared to prose-only sections (approximately 1,000 tokens), as defined in the skill generation logic. This allocation reflects the density of information in structured technical content.

How Technical Mode Works Internally

The extraction pipeline routes your request through three key components when --mode technical is specified.

Argument Parsing and Validation

In book_to_skill/utils.py, the parse_arguments function (lines 36-68) parses the --mode flag and validates the input. If you provide an unrecognized value, the system defaults to "text" mode, making explicit flags critical for technical extraction.

Extractor Selection

The PDF parser in book_to_skill/parsers/pdf.py (lines 45-46) implements the mode selection logic:

if extraction_mode == "technical":
    return extract_with_docling(str(pdf_path))

When the mode equals "technical", the pipeline bypasses the fast text extractors and initializes the Docling-based extractor instead.

Architectural Flow

As visualized in docs/architecture.md, the system makes a BOOK_TYPE decision (technical vs. text) that determines the entire downstream processing path. The docs/how-it-works.md file illustrates how the technical branch maintains document structure through to the final skill generation, while the text branch optimizes for narrative coherence.

Usage Examples

Force technical extraction when you know your document contains code or tables, bypassing the interactive prompt:

# Force technical extraction to preserve tables and code blocks

python -m book_to_skill extract path/to/manual.pdf --mode technical

Use text mode for speed when processing prose-heavy content:

# Fast extraction for novels or plain text documents

python -m book_to_skill extract path/to/book.pdf --mode text

Allow automatic detection when you're unsure of the content type:

# Interactive mode - the tool will ask whether the PDF is technical

python -m book_to_skill extract path/to/unknown.pdf

The entry point in scripts/extract.py forwards your --mode selection directly to the core utilities, ensuring consistent behavior across the extraction pipeline.

Summary

• Use --mode technical for PDFs containing code, tables, or structured layouts that must retain exact formatting
• Technical mode uses Docling via extract_with_docling and allocates ~1,800 tokens per section versus ~1,000 for text mode
• Expect processing times roughly 3x slower than text mode (benchmark: 164s vs 48s for 103 pages)
• The parse_arguments function in book_to_skill/utils.py handles CLI validation, defaulting to text mode if invalid input is provided
• Source files including book_to_skill/parsers/pdf.py and docs/performance.md document the implementation details and benchmarks

Frequently Asked Questions

How much slower is technical mode compared to text mode?

According to benchmarks in docs/performance.md, technical mode processes approximately 1.5 seconds per page, while text mode completes in roughly 0.47 seconds per page. For a 103-page document, this translates to approximately 164 seconds versus 48 seconds total processing time.

Can I switch modes after extraction has started?

No, the extraction mode is determined at the outset when book_to_skill/parsers/pdf.py selects the extractor function. Once the pipeline initializes either extract_with_docling or the fast text tools, you must restart the process with the correct --mode flag to change methodologies.

Why does technical mode get more tokens per section?

The skill generation logic in SKILL.md allocates higher token budgets (~1,800 tokens) to technical sections because code blocks and tables contain dense information that requires more context window space to represent accurately, whereas prose-only sections (~1,000 tokens) contain more redundant narrative text.

What happens if I don't specify a mode?

If you omit the --mode flag, the extraction script in scripts/extract.py triggers an interactive prompt that asks whether your book is technical or text-heavy, then routes the PDF through the appropriate pathway automatically. This behavior is documented in the repository's README.md.

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