doc-indexer

Document Indexer Skill

Purpose

Provide just-in-time context about available project documentation without loading full file content into the context window. The doc-indexer scans all markdown files in the docs/ directory, extracts their YAML frontmatter metadata, and returns a structured map of available documentation. This enables efficient discovery of specs, plans, retrospectives, and other documentation while minimizing token usage.

When to Use

Use this skill in the following situations:

• At the beginning of any work session to understand the current state of documentation
• When starting work on a new issue to identify relevant specs and context
• Before proposing changes to understand existing specifications
• When planning a sprint to review available approved specs
• Anytime you need an overview of project documentation without reading full files

Prerequisites

• The project must have a docs/ directory
• Documentation files should follow the convention of including YAML frontmatter
• The jq tool is NOT required (script works without it)

Workflow

Step 1: Run the Documentation Scanner

Execute the helper script to scan all markdown files in the docs/ directory:

bash scripts/scan-docs.sh

This will output a human-readable summary showing each document's frontmatter metadata.

For machine-readable JSON output (useful for programmatic processing):

bash scripts/scan-docs.sh -j

Step 2: Review the Documentation Map

The scanner returns information about all markdown files found in docs/, including:

• File path: Location of the documentation file
• Frontmatter metadata: Key-value pairs from YAML frontmatter (title, status, type, etc.)
• Compliance warnings: Files missing YAML frontmatter are flagged

Example human-readable output:

---
file: docs/specs/001-synthesis-flow.md
title: AgenticDev Methodology
status: approved
type: spec
---
file: docs/changes/my-feature/proposal.md
title: My Feature Proposal
status: in-review
type: proposal
[WARNING] Non-compliant file (no frontmatter): docs/README.md