index-docs

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"]}

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:

1. Scan documentation files (.md files in docs/)
2. Extract structure:
   • Headings and sections
   • Code blocks and examples
   • Keywords and concepts (API names, domain terms, technologies)
3. Build document index with sections, keywords, line numbers
4. 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)