GAAI-framework build-agents-index

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.

install

source · Clone the upstream repo

git clone https://github.com/Fr-e-d/GAAI-framework

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Fr-e-d/GAAI-framework "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.gaai/core/skills/cross/build-agents-index" ~/.claude/skills/fr-e-d-gaai-framework-build-agents-index && rm -rf "$T"

manifest: .gaai/core/skills/cross/build-agents-index/SKILL.md

source content

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

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