Fr-e-d 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.yamlis 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
idvalues
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.yamlare included verbatim - No manually written entries — all agent/sub-agent entries derived from frontmatter
- Duplicate
idvalues flagged generated_atreflects the date of this run- File written to
.gaai/core/agents/agents-index.yamlexactly
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.