Build Skills Index

Build Skills Index

Purpose / When to Activate

Activate when:

• A new skill is created (invoked automatically by create-skill Step 6)
• A skill's frontmatter is modified (description, tags, category, id)
• A skill is removed or deprecated
• Either skills-index.yaml is absent or suspected stale (e.g. after a git pull or framework update)

This skill generates the derived catalogs used by agents for fast skill discovery. It does not replace frontmatter — it aggregates it.

skills-index.yaml files are caches. Frontmatter is the source of truth.

Process

Step 1 — Scan both skill directories

Scan .gaai/core/skills/ recursively. Collect every file named SKILL.md. If .gaai/project/skills/ exists, scan it too. Ignore non-SKILL.md files. Ignore README.*, skills-index.yaml.

Step 2 — Extract frontmatter from each SKILL.md

For each SKILL.md found, 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 — include for visibility. Log any duplicate id values across both layers.

Step 3 — Group entries by track

Organize entries into three groups: discovery, delivery, cross. Within each group, sort alphabetically by name.

Step 4 — Write separate index files

Core index → .gaai/core/skills/skills-index.yaml (core skills only):

# GAAI Core Skills Index
# Source of truth: .gaai/core/skills/*/SKILL.md — core framework skills only
# Regenerate: invoke build-skills-index skill
generated_at: YYYY-MM-DD
total: N

discovery:
  - id: SKILL-DSC-001
    name: create-prd
    source: core
    description: "..."
    category: discovery
    track: discovery
    tags: []
    updated_at: YYYY-MM-DD
    path: core/skills/discovery/create-prd/SKILL.md

Project index → .gaai/project/skills/skills-index.yaml (project skills only, if project dir exists):

# GAAI Project Skills Index
# Source of truth: .gaai/project/skills/*/SKILL.md — project-specific skills only
# Regenerate: invoke build-skills-index skill
generated_at: YYYY-MM-DD
total: N

discovery:
  - id: SKILL-CNT-011
    name: content-plan
    source: project
    description: "..."
    # ... fields

Agents read both indices to get the full skill catalogue.

Step 5 — Report

Return to the invoking agent:

• Core skills count + project skills count
• Any entries with missing required fields (names + fields)
• Any duplicate IDs across both layers
• Confirmation both files were written

Automation

The check-and-update-skills-index.cjs script performs the same work automatically via the post-commit Git hook. This skill exists for manual invocation when the hook doesn't trigger (fresh clone, worktree, CI).

Quality Checks

• Every SKILL.md in both directories is represented in the correct index (no silently skipped files)
• No manually written entries — all entries derived from frontmatter
• Duplicate id values flagged across both layers (do not silently deduplicate)
• generated_at reflects the date of this run
• Core index contains zero source: project entries
• Project index contains zero source: core entries

Non-Goals

This skill must NOT:

• Edit any SKILL.md file
• Make decisions about which skills are valid or relevant
• Merge duplicate skills or resolve conflicts — only report them
• Be invoked as a dependency of other skills (only agents call this)

This skill reads and aggregates — it does not evaluate or decide.