Documentation Retrieval Skill

This skill enables efficient retrieval of documentation context from the hierarchical documentation system.

Variables

Variable	Default	Description
MAX_TOKENS	2000	Target token budget for context loading
LOAD_FULL_CONTEXT	false	Use full-context.md instead of targeted pages
LOCAL_FIRST	true	Check ai-docs before web search

Instructions

MANDATORY - Always check local documentation before web searches.

•Start with _index.toon files for navigation
•Load targeted page summaries, not full contexts
•Consolidate multi-library context using the format below
•Pass pre-loaded context to sub-agents

Red Flags - STOP and Reconsider

If you're about to:

•Load full-context.md for a simple question
•Web search without checking local docs first
•Let sub-agents navigate from scratch instead of passing context
•Load all libraries "just in case"

STOP -> Use targeted retrieval patterns below -> Then proceed

Workflow

• CHECKPOINT: Have you identified what libraries you need?
• Check ai-docs/libraries/_index.toon for available docs
• Navigate to specific library _index.toon
• Identify relevant pages from index
• Load only the page summaries you need
• CHECKPOINT: Are you within token budget?

Cookbook

Direct Navigation

•IF: You know the library and topic
•THEN: Read cookbook/direct-navigation.md
•RESULT: Fastest path to specific information

Keyword Search

•IF: Uncertain which library has what you need
•THEN: Read cookbook/keyword-search.md
•RESULT: Find relevant docs by matching keywords

Multi-Library Gathering

•IF: Task involves multiple libraries
•THEN: Read cookbook/multi-library.md
•RESULT: Consolidated context from multiple sources

Full Context Loading

•IF: Need comprehensive understanding (migrations, tutorials)
•THEN: Read cookbook/full-context.md
•WARNING: High token cost (5,000-15,000 tokens)

When to Use This Skill

•Before implementing features involving external libraries
•When debugging errors from external dependencies
•When spawning sub-agents that need library context
•When uncertain about API syntax or behavior

Retrieval Patterns

Pattern 1: Direct Navigation (Know What You Need)

When you know the library and topic:

code

1. @ai-docs/libraries/{library}/_index.toon
   -> Read overview and common_tasks

2. Find matching task or section
   -> Note the page path

3. @ai-docs/libraries/{library}/{section}/pages/{page}.toon
   -> Get detailed summary with gotchas and patterns

Example: Need BAML retry configuration

code

1. @ai-docs/libraries/baml/_index.toon
   -> common_tasks: "Handle errors gracefully" -> guide/error-handling

2. @ai-docs/libraries/baml/guide/pages/error-handling.toon
   -> RetryPolicy syntax, gotchas about timeouts

Pattern 2: Keyword Search (Uncertain What Exists)

When you're not sure which library or page:

code

1. @ai-docs/libraries/_index.toon
   -> Scan library descriptions and keywords

2. Match your need against keywords
   -> Identify candidate libraries

3. For each candidate:
   -> @ai-docs/libraries/{lib}/_index.toon
   -> Check if relevant content exists

4. Load specific pages from best match

Example: Need "structured output parsing"

code

1. @ai-docs/libraries/_index.toon
   -> BAML: "Structured LLM outputs with type safety" [match]
   -> MCP: "Tool integration protocol" [no match]

2. @ai-docs/libraries/baml/_index.toon
   -> Confirms: type system, parsing, validation

3. Load relevant BAML pages

Pattern 3: Multi-Library Gathering (Complex Tasks)

When task involves multiple libraries:

code

1. List all libraries involved in task

2. For each library:
   -> Load _index.toon
   -> Identify relevant pages
   -> Load page summaries

3. Consolidate into single context block

4. OR: Spawn docs-context-gatherer agent

Pattern 4: Full Context (Deep Work)

When you need comprehensive understanding:

code

@ai-docs/libraries/{library}/full-context.md

Use sparingly - this loads everything (~5,000-15,000 tokens)

Appropriate for:

•Major migrations
•Writing tutorials
•Architectural decisions
•First-time deep learning

Context Consolidation Format

When gathering context from multiple pages, consolidate as:

markdown

## Documentation Context

### {Library}: {Topic}
**Purpose**: {1-2 sentence purpose}
**Key Points**:
- {concept 1}
- {concept 2}
**Gotchas**:
- {warning 1}
- {warning 2}
**Pattern**:
```{language}
{minimal code example}

{Library}: {Another Topic}

...

Sources: {list of page paths loaded} Tokens: ~{estimate}

code


## Budget Management

### Token Estimates by File Type

| File Type | Typical Size |
|-----------|--------------|
| `_index.toon` (category) | 100-150 tokens |
| `_index.toon` (library) | 150-250 tokens |
| `_index.toon` (section) | 100-200 tokens |
| `pages/*.toon` | 250-450 tokens |
| `full-context.md` | 5,000-15,000 tokens |

### Budget Guidelines

| Task Type | Target Budget | Loading Strategy |
|-----------|---------------|------------------|
| Quick fix | 300-500 | 1 page summary |
| Single feature | 800-1,200 | 2-3 page summaries |
| Integration | 1,500-2,500 | Library index + 4-6 pages |
| Multi-library | 2,000-4,000 | Multiple library indexes + key pages |
| Full context | 5,000+ | full-context.md |

### Efficiency Tips

1. **Index files are cheap navigation** - Read them freely
2. **Page summaries are high-signal** - Designed for this purpose
3. **Gotchas prevent expensive mistakes** - Always worth loading
4. **Code patterns are copy-paste ready** - High value per token
5. **full-context.md is last resort** - Use targeted loading first

## Common Retrieval Scenarios

### Scenario: Implementing a Feature

•Identify: What libraries does this feature use?
•Navigate: Find relevant pages in each library
•Load: Page summaries for implementation guidance
•Note: Gotchas before writing code
•Proceed: Implement with context loaded

code


### Scenario: Debugging an Error

•Identify: Which library produced the error?
•Search: Error-related pages in that library
•Load: Error handling and troubleshooting pages
•Check: Known gotchas that might explain the issue
•Proceed: Debug with context

code


### Scenario: Spawning Sub-Agent

•Analyze: What docs will sub-agent need?
•Gather: Load relevant pages NOW
•Consolidate: Format as context block
•Include: Add to sub-agent spawn prompt
•Spawn: Sub-agent has pre-loaded context

code


### Scenario: Uncertain Which Library

•Start: @ai-docs/libraries/_index.toon
•Scan: Library descriptions and keywords
•Match: Find libraries relevant to your need
•Explore: Check promising library indexes
•Load: Pages from best matching library

code


### Scenario: AI Tool Documentation

When you need information about AI tools (Claude Code, BAML, MCP, TOON, etc.):

•
Check local ai-docs FIRST: @ai-docs/libraries/claude-code/_index.toon @ai-docs/libraries/baml/_index.toon @ai-docs/libraries/toon/_index.toon
•
Navigate using same patterns as any library: -> Find section in _index.toon -> Load relevant page summaries -> Use full-context.md for comprehensive needs
•
Fall back to web search/fetch when:
- •Local docs don't cover the specific topic
- •Need time-sensitive info (release dates, latest versions)
- •Local docs are insufficient after checking
- •User explicitly requests current web information

code


**Why local first:**
- Faster (no network round-trip)
- Curated context (TOON format optimized for LLMs)
- Gotchas pre-extracted
- Token-efficient vs. full web pages

**When to web search:**
- Topic not found after checking local index
- Need current/live information
- User explicitly asks for latest from web

## Anti-Patterns

### Don't: Load full-context.md for Simple Questions

**Bad**: Load 15K tokens to answer "what's the retry syntax?"
**Good**: Navigate to specific page, load ~400 tokens

### Don't: Skip Documentation

**Bad**: "I probably remember how this works..."
**Good**: Take 30 seconds to load relevant page

### Don't: Re-Navigate in Sub-Agents

**Bad**: Each sub-agent navigates from scratch
**Good**: Parent loads context, passes to sub-agents

### Don't: Load Everything "Just in Case"

**Bad**: Load all libraries mentioned anywhere
**Good**: Load specific pages for specific needs

## Integration with Protocol

This skill implements the retrieval portions of:
`.claude/ai-dev-kit/protocols/docs-management.md`

Always follow the protocol's decision flow:
1. Task Analysis -> Identify libraries
2. Documentation Check -> Verify docs exist
3. Context Loading -> Use this skill's patterns
4. Execute with Context -> Proceed with task