Analyze Only vs Full Conversion in Book-to-Skill: Pipeline Modes Explained

Full Conversion runs all ten pipeline steps to generate a complete skill directory with chapters and documentation, while Analyze Only halts after extraction to provide a preview of frameworks and techniques found—without creating any skill files.

The virgiliojr94/book-to-skill project processes technical documents through a fixed ten-step pipeline that transforms books into structured skill packages. Understanding the difference between Analyze Only and Full Conversion modes helps you choose between rapid content inspection and complete skill generation. Both modes execute the same initial validation and extraction logic defined in SKILL.md, but diverge significantly in output format and resource consumption.

Pipeline Execution: Steps 0-3 vs Steps 0-9

According to the specification in SKILL.md, Book-to-Skill implements a strict pipeline numbered 0 through 9. The mode you select determines exactly how many stages execute.

Full Conversion: The Complete Workflow

When running Full Conversion—the default behavior when no special flag is provided—the engine executes Steps 0 through 9:

1. Out-of-scope check
2. Input validation
3. Content-type detection
4. Content extraction
5. Analysis
6. Generation of chapters
7. Glossary generation
8. Patterns extraction
9. Cheatsheet creation
10. Final SKILL.md assembly

Analyze Only: Extraction and Validation Only

Analyze Only executes only Steps 0 through 3:

• Out-of-scope check
• Input validation
• Content-type detection
• Content extraction

The pipeline terminates immediately after the extraction stage, returning a structured extraction report that lists frameworks, principles, and techniques detected in the source material. No generation steps run, and no skill files are written to disk.

This architecture keeps the extraction logic DRY (Don't Repeat Yourself) in scripts/extract.py and book_to_skill/parsers/*, allowing both modes to share identical raw text extraction before the CLI decides whether to invoke downstream generation steps.

Output Comparison: Extraction Report vs Skill Package

The primary distinction between modes lies in deliverables and file system impact.

Full Conversion produces a complete skill package containing:

• SKILL.md (the master skill file)
• chapters/ directory with individual markdown files
• Glossary, patterns, and cheatsheet documentation

Analyze Only produces only a structured extraction report summarizing detected technical content. As implemented in book_to_skill/cli.py, this mode generates no skill files whatsoever, making it ideal for previewing content before committing computational resources to full generation.

Performance and Token Usage Implications

Analyze Only consumes significantly fewer tokens and executes faster because it terminates after Step 3. Full Conversion incurs higher token usage and longer processing times due to the AI-driven generation steps (Steps 4-9) that create multiple structured output files.

How to Invoke Each Mode via CLI

The mode selection logic resides in book_to_skill/cli.py, which parses arguments to determine which pipeline steps to orchestrate.

Default Full Conversion

book-to-skill path/to/document

This runs the complete pipeline through Step 9 and creates a full skill directory with all generated assets.

Explicit Analyze Only

book-to-skill path/to/document --mode analyze

# Or using the short alias

book-to-skill path/to/document -a

These commands execute only Steps 0-3 and print the extraction report to stdout.

Both calls ultimately invoke scripts/extract.py for document parsing, but the CLI controls whether to continue with generation based on the mode flag.

Summary

• Full Conversion (default) executes Steps 0-9, generating a complete skill package with SKILL.md, chapters, and reference materials.
• Analyze Only (--mode analyze or -a) stops at Step 3, providing an extraction report without creating skill files.
• Both modes share identical extraction logic in Steps 0-3, ensuring consistent content detection regardless of selected mode.
• Analyze Only reduces token costs and processing time by skipping AI generation phases.
• The mode decision logic in book_to_skill/cli.py determines which downstream steps to invoke after scripts/extract.py completes.

Frequently Asked Questions

What are the specific pipeline steps that run in Analyze Only mode?

Analyze Only executes Steps 0 through 3 only: out-of-scope checking, input validation, content-type detection, and content extraction. These steps validate the input document and extract raw text using the parsers in book_to_skill/parsers/*, but stop before any AI analysis or file generation occurs.

Can I switch from Analyze Only to Full Conversion without re-extracting?

Yes. Since both modes share the same extraction logic in Steps 0-3, the raw text extraction remains identical. If you preserve the intermediate data generated during Analyze Only, you can proceed to Full Conversion without re-parsing the source document, as the extraction stage produces the same intermediate representation regardless of mode.

Does Analyze Only mode support all document formats that Full Conversion handles?

Yes. Analyze Only utilizes the same scripts/extract.py module and format-specific parsers (PDF, EPUB, DOCX, HTML) located in book_to_skill/parsers/ as Full Conversion. The mode flag only affects whether generation steps run after extraction completes, not which parsers are available.

When should I use Analyze Only instead of running the full conversion immediately?

Use Analyze Only when you want to preview what frameworks and techniques will be extracted before committing to the higher token costs and longer processing time of Full Conversion. It allows you to review the structured extraction report and verify content suitability before generating the final skill files.

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