build-agents-index

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-26T00:00:00.000Z","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

# 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.