Documentation Navigation Skill

Navigate the hierarchical documentation system to find relevant context with minimal token usage.

Variables

| Variable | Default | Description | |----------|---------|-------------| | START_LEVEL | auto | auto, root, category, library, section, page | | KEYWORD_MATCH | fuzzy | fuzzy (semantic) or exact matching for index navigation |

Instructions

MANDATORY - Always start at the appropriate index level and drill down.

Read _index.toon files before loading pages
Match task keywords against index keywords
Load specific pages, not full contexts
Note priority and when_to_use fields in indexes

Red Flags - STOP and Reconsider

If you're about to:

Load full-context.md for a simple question
Guess file paths instead of reading the index
Skip the index and go straight to pages
Load everything "just in case"

STOP -> Follow the Navigation Protocol below -> Then proceed

Workflow

[ ] CHECKPOINT: Identify what you know (library? section? topic?)
[ ] Start at the appropriate index level
[ ] Read index, match keywords to your task
[ ] Drill down to specific pages
[ ] Load only the pages you need
[ ] CHECKPOINT: Is full-context.md justified? (rarely)

Cookbook

Level Selection

IF: Unsure where to start in the hierarchy
THEN: Read cookbook/level-selection.md
RESULT: Start at the right level based on what you know

Keyword Matching

IF: Searching for documentation by topic
THEN: Read cookbook/keyword-matching.md
RESULT: Find relevant pages through index keywords

Efficient Page Loading

IF: Loading multiple pages or managing token budget
THEN: Read cookbook/page-loading.md
RESULT: Minimize token usage while getting needed context

The Hierarchy

ai-docs/
├── _root_index.toon              # Level 0: All categories
├── libraries/
│   ├── _index.toon               # Level 1: All libraries
│   ├── {library}/
│   │   ├── _index.toon           # Level 2: Library sections
│   │   ├── {section}/
│   │   │   ├── _index.toon       # Level 3: Section pages
│   │   │   └── pages/
│   │   │       └── {page}.toon   # Level 4: Page summary
│   │   └── full-context.md       # Everything (escape hatch)

Navigation Protocol

Step 1: Start at the Right Level

| You Know | Start Here | |----------|------------| | Nothing | ai-docs/_root_index.toon | | Category (libraries/frameworks) | ai-docs/{category}/_index.toon | | Library name | ai-docs/libraries/{lib}/_index.toon | | Library + section | ai-docs/libraries/{lib}/{section}/_index.toon | | Exact page | ai-docs/libraries/{lib}/{section}/pages/{page}.toon |

Step 2: Read Index, Match Keywords

Each index contains:

description or purpose - What this level contains
keywords - Terms for matching your task
when_to_use - Guidance on when to drill deeper
Child paths - Where to navigate next

Match your task against keywords:

Task: "Handle LLM retry failures"
Keywords to find: retry, error, failure, fallback, timeout

Navigate:
1. libraries/_index.toon -> "baml" has "llm|structured-output"
2. baml/_index.toon -> common_tasks mentions "error handling"
3. baml/guide/_index.toon -> "error-handling" page has "retry|fallback"
4. baml/guide/pages/error-handling.toon -> Exact info needed

Step 3: Load Only What's Needed

DO:

@ai-docs/libraries/baml/guide/pages/error-handling.toon  # ~400 tokens

DON'T:

@ai-docs/libraries/baml/full-context.md  # ~15,000 tokens

Step 4: Load Multiple Pages if Needed

For complex tasks, load several specific pages:

@ai-docs/libraries/baml/guide/pages/error-handling.toon
@ai-docs/libraries/baml/guide/pages/timeouts.toon
@ai-docs/libraries/baml/reference/pages/retry-policy.toon

Still far cheaper than full-context.md.

Step 5: Use full-context.md Sparingly

Only for:

Writing comprehensive tutorials
Major migrations
Initial deep learning of a library

Index File Structure

Category Index (`_index.toon`)

meta:
  level: category
  name: libraries
  count: 5

items[5]{id,name,description,path,keywords,priority}:
baml,BAML,Structured LLM outputs with type safety,./baml/_index.toon,llm|types|prompts,high
mcp,MCP,Tool integration for AI assistants,./mcp/_index.toon,tools|servers|context,high

Library Index (`{lib}/_index.toon`)

meta:
  level: library
  name: BAML
  version: 0.70.0
  homepage: https://docs.boundaryml.com

overview: |
  Brief description of what this library does and when to use it.

sections[3]{id,name,path,page_count,when_to_use}:
guide,Guide,./guide/_index.toon,15,Learning concepts and tutorials
reference,Reference,./reference/_index.toon,25,Exact syntax and API details
examples,Examples,./examples/_index.toon,8,Working code samples

common_tasks[5]{task,section,page}:
Define output types,reference,types
Handle errors,guide,error-handling
Stream responses,guide,streaming

Section Index (`{lib}/{section}/_index.toon`)

meta:
  level: section
  library: baml
  section: guide
  page_count: 15

pages[15]{id,title,path,priority,purpose,keywords}:
introduction,Introduction,./pages/introduction.toon,core,Overview and basic concepts,basics|overview|start
error-handling,Error Handling,./pages/error-handling.toon,important,Retry and fallback strategies,retry|error|fallback

Page Summary (`{lib}/{section}/pages/{page}.toon`)

meta:
  level: page
  library: baml
  section: guide
  page: error-handling
  source_url: https://docs.boundaryml.com/guide/error-handling
  content_hash: abc123

summary:
  purpose: |
    One to two sentences on what this page teaches.

  key_concepts[5]: concept1|concept2|concept3|concept4|concept5

  gotchas[3]: warning1|warning2|warning3

code_patterns[2]:
  - lang: baml
    desc: What this pattern shows
    code: |
      // Truncated code example

related_pages[2]: ../pages/timeouts.toon|../../reference/pages/retry-policy.toon

Navigation Examples

Example 1: Specific Feature

Task: "Configure BAML streaming"

1. @ai-docs/libraries/baml/_index.toon
   -> common_tasks: "Stream responses" -> guide/streaming

2. @ai-docs/libraries/baml/guide/pages/streaming.toon
   -> Get streaming configuration

Tokens: ~600

Example 2: Unknown Library

Task: "Type-safe database access in TypeScript"

1. @ai-docs/libraries/_index.toon
   -> Scan keywords: "prisma" has "database|orm|typescript"

2. @ai-docs/libraries/prisma/_index.toon
   -> Navigate to relevant section

Tokens: ~400 + next level

Example 3: Comprehensive Knowledge

Task: "Migrate entire codebase from X to BAML"

1. @ai-docs/libraries/baml/full-context.md
   -> Load everything (correct choice here)

Tokens: ~15,000 (justified for migration)

Anti-Patterns

| Bad | Good | Why | |-----|------|-----| | Load full-context.md for simple question | Navigate to specific page | 95% token waste | | Guess at file paths | Start at index, drill down | Indexes show what exists | | Load everything "just in case" | Load what task requires | Wastes context window | | Skip index, go straight to pages | Read index first | May miss better pages |