DEPTH=reference vs DEPTH=study in Book-to-Skill: Key Differences Explained

DEPTH=reference generates lean, fast-lookup chapters with 800–1,800 tokens for quick decision-making, while DEPTH=study produces expansive, example-driven chapters with 1,000–3,000 tokens for deep learning.

Book-to-Skill, an open-source project maintained by virgiliojr94/book-to-skill, uses the DEPTH variable to control the granularity of generated skill chapters. Understanding the difference between DEPTH=reference and DEPTH=study is essential for optimizing token usage and ensuring the generated content matches your intended use case, whether you need quick reference material or comprehensive study guides.

Content Structure: Reference vs Study Mode

The DEPTH variable determines how much pedagogical content is included in each generated chapter. This setting is automatically inferred from the user's answer to the "purpose" question in Step 4 of the generator pipeline, as documented in docs/architecture.md (lines 33–35).

DEPTH=reference (Quick Lookup Mode)

Reference depth is optimized for speed and minimal token consumption. Chapters generated in this mode contain only essential decision-ready points, omitting worked examples, expanded procedural steps, and deep reasoning. The resulting content is compact and loads faster, making it ideal for scenarios where you need to look up specific facts or commands without narrative context.

DEPTH=study (Deep Learning Mode)

Study depth prioritizes pedagogical richness over brevity. These chapters include concrete worked examples, expanded "how" steps, and brief "why it works" notes. According to the specification in SKILL.md (lines 45–51), study mode adds "## Worked Example" sections and actionable content that learners can reproduce, providing a more thorough understanding at the cost of higher token usage.

Token Budget Matrix

The concrete difference between the two modes is enforced through a token budget matrix defined in SKILL.md. The allocation varies by both DEPTH setting and book type (text or technical), with technical books receiving higher limits to accommodate code examples and technical specifications.

Book Type	DEPTH=reference	DEPTH=study
text	800–1,200 tokens	1,000–1,800 tokens
technical	1,200–1,800 tokens	2,000–3,000 tokens

Technical books consistently require 40–66% more tokens than text books at the same depth level due to the inclusion of syntax, configuration examples, and command references.

Implementation in the Source Code

The DEPTH logic is implemented across several core files in the repository. The mapping of user intent to DEPTH value is specified in SKILL.md (lines 91–95), while the budget enforcement resides in the configuration layer.

Book Type Configuration

Supported book types are defined in book_to_skill/config.py, where valid entries include text and technical. These types combine with the DEPTH variable to compute the final token constraints passed to the language model.

Budget Calculation Logic

The token allocation is implemented programmatically using a dictionary mapping that corresponds to the matrix in SKILL.md:

# Token budget matrix as defined in the configuration

DEPTH_BUDGET = {
    ("text", "reference"): (800, 1200),
    ("text", "study"):     (1000, 1800),
    ("technical", "reference"): (1200, 1800),
    ("technical", "study"):     (2000, 3000),
}

def token_budget(book_type: str, depth: str) -> tuple[int, int]:
    """Retrieve min and max token limits for a given book type and depth."""
    return DEPTH_BUDGET[(book_type, depth)]

Depth Inference Algorithm

The system automatically infers DEPTH from the user's answer to the purpose question in Step 4. A simplified representation of this logic, as implemented in the CLI orchestration layer (book_to_skill/cli.py), follows this pattern:

def infer_depth(answer: str) -> str:
    """
    Determine DEPTH based on user selection.
    '3' maps to reference mode; all others default to study.
    """
    opts = set(answer.split())
    return "reference" if opts == {"3"} else "study"

When to Use Each Mode

Choose DEPTH=reference when building quick-reference cards, command cheat sheets, or API documentation where the goal is fast lookup and minimal token costs during querying.

Choose DEPTH=study when creating onboarding materials, tutorial documentation, or training resources where the reader needs to understand not just what to do, but how and why through concrete examples.

Summary

• DEPTH=reference produces lean chapters (800–1,800 tokens) optimized for fast lookup, omitting worked examples and deep reasoning to minimize token consumption.
• DEPTH=study generates comprehensive chapters (1,000–3,000 tokens) including concrete worked examples, expanded procedural steps, and pedagogical context for deep learning.
• The mode is determined in Step 4 of the generator pipeline based on the user's purpose answer, as documented in docs/architecture.md and specified in SKILL.md.
• Token budgets are enforced through the DEPTH_BUDGET mapping in the configuration layer, with technical books receiving higher allocations than text books at both depth levels.

Frequently Asked Questions

How is DEPTH automatically determined in Book-to-Skill?

DEPTH is set during Step 4 of the generation pipeline based on the user's answer to the "purpose" question. According to the architecture documentation in docs/architecture.md (lines 33–35), selecting option "3" maps to reference mode, while any other selection defaults to study mode. This logic is implemented in the CLI orchestration layer within book_to_skill/cli.py.

What are the exact token limits for each DEPTH setting?

The token budgets are hardcoded in SKILL.md (lines 45–51) and implemented in the configuration module. For text books, reference mode allows 800–1,200 tokens and study mode allows 1,000–1,800 tokens. For technical books, reference mode allows 1,200–1,800 tokens and study mode allows 2,000–3,000 tokens.

Does DEPTH affect the presence of worked examples?

Yes. DEPTH=study explicitly includes "## Worked Example" sections and expanded "how" steps that are strictly omitted in DEPTH=reference. The SKILL.md specification (lines 45–51) states that reference mode provides only "essential decision-ready points" without the concrete examples and reasoning steps included in study mode.

Where is the DEPTH logic implemented in the source code?

The DEPTH behavior is distributed across three key files: docs/architecture.md defines the Step 4 mapping, SKILL.md contains the semantic specification and token matrix (lines 45–51 and 91–95), and book_to_skill/config.py defines the supported book types. The runtime application of these budgets occurs in book_to_skill/cli.py, which orchestrates the extraction and generation flow.

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