---
name: Build Agents Index
slug: build-agents-index
category: Automation
description: Build Agents Index scans agent and sub-agent frontmatter plus specialists.registry.yaml, then writes a derived agents-index.yaml. Use it after adding, changing, or removing agent, sub-agent, or specialist entries.
github: "https://github.com/digipulse-engineering/GAAI-framework/tree/main/.gaai/core/skills/cross/build-agents-index"
language: Shell
stars: 161
forks: 27
install: "npx degit https://github.com/digipulse-engineering/GAAI-framework/tree/main/.gaai/core/skills/cross/build-agents-index ~/.claude/skills/build-agents-index"
installs_to: ~/.claude/skills/build-agents-index
source_path: .gaai/core/skills/cross/build-agents-index/SKILL.md
collection_size: 25
category_size: 2226
collection_url: "https://dirskills.com/collections/Fr-e-d/GAAI-framework"
added: 2026-09-08T05:36:19.668Z
last_synced: 2026-09-08T05:36:19.668Z
canonical_url: "https://dirskills.com/skills/build-agents-index"
---

# Build Agents Index

Build Agents Index scans agent and sub-agent frontmatter plus specialists.registry.yaml, then writes a derived agents-index.yaml. Use it after adding, changing, or removing agent, sub-agent, or specialist entries.

**Install:**

```bash
npx degit https://github.com/digipulse-engineering/GAAI-framework/tree/main/.gaai/core/skills/cross/build-agents-index ~/.claude/skills/build-agents-index
```

## README

# Build Agents Index

## Purpose / When to Activate

Activate when:
- A new agent or sub-agent definition is created
- An agent's frontmatter is modified (role, id, track, lifecycle)
- A specialist entry is added, modified, or removed in `specialists.registry.yaml`
- `agents-index.yaml` is absent or suspected stale

This skill generates a single derived catalog of all agents, sub-agents, and specialists
available in the GAAI framework. Consumed by `gaai-status` and agent onboarding operations.

**`agents-index.yaml` is a cache. Agent .md frontmatter and specialists.registry.yaml are the sources of truth.**

---

## Process

### Step 1 — Scan agent definition files

Traverse `.gaai/core/agents/` recursively. Collect every `.md` file except `README.agents.md`.
This includes:
- Primary agents: `discovery.agent.md`, `bootstrap.agent.md`
- Sub-agents: `sub-agents/*.sub-agent.md`

Ignore non-.md files and the README.

### Step 2 — Extract frontmatter from each agent file

For each agent `.md` file, read the YAML frontmatter block (between `---` delimiters).
Extract the following fields:

| Field | Source | Notes |
|---|---|---|
| `type` | frontmatter `type` | `agent` or `sub-agent` |
| `id` | frontmatter `id` | Required |
| `role` | frontmatter `role` | Required |
| `track` | frontmatter `track` | Required |
| `parent` | frontmatter `parent` | Sub-agents only; absent for primary agents |
| `lifecycle` | frontmatter `lifecycle` | e.g. `ephemeral`, `persistent` |
| `updated_at` | frontmatter `updated_at` | May be absent |
| `path` | derived — relative path from `.gaai/core/agents/` | e.g. `sub-agents/review.sub-agent.md` |

If a required field is missing, log a warning inline in the entry but do not skip it.

### Step 3 — Merge specialist entries

Read `.gaai/core/agents/specialists.registry.yaml`. For each entry in the `specialists` list, include it verbatim under the `specialists` key in the output. Do not transform or filter specialist entries — they are already structured.

Add a `path` field: `specialists.registry.yaml` for all specialist entries.

### Step 4 — Write agents-index.yaml

Write to `.gaai/core/agents/agents-index.yaml` using the format below.
Overwrite any existing file — this is a fully derived artifact.

### Step 5 — Report

Return to the invoking agent:
- Count of agents, sub-agents, and specialists indexed
- Any entries with missing required fields
- Any duplicate `id` values

---

## Outputs

```yaml
# GAAI Agents Index
# Generated by build-agents-index — DO NOT EDIT MANUALLY
# Sources of truth: frontmatter in each agent .md + specialists.registry.yaml
# Regenerate: invoke build-agents-index skill

generated_at: YYYY-MM-DD
total:
  agents: N
  sub_agents: N
  specialists: N

agents:
  - id: AGENT-DISCOVERY-001
    type: agent
    role: discovery
    track: discovery
    lifecycle: persistent
    updated_at: YYYY-MM-DD
    path: discovery.agent.md

sub_agents:
  - id: SUB-AGENT-REVIEW-001
    type: sub-agent
    role: discovery-reviewer
    parent: AGENT-DISCOVERY-001
    track: discovery
    lifecycle: ephemeral
    updated_at: YYYY-MM-DD
    path: sub-agents/review.sub-agent.md

specialists:
  - id: db-migration
    description: "Schema changes, migrations, database-level operations"
    triggers: [schema change, migration, ALTER TABLE, ...]
    skills: [implement]
    context_bundle: [...]
    path: specialists.registry.yaml
```

---

## Quality Checks

- Every agent .md file (except README) is represented in the output
- All specialists from `specialists.registry.yaml` are included verbatim
- No manually written entries — all agent/sub-agent entries derived from frontmatter
- Duplicate `id` values flagged
- `generated_at` reflects the date of this run
- File written to `.gaai/core/agents/agents-index.yaml` exactly

---

## Non-Goals

This skill must NOT:
- Edit any agent .md file or specialists.registry.yaml
- Make decisions about which agents are valid or active
- Merge conflicting entries — only report them
- Be invoked as a dependency of other skills

**This skill reads and aggregates — it does not evaluate or decide.**