// Create searchable knowledge base from existing documentation and code for fast context lookup in brownfield projects. Indexes .md files with sections/keywords, maps code exports to documentation, generates search.json, quick-ref.md, and glossary.md in .claude/index/. Use when onboarding to brownfield projects or when documentation needs better discoverability.
| name | index-docs |
| description | Create searchable knowledge base from existing documentation and code for fast context lookup in brownfield projects. Indexes .md files with sections/keywords, maps code exports to documentation, generates search.json, quick-ref.md, and glossary.md in .claude/index/. Use when onboarding to brownfield projects or when documentation needs better discoverability. |
| version | 1 |
| category | Brownfield |
| acceptance | {"documentation_indexed":"All documentation files (.md) indexed with sections, keywords, and cross-references extracted","code_indexed":"Code files indexed with exports, functions, and documentation links mapped","search_index_created":"Searchable index files created (search.json, quick-ref.md, glossary.md) in .claude/index/"} |
| inputs | {"refresh":{"required":false,"description":"Refresh existing index (incremental) vs rebuild from scratch"}} |
| outputs | {"files_indexed":{"description":"Total number of files indexed (docs + code)"},"keywords_count":{"description":"Total unique keywords identified"},"references_count":{"description":"Total cross-references and links created"},"index_location":{"description":"Path to generated index files"}} |
| telemetry | {"emit":"skill.index-docs.completed","track":["files_indexed","docs_files_count","code_files_count","keywords_count","references_count","index_size_bytes","operation_type"]} |
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.
docs/ directory.claude/index/ locationdocument-project skill completed firstCheck prerequisites and configuration:
# .claude/config.yaml
brownfield:
docsPath: docs/
codebasePath: src/
indexLocation: .claude/index/
includeCode: true
maxDepth: 3
Validate:
Parse and structure documentation content:
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
Map code to documentation:
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
Create fast lookup structures:
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
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
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
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)
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
document-project first)Part of BMAD Enhanced Brownfield Suite