---
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`, `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.**