---
name: build-agents-index
description: Scan all agent and sub-agent definition files in .gaai/core/agents/, extract YAML frontmatter, merge with specialists.registry.yaml, and generate a derived agents-index.yaml at .gaai/core/agents/agents-index.yaml. Activate after adding, modifying, or removing any agent, sub-agent, or specialist entry.
license: ELv2
compatibility: Works with any filesystem-based AI coding agent
metadata:
  author: gaai-framework
  version: "1.0"
  category: cross
  track: cross-cutting
  id: SKILL-CRS-018
  tags:
    - governance
    - index
    - discoverability
    - agents
  updated_at: 2026-02-26
  status: stable
inputs:
  - .gaai/core/agents/**                      (all agent .md files — scanned for frontmatter)
  - .gaai/core/agents/specialists.registry.yaml   (specialist definitions — included as-is)
outputs:
  - .gaai/core/agents/agents-index.yaml      (generated — never edit manually)
---

# 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`, `delivery.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/planning.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

  - id: AGENT-DELIVERY-001
    type: agent
    role: delivery-orchestrator
    track: delivery
    lifecycle: persistent
    updated_at: YYYY-MM-DD
    path: delivery.agent.md

sub_agents:
  - id: SUB-AGENT-PLANNING-001
    type: sub-agent
    role: planning-specialist
    parent: AGENT-DELIVERY-001
    track: delivery
    lifecycle: ephemeral
    updated_at: YYYY-MM-DD
    path: sub-agents/planning.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.**