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:

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.