content-retrieval

thapaliyabikendra's avatarfrom thapaliyabikendra

Token-efficient retrieval using depth levels (L0-L5) and heading-based sections. Use for any file reads.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 19, 2025
[Memory and Context Management]

When & Why to Use This Skill

This Claude skill implements a high-performance Content Retrieval Protocol designed to minimize token consumption during file operations. By utilizing a tiered depth system (L0-L5) and markdown-native section extraction, it allows agents to pinpoint and retrieve only the necessary information—ranging from simple existence checks to specific section reads—rather than processing entire files. This approach significantly enhances agent speed and reduces operational costs in large-scale codebases or documentation sets.

Use Cases

  • Large Codebase Navigation: Quickly checking for the existence of specific functions or classes across multiple files without loading full source code, saving up to 90% in token usage.
  • Targeted Documentation Lookup: Extracting specific 'Quick Reference' or 'Summary' sections from long markdown guides using heading-based detection to provide instant answers.
  • Context Window Optimization: Managing long-running agent tasks by replacing full-file reads with targeted grep-based lookups to stay within strict token limits.
  • Efficient Metadata Extraction: Rapidly reading file frontmatter and headers to categorize or index large sets of documents without processing the body content.
namecontent-retrieval
description"Token-efficient retrieval using depth levels (L0-L5) and heading-based sections. Use for any file reads."
layer4
tech_stack[agnostic]
topics[retrieval, efficiency, tokens, grep, read, protocol]
depends_on[]
complements[knowledge-discovery]
keywords[retrieve, read, grep, lookup, tokens, efficient, partial, section]
auto_applytrue

Content Retrieval Protocol

Token-efficient retrieval system using markdown-native section detection.

Summary

Core Principle: Never read a full file when partial content suffices.

Choose retrieval depth by need:

  • Exists? → Grep (files_with_matches)
  • Count? → Grep (count)
  • Lookup? → Grep (-C:2)
  • Overview? → Read (limit:40)
  • Section? → Grep heading → Read (offset, limit)
  • Full? → Read (justify first)

Quick Reference

Depth Levels

Level Need Method Lines
L0 Exists? Grep(output: files_with_matches) ~1
L1 Count? Grep(output: count) ~1
L2 Lookup value Grep(pattern, -C:2) ~5
L3 Overview Read(limit: 40) ~40
L4 Section Grep heading → Read(offset, limit) ~50
L5 Full Read() - justify first All

Decision Tree

What do I need?
├─ Does X exist? ──────────► L0: Grep files_with_matches
├─ How many X? ────────────► L1: Grep count
├─ What is X's value? ─────► L2: Grep with context
├─ What does X do? ────────► L3: Read limit:40
├─ How to use X for Y? ────► L4: Section extraction
└─ Implement X fully? ─────► L5: Full read (target only)

Tool Selection

Scenario Tool Parameters
Check skill exists Grep output: files_with_matches
Count matches Grep output: count
Get specific row Grep pattern, -C: 0-2
Read frontmatter Read limit: 25
Read frontmatter+summary Read limit: 40
Extract section Read offset: N, limit: 50
Full understanding Read (no limit)

Section Extraction

How Sections Work (Markdown-Native)

Sections are defined by headings and horizontal rules:

## Section A
Content...

---                    ← Section A ends here (horizontal rule)

## Section B           ← Or section ends at next same-level heading
Content...

No custom markers needed. Standard markdown structure.

Extraction Algorithm

1. Grep("^## Section Name$", file)     → line 15
2. Grep("^---|^## ", file, offset: 16) → next break at line 30
3. Read(file, offset: 15, limit: 15)   → lines 15-30

Section End Detection

A section ends at the first of:

  1. --- (horizontal rule)
  2. ## (same-level heading)
  3. # (higher-level heading)
  4. EOF (end of file)

Examples

# Extract Summary section
Grep("^## Summary$", file) → line 20
Grep("^---|^## ", file, offset: 21) → line 28
Read(file, offset: 20, limit: 8)

# Extract Quick Reference section
Grep("^## Quick Reference$", file) → line 30
Grep("^---|^## ", file, offset: 31) → line 55
Read(file, offset: 30, limit: 25)

Retrieval Protocol

Rule 1: Start at Lowest Depth

WRONG: Read entire SKILL-INDEX.md to find one skill
RIGHT: Grep("skill-name", SKILL-INDEX.md, -C:1)

WRONG: Read 5 skill files to understand what they do
RIGHT: Read each with limit:40 (frontmatter + summary)

WRONG: Read entire agent file to check if it has a skill
RIGHT: Grep("skills:.*skill-name", agent.md)

Rule 2: Index First, Files Second

1. Check index file (SKILL-INDEX.md, AGENT-INDEX.md)
2. Extract needed info via grep
3. Only read source file if index insufficient

Rule 3: Frontmatter Contains Metadata

All files have metadata in first 20 lines:

---
name: identifier
description: "one-line summary"
layer: 1-4
keywords: [searchable, terms]
---

To get metadata: Read(file, limit: 20)

Rule 4: Headings Define Sections

Standard markdown headings define extractable sections:

## Summary          ← Grep target
Brief description.

---

## Quick Reference  ← Grep target
| Col | Col |

To extract section: Grep heading → find end → Read range

Rule 5: Full Read Only for Targets

Full read justified when:

  • File is the TARGET being modified/implemented
  • L3 read confirmed full content needed
  • Creating comprehensive documentation
  • Debugging requires full context

QMD File Structure

Standard Layout

---
name: identifier
description: "One-line (< 100 chars)"
layer: 1-4
keywords: [grep, targets]
---

# Title

## Summary

2-3 sentences. Key purpose.

---

## Quick Reference

| Pattern | Usage |
|---------|-------|

---

## Patterns

### Pattern 1
Content...

### Pattern 2
Content...

---

## Related

- [link](path)

Reserved Headings

Heading Purpose Required
## Summary Quick understanding (L3) Yes
## Quick Reference Lookup tables (L2-L3) Yes
## Patterns Implementation details For skills
## Scope Does/Does NOT For agents
## Related Cross-references Recommended

Frontmatter Schema

---
# Required
name: string           # Identifier (grep target)
description: string    # One-line (< 100 chars)
layer: number          # 1=foundation, 2=framework, 3=feature, 4=workflow

# Recommended
keywords: string[]     # Grep targets
depends_on: string[]   # Prerequisites
complements: string[]  # Often-used-with

# Optional
used_by: string[]      # Agents/commands using this
tech_stack: string[]   # Technologies
auto_apply: boolean    # Auto-trigger on match
---

Index File Format

Grep-Optimized Tables

## Master Index

| Name | L | Keywords | Path |
|------|---|----------|------|
| skill-a | 2 | key1,key2 | skills/skill-a/SKILL.md |
| skill-b | 1 | key3,key4 | skills/skill-b/SKILL.md |

---

## Lookup by Keyword

| Keyword | Skills |
|---------|--------|
| entity | abp-framework, abp-entity, domain-modeling |

Grep usage:

Grep("skill-a", INDEX.md, output: content, -C: 0)
→ | skill-a | 2 | key1,key2 | skills/skill-a/SKILL.md |

Examples

Example 1: Analyze Agent

Old approach (2,434 lines):

Read(AGENT-QUICK-REF.md)        → 127 lines
Read(abp-developer.md)          → 144 lines
Read(SKILL-INDEX.md)            → 337 lines
Read(3 skill files)             → 1,283 lines

Protocol approach (~265 lines):

Read(abp-developer.md)                    → 108 lines (target)
Grep("abp-developer", AGENT-INDEX.md)     → 1 line
Grep(skills from agent, SKILL-INDEX.md)   → 11 lines
Read(3 skills, limit:40 each)             → 120 lines

Savings: 89%

Example 2: Check Skill Exists

# L0: Just check existence
Grep("^name: xunit-testing", .claude/skills, output: files_with_matches)
→ .claude/skills/xunit-testing-patterns/SKILL.md

Example 3: Extract Section

# L4: Section extraction (markdown-native)
Grep("^## Quick Reference$", skill.md) → line 30
Grep("^---|^## ", skill.md, offset: 31) → line 55
Read(skill.md, offset: 30, limit: 25)
→ Just the Quick Reference section

Checklist

For File Authors

  • Frontmatter under 20 lines
  • description is one line, under 100 chars
  • keywords include grep targets
  • ## Summary section present (2-3 sentences)
  • ## Quick Reference has lookup tables
  • --- separators between major sections
  • No critical info buried deep

For Consumers

  • Check index before reading files
  • Use appropriate depth level (L0-L5)
  • Start with L0-L2, escalate if needed
  • Full read only for target files