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.

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