# Knowledge Index

> Generate a pre-computed index of all solution frontmatter for fast knowledge lookups. Replaces multiple Grep+Read calls with a single file read.

- Skill: `oaa-dev/knowledge-index` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oaa-dev/knowledge-index`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oaa-dev/knowledge-index/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oaa-dev (https://skillmd.com/u/oaa-dev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/oaa-dev/knowledge-index

---


# Knowledge Index Generator

**Purpose:** Scan all solution files, extract YAML frontmatter, and write a compact markdown index to `docs/knowledge/index.md`. This index enables single-read knowledge lookups instead of multiple Grep+Read tool calls.

## Overview

The index file contains:
- A header with solution count, module count, and generation timestamp
- A Critical Patterns digest (titles + file refs from critical-patterns.md)
- A Modules table with file counts, key components, and relationships per module
- A Solutions table with all frontmatter fields from every solution file

One Read of this file replaces 3-4 Grep calls + N frontmatter reads + a Read of critical-patterns.md + module doc exploration.

---

## Process

### Step 1: Verify Knowledge Base

Check that `docs/knowledge/solutions/` exists. If not, report: "No knowledge base found. Run /setup first."

### Step 2: Gather All Solution Files

```
Glob: pattern="docs/knowledge/solutions/**/*.md"
```

### Step 3: Read Critical Patterns

```
Read: docs/knowledge/patterns/critical-patterns.md
```

Extract each numbered pattern heading and its associated solution file reference. Format as:
```
- [Pattern Name] -> [relative/path/to/solution.md]
```

If the file only has the placeholder comment, the Critical Patterns section will be empty.

### Step 4: Scan Module Docs

```
Glob: pattern="docs/knowledge/modules/*.md"
```

If no files found, skip this step. The Modules section will be omitted from the index.

For each module doc found, read the first 40 lines. Extract:
- **Module name**: from the `# {Name} Module` heading
- **File count**: number of rows in the Connected Files table
- **Key components**: unique Category values from the table (max 4)
- **Relationships**: from the model relationships section (max 4 related modules)

Use parallel Read calls in batches of 10 for efficiency.

### Step 5: Extract Frontmatter From Each Solution

For each solution file, read the first 20 lines to extract YAML frontmatter fields:
- `module`
- `date`
- `problem_type`
- `component`
- `severity`
- `tags` (join array as comma-separated string)
- `title` (from the first `# ` heading after frontmatter, or from the filename)

Use parallel Read calls in batches of 10 for efficiency.

**If a file has malformed or missing frontmatter**, skip it and count it as skipped.

### Step 6: Generate Index File

Write `docs/knowledge/index.md` with this exact structure:

```markdown
# Knowledge Index
<!-- Auto-generated by knowledge-index skill. Regenerate with /knowledge-garden::reindex -->
<!-- Updated: YYYY-MM-DD -->
<!-- Solutions: N -->
<!-- Skipped: M (malformed frontmatter) -->
<!-- Modules: P -->

## Critical Patterns
- [Pattern Name] -> [category/filename.md]
- ...

## Modules
| Module | Files | Key Components | Relationships | Doc |
|--------|-------|----------------|---------------|-----|
| User | 14 | Controller, Service, DTO, Repository | Order, Profile | modules/user.md |
| ... | ... | ... | ... | ... |

## Solutions
| File | Module | Type | Component | Severity | Date | Tags |
|------|--------|------|-----------|----------|------|------|
| category/filename.md | ModuleName | problem_type | component | severity | YYYY-MM-DD | tag1, tag2 |
| ... | ... | ... | ... | ... | ... | ... |
```

**File column:** Use the path relative to `docs/knowledge/solutions/` (e.g., `performance-issues/n-plus-one-user-queries-20260210.md`).

**Sort order:** By date descending (newest first).

**Modules section:** Only include if module docs were found in Step 4. If no module docs exist, use `<!-- Modules: 0 -->` and omit the table.

**Empty knowledge base:** If no solution files found, write:

```markdown
# Knowledge Index
<!-- Auto-generated by knowledge-index skill. Regenerate with /knowledge-garden::reindex -->
<!-- Updated: YYYY-MM-DD -->
<!-- Solutions: 0 -->
<!-- Modules: 0 -->

## Critical Patterns

## Solutions
| File | Module | Type | Component | Severity | Date | Tags |
|------|--------|------|-----------|----------|------|------|
```

### Step 7: Report

```
Knowledge index updated.

- Solutions indexed: N
- Skipped (malformed): M
- Critical patterns: P
- Modules indexed: Q
- Written to: docs/knowledge/index.md
```

---

## Error Handling

**No solutions directory:**
- Suggest running setup: "Run /setup to initialize knowledge-garden first."

**No solution files:**
- Write an empty index (Solutions: 0). This allows the auto-read phase in workflow commands to detect an empty KB with a single Read.

**Malformed frontmatter:**
- Skip the file, increment skipped counter, report at the end.

**No module docs:**
- Skip the Modules section. Use `<!-- Modules: 0 -->` in the header and omit the Modules table.