Index Documentation and Code Skill

Purpose

Create a searchable, structured knowledge base from existing documentation and codebase. This enables fast context lookup during task planning and implementation in brownfield projects through semantic search, documentation-to-code mapping, and quick reference systems.

Core Principle: In brownfield projects, context discovery is the bottleneck—indexing eliminates repeated searching.

Prerequisites

• Existing documentation in docs/ directory

• Structured, readable codebase

• Write access to .claude/index/ location

• Optional: document-project skill completed first

Workflow

1. Load Configuration and Validate

Check prerequisites and configuration:

.claude/config.yaml

brownfield: docsPath: docs/ codebasePath: src/ indexLocation: .claude/index/ includeCode: true maxDepth: 3

Validate:

• Documentation directory exists with files

• Index location is writable

• Check if index exists (offer refresh vs rebuild)

2. Index Documentation

Parse and structure documentation content:

• Scan documentation files (.md files in docs/)

• Extract structure:

• Headings and sections

• Code blocks and examples

• Keywords and concepts (API names, domain terms, technologies)

• Build document index with sections, keywords, line numbers

• Create cross-references between documents

Output: Documentation indexed (file count), sections extracted, keywords identified, cross-references created

See: references/templates.md#step-2-output for complete format and index structure

3. Index Codebase (Optional)

Map code to documentation:

• Scan key code files:

• Models, schemas, types

• Routes, controllers, services

• Extract code elements:

• Exports, imports, functions

• Map to line numbers

• Build code-to-docs mapping:

• Find code mentions in docs

• Create bidirectional links

Output: Code files indexed, exports/functions mapped, code-to-docs links created

See: references/templates.md#step-3-output for complete format and code-mapping.md for strategies

4. Build Searchable Index

Create fast lookup structures:

• Create search index:

• Keyword → Documents

• Concept → Sections

• Code → Documentation

• Generate quick reference:

• Data models with file locations

• API endpoints with docs links

• Patterns and where documented

• Create glossary:

• Terms and definitions

• Links to detailed documentation

Output: search.json (searchable index), quick-ref.md (quick reference), glossary.md (term definitions) created in .claude/index/

See: references/templates.md#step-4-output for complete file formats and examples

Using the Index

Quick searches: grep for keywords in search.json | Look up endpoints in quick-ref.md | Find term definitions in glossary.md

Integration: create-task-spec loads relevant docs | implement-feature looks up patterns | document-project refreshes index

See: references/templates.md#search-examples for complete search commands and #integration-examples for workflows

Index Maintenance

When to refresh: Documentation updated | New code modules | Architecture changes | Quarterly maintenance

Refresh vs Rebuild: Refresh=incremental update (faster, preserves customizations) | Rebuild=full re-index (slower, clean slate)

See: references/templates.md#index-maintenance for detailed refresh process and output examples

Best Practices

Index early (before implementation) | Keep docs updated (refresh after changes) | Use quick ref (faster than full docs) | Maintain glossary (project-specific terms) | Include code selectively (key files only)

Reference Files

Detailed documentation in references/ :

templates.md: All output formats (Steps 1-4), search.json structure, quick-ref.md format, glossary.md format, search examples, integration workflows, index maintenance, JSON output format

indexing-format.md: Index structure details (comprehensive in templates.md)

code-mapping.md: Code-to-docs mapping strategies

When to Escalate

• Documentation is sparse or missing (run document-project first)

• Codebase structure is unclear or chaotic

• Index becomes too large (>100MB)

• Search performance degrades

Part of BMAD Enhanced Brownfield Suite