Difference Between DEPTH=reference and DEPTH=study in book-to-skill

DEPTH=reference generates a lightweight, fast-lookup index containing only chapter hierarchies and metadata, whereas DEPTH=study produces a comprehensive study guide embedding every paragraph, example, and annotation from the source material.

The book-to-skill repository provides a specialized extraction pipeline that converts books into structured skill files for AI agents. Understanding the DEPTH configuration flag is essential for controlling the granularity of generated output, as this parameter directly determines whether you receive a concise reference catalog or an exhaustive knowledge base suitable for deep research.

What the DEPTH Flag Controls

According to the source code in scripts/extract.py, the DEPTH environment variable acts as a content-filtering directive during the extraction phase. It instructs the parser how deeply to traverse the document tree before serializing content into the final SKILL.md artifact. The flag supports two mutually exclusive modes that trade storage efficiency against informational completeness.

DEPTH=reference: Lean Index Mode

When you set DEPTH=reference, the extractor preserves only the top-level document hierarchy—specifically chapter titles, section headers, and essential metadata. As noted in SKILL.md at line 292, this mode creates a "lean, fast-lookup" structure that omits body text, code examples, and detailed annotations, resulting in a compact representation optimized for navigation.

Use this mode when you need:

• A lightweight table of contents for quick browsing and cataloging
• Fast-loading skill files for memory-constrained environments
• Simple reference lookups without full-text retrieval requirements

DEPTH=reference python -m scripts.extract <path-to-book>

DEPTH=study: Comprehensive Study Mode

Setting DEPTH=study engages the full extraction pipeline, retaining every paragraph, code example, and detailed annotation found in the source document. The documentation at line 404 of SKILL.md demonstrates that this mode generates a verbose skill file capable of supporting deep-dive interactions, contextual question answering, and AI tutoring applications where complete context is required.

Use this mode when you require:

• Exhaustive content coverage for research-grade retrieval systems
• In-context learning capabilities for detailed tutoring agents
• Complete preservation of examples and explanatory text

DEPTH=study python -m scripts.extract <path-to-book>

Programmatic Configuration Options

Beyond shell environment variables, you can configure the depth programmatically within Python applications. The book_to_skill package reads the DEPTH value during initialization via book_to_skill/__init__.py, allowing dynamic configuration before invoking the extraction pipeline.

import os
from book_to_skill import extractor

# Configure depth programmatically

os.environ["DEPTH"] = "study"  # or "reference"

skill = extractor.run("<path-to-book>")

# Output contains either lean reference or full study content

print(skill.metadata.depth)  # Confirms active extraction mode

Implementation Details and Source Files

The semantic distinction between these modes is formally documented in SKILL.md, which explicitly defines the two options and provides a comparison table at line 347 outlining their respective use cases. The extraction logic that implements these behaviors resides in scripts/extract.py, which inspects the environment variable and adjusts its AST traversal depth before the generator serializes the final artifact.

Summary

• DEPTH=reference produces compact, hierarchical indexes containing only chapter and section metadata, ideal for quick navigation and catalog applications
• DEPTH=study generates comprehensive skill files retaining every paragraph, example, and annotation, enabling deep research and tutoring use cases
• Configure the flag via environment variable, command line, or programmatically through the Python API before calling the extractor
• The parameter is processed in scripts/extract.py and documented in SKILL.md with specific line references defining each mode's behavior

Frequently Asked Questions

Which DEPTH mode produces smaller output files?

DEPTH=reference generates significantly smaller files because it deliberately discards body text and retains only the structural metadata necessary for cataloging and navigation.

Can I convert an existing reference skill file to a study skill file?

No, you must reprocess the original book source with DEPTH=study specified to capture the full text content that was omitted during the initial reference extraction.

Does DEPTH=study impact processing performance?

Yes, DEPTH=study requires substantially more processing time and memory because it traverses the entire document tree and serializes significantly more content into the final skill structure compared to the lean reference mode.

Where is the DEPTH parameter documented in the repository?

The parameter semantics are documented in SKILL.md at line 292, with a detailed comparison table listing both modes side-by-side at line 347 and worked examples demonstrating the output differences at line 404.

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