scripture-study

name	scripture-study
description	Study scripture by retrieving and merging all available commentary data for one or more verses. Supports verse ranges, depth levels (light/medium/full), and optional filtering by tool type.

Scripture Study

Overview

Retrieve and merge all available commentary data for Bible verses to enable comprehensive scripture study. This skill aggregates YAML commentary files from various Bible study tools, providing a unified view of lexical, theological, historical, and practical insights.

Data Repository Setup

This skill requires the mybibletoolbox-data repository for verse commentary data.

Auto-Clone Commentary Data

Before using this skill, check if data exists for the requested book(s). If not, auto-clone with sparse checkout:

# Function to ensure book data is available
ensure_book_data() {
  local BOOK=$1  # e.g., "MAT", "JHN", "ROM"

  # Check if data repo exists
  if [ ! -d "data" ]; then
    echo "Data not found. Cloning mybibletoolbox-data with sparse checkout..."
    git clone --filter=blob:none --sparse https://github.com/authenticwalk/mybibletoolbox-data data
    cd data
    git sparse-checkout init --cone
    git sparse-checkout set bible/${BOOK}
    cd ..
    echo "✓ Data ready for ${BOOK}"
  else
    # Check if specific book is available
    if [ ! -d "data/bible/${BOOK}" ]; then
      echo "Adding ${BOOK} to sparse checkout..."
      cd data
      git sparse-checkout add bible/${BOOK}
      cd ..
      echo "✓ ${BOOK} added"
    fi
  fi
}

# Example: For studying Matthew 5:3-10
ensure_book_data "MAT"

Expected location:

• data/bible/{BOOK}/ - All verse data for book

Sparse checkout strategy:

• Single book study: Clone only that book
• Multiple books: Add books as needed with git sparse-checkout add
• Sermon series: Clone all needed books upfront

When to Use

Use this skill when:

• User wants to study a specific verse or passage
• User asks for "all available data" or "commentary" on a verse
• User needs comprehensive verse analysis
• User mentions studying scripture, doing research, or preparing teaching materials
• User specifies a verse reference with depth or detail requirements

Do NOT use this skill when:

• User only wants to quote/display the verse text (use quote-bible skill)
• User wants to study source languages specifically (use get-source-languages skill)
• User is creating new commentary data (use appropriate tool-specific skills)

How to Use

Step 1: Parse the Bible Reference

Extract verse reference(s) from the user's request. References must use USFM 3.0 three-letter codes:

Formats supported:

• Single verse: "JHN 3:16", "GEN 1:1", "MAT 5:3"
• Verse range: "MAT 5:3-10", "JHN 1:1-5"
• Multiple verses: "JHN 3:16 JHN 3:17 JHN 3:18"
• Chapter: "MAT 5" (all verses in chapter 5)

Book codes: USFM 3.0 standard (MAT, JHN, GEN, ROM, PSA, etc.)

Step 2: Determine Depth Level

Identify the depth level from the user's request or default to "medium":

Depth levels:

• light: Core files only (essential commentary, translations, key insights)
• medium: Core files + verse-level tools (default)
• full: All available data including chapter-level and book-level context

Determining depth from user intent:

• "Quick overview", "summary", "brief": → light
• "Study", "analysis", "research": → medium
• "Comprehensive", "everything", "all data", "deep dive": → full

Step 3: Execute the Scripture Study Script

Use the Bash tool to execute:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "BOOK CHAPTER:VERSE" --depth <level>

Examples:

Single verse with default depth:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "JHN 3:16"

Verse range with full depth:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "MAT 5:3-10" --depth full

Multiple verses:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "JHN 3:16 JHN 3:17"

Filter by tool type:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "JHN 3:16" --filter sermon-illustrations

Step 4: Display Results

The script returns merged YAML data containing all available commentary organized by verse. Present the information clearly to the user:

For single verse:

• Show available commentary categories
• Highlight key insights relevant to their question
• Note data sources and citation information

For verse ranges:

• Present verse-by-verse breakdown
• Identify common themes across verses
• Summarize key patterns or progressions

For comprehensive study:

• Overview of all available data types
• Key theological, lexical, and practical insights
• Cross-references and related topics

Options and Parameters

Required Parameters

• reference: Verse reference in USFM 3.0 format (BOOK CHAPTER:VERSE)

Optional Parameters

• --depth <level>: Depth level (light|medium|full) - default: medium
• --filter <tool>: Include only specific tool types (can specify multiple)
• --exclude <tool>: Exclude specific tool types (can specify multiple)
• --output <file>: Save results to YAML file
• --json: Output as JSON instead of YAML
• --list-tools: Show available tools for the verse(s)

Filter Options

Use --filter to focus on specific commentary types:

# Only sermon illustrations
--filter sermon-illustrations

# Only source language data
--filter original-language-words

# Multiple filters
--filter sermon-illustrations --filter translations

Use --exclude to omit specific types:

# Exclude translations (often very large)
--exclude translations-ebible

Examples

Example 1: Quick Overview

User: "Give me a quick overview of John 3:16"

Action: Execute:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "JHN 3:16" --depth light

Expected behavior: Returns core commentary with essential insights, avoiding overwhelming detail

Example 2: Verse Range Study

User: "I want to study the Beatitudes in Matthew 5"

Action: Execute:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "MAT 5:3-12" --depth medium

Expected behavior: Returns verse-by-verse commentary for each Beatitude with moderate detail

Example 3: Comprehensive Analysis

User: "Give me everything you have on Genesis 1:1"

Action: Execute:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "GEN 1:1" --depth full

Expected behavior: Returns all available commentary including chapter and book-level context

Example 4: Sermon Preparation

User: "I'm preaching on Romans 8:28, show me sermon illustrations"

Action: Execute:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "ROM 8:28" --filter sermon-illustrations

Expected behavior: Returns only sermon illustration data for targeted preparation

Example 5: Multiple Verses

User: "Compare John 3:16, Romans 5:8, and 1 John 4:8"

Action: Execute:

python3 /home/user/context-grounded-bible/src/lib/scripture_study.py "JHN 3:16 ROM 5:8 1JN 4:8"

Expected behavior: Returns commentary for all three verses, enabling comparison

Technical Details

Data Sources

The skill aggregates data from:

• Commentary files: ./bible/commentary/{BOOK}/{chapter:03d}/{BOOK}.{chapter:03d}.{verse:03d}-{tool}.yaml
• Chapter-level files: ./bible/commentary/{BOOK}/{chapter:03d}/{BOOK}.{chapter:03d}-{tool}.yaml
• Book-level files: ./bible/commentary/{BOOK}/{BOOK}-{tool}.yaml

Depth Filtering

Light depth includes:

• Tools with scope: core
• Essential data only (~1-50 KB per verse)
• Examples: sermon-illustrations, cross-references

Medium depth includes:

• Tools with scope: core + standard
• Standard research depth (~50-500 KB per verse)
• Examples: core tools + word-studies, historical-context, semantic-clusters

Full depth includes:

• Tools with scope: core + standard + comprehensive
• Exhaustive reference data (>500 KB per verse)
• Examples: medium tools + all-translations, complete-lexicon

Tool Registry

The script reads from bible-study-tools/tool-registry.yaml to determine:

• Available tool types
• Tool file suffixes
• Scope levels (core/standard/comprehensive)
• Which tools should be included at each depth level

Scope Mapping:

• core: Always included (light, medium, full queries)
• standard: Included in medium and full queries only
• comprehensive: Included in full queries only

Data Merging

Uses yaml_merger.py to merge multiple YAML files:

• Nested merge preserves structure
• String values are concatenated if different
• Lists are extended
• Citations are preserved

Error Handling

If the script fails:

1. "No commentary found": No data exists for this verse yet
2. "Invalid verse reference": Check reference format (BOOK CHAPTER:VERSE)
3. "Tool not found": Specified filter tool doesn't exist (use --list-tools)
4. "File not readable": YAML syntax error in source file (report issue)

Integration with Tool Ecosystem

For Tool Creators

When creating new Bible study tools with bible-study-tool-creator:

• Register your tool in bible-study-tools/tool-registry.yaml
• Specify scope level:
  • core: Essential data, always included (<50 KB)
  • standard: Standard research depth (50-500 KB) - most tools
  • comprehensive: Exhaustive reference (>500 KB)
• Use standard file naming: {BOOK}_{chapter}_{verse:03d}.{tool-suffix}.yaml

For Tool Experimenters

When using tool-experimenter to improve tools:

• Consider how your tool fits into the depth hierarchy
• Test output size to determine appropriate scope level
• Update tool registry with final scope after experimentation
• Ensure YAML structure is compatible with merging

Notes

• Verse references use USFM 3.0 book codes (MAT, JHN, GEN, etc.)
• Chapter and verse numbers are zero-padded in file paths (001, 005, 016)
• YAML format ensures both human and AI readability
• Citations are preserved through merging for full traceability
• Empty results indicate no commentary has been generated yet for that verse

Version History

Version 1.0.0 (2025-10-30)

• Initial creation
• Supports single verses, ranges, and multiple verses
• Three depth levels (light/medium/full)
• Filter and exclude options
• Tool registry integration