GAAI-framework build-skills-index

Scan SKILL.md files in .gaai/core/skills/ and .gaai/project/skills/, extract YAML frontmatter, and regenerate separate skills indices for each layer. Core index ships with the OSS framework; project index is project-specific.

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-skills-index" ~/.claude/skills/fr-e-d-gaai-framework-build-skills-index && rm -rf "$T"

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

source content

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:

Field	Source	Notes
`name`	frontmatter `name`	Required
`description`	frontmatter `description`	Required
`id`	frontmatter `id` or `metadata.id`	Required
`category`	frontmatter `category` or `metadata.category`	Required
`track`	frontmatter `track` or `metadata.track`	Required
`tags`	frontmatter `tags` or `metadata.tags`	May be absent — default to `[]`
`updated_at`	frontmatter `updated_at` or `metadata.updated_at`	May be absent
`path`	derived — relative path from `.gaai/` to SKILL.md	e.g. `core/skills/cross/memory-ingest/SKILL.md`

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.