Book-to-Skill Operational Modes: A Complete Guide to the 4 Extraction Workflows

The book-to-skill generator supports four operational modes—full conversion (default), analyze-only, generate-from-analysis, and update/fold-in—that control how documents are extracted and transformed into agent-compatible skills.

The virgiliojr94/book-to-skill repository provides a command-line tool for converting books, papers, and documents into structured AI agent skills. Understanding these book-to-skill operational modes enables precise control over the extraction pipeline, from one-shot conversions to incremental updates of existing skills.

The Four Book-to-Skill Operational Modes

The generator's behavior is determined by the --mode flag parsed in scripts/extract.py, which dispatches execution to distinct workflows based on your specific needs.

1. Full Conversion (Default Mode)

This is the standard operating mode when no --mode flag is specified. It performs a complete end-to-end pipeline: extracting the source document, analyzing the content, and immediately generating a finished SKILL.md file.

Use this mode when you want to convert a document to a skill in a single step without intermediate inspection.

/book-to-skill ~/books/awesome-book.pdf awesome-skill

2. Analyze-Only Mode

The analyze-only mode runs the document extractor and writes a detailed analysis report (analysis.md), then stops without generating the final skill. This creates an intermediate representation that you can inspect, edit, or curate before committing to skill generation.

According to the repository's docs/usage.md, this mode is ideal when you want to review extracted data or manually adjust the analysis before creating the agent skill.

/book-to-skill ~/books/awesome-book.pdf awesome-skill --mode analyze-only

3. Generate-from-Analysis Mode

This mode consumes an existing analysis.md file produced by a previous analyze-only run and builds the final SKILL.md without re-running the extractor. It skips the potentially expensive document parsing phase, using the saved analysis as the direct input for skill generation.

This is efficient when iterating on skill formatting or when working offline from a previously extracted analysis.

/book-to-skill ~/books/awesome-book.pdf awesome-skill --mode generate-from-analysis

4. Update/Fold-in Mode

The update (or fold-in) mode merges new source material into an existing skill directory. Instead of creating a fresh skill, it adds the extracted content to an already-published skill folder, preserving existing structure while appending new chapters or papers.

As documented in README.md, you invoke this by pointing the command at an existing skill path rather than a new name:

/book-to-skill ~/new-paper.pdf ~/.claude/skills/awesome-skill

Technical Implementation Details

The operational mode logic resides in scripts/extract.py, which serves as the CLI entry point. The script parses the --mode argument and routes execution to the appropriate workflow handler:

• Default path: Triggers the full extraction and generation pipeline
• --mode analyze-only: Executes only the extraction phase, outputting analysis.md
• --mode generate-from-analysis: Bypasses extraction, reading from analysis.md to produce SKILL.md
• Implicit update mode: Detected when the target path matches an existing skill directory structure

The docs/usage.md file provides concrete CLI examples for each routing path, while README.md outlines the high-level mode descriptions.

Summary

• Full conversion provides one-shot document-to-skill generation without intermediate files
• Analyze-only creates editable analysis.md reports for manual review before skill creation
• Generate-from-analysis rebuilds skills from saved analysis data, skipping redundant extraction
• Update/fold-in incrementally adds new content to existing skills without rebuilding the entire structure

Frequently Asked Questions

What is the default operational mode of the book-to-skill generator?

The default mode is full conversion, which extracts the source document and immediately generates a complete SKILL.md file in a single execution. You do not need to specify the --mode flag to use this behavior.

Can I edit extracted content before generating the final skill?

Yes. Use the analyze-only mode to produce an analysis.md file containing the raw extraction. You can manually edit this file, then run generate-from-analysis mode to create the final skill from your modified analysis without re-parsing the original document.

How do I add new chapters to an existing skill without starting over?

Use the update/fold-in mode by specifying the path to your existing skill directory (typically ~/.claude/skills/<skill-name>) as the destination. The generator will merge the new source material with the existing skill files rather than creating a new skill from scratch.

Where is the mode selection logic implemented in the source code?

The mode selection logic is implemented in scripts/extract.py, which parses the --mode CLI argument and dispatches to the appropriate workflow handler. The README.md and docs/usage.md files document the available modes and their specific use cases.

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