GAAI Skills

May 8, 2026 · View on GitHub

Skills are pure execution units. They perform a single, well-defined operation and produce explicit outputs. They never reason about intent or strategy.

Agents decide. Skills execute.

Core Skills — Week 1

These are the 7 skills you will encounter in a normal workflow. You do not invoke skills directly — agents invoke them on your behalf. This list tells you what is happening under the hood.

Skill	When it runs
`generate-epics`	Discovery: translate product intent into outcome-driven Epics
`generate-stories`	Discovery: translate an Epic into User Stories with acceptance criteria
`evaluate-story`	Delivery: assess complexity and determine delivery tier
`implement`	Delivery: write code that satisfies acceptance criteria
`qa-review`	Delivery: validate implementation against acceptance criteria — the quality gate
`memory-retrieve`	Any agent: load the minimum relevant memory before context-building
`decision-extraction`	After QA PASS: formalize durable decisions into long-term memory

The full catalog (48 skills) is below. Skills outside this list are loaded on demand for advanced workflows.

Structure

Each skill lives in its own directory with a SKILL.md file:

skills/
├── discovery/   ← produce artefacts (PRD, Epics, Stories, validation)
├── delivery/    ← orchestrate and execute (planning, implementation, QA)
├── cross/       ← memory, context, governance, analysis — usable by any agent
└── domains/     ← domain-specific skill packs (mirrors memory/domains/)
    └── content-production/

The source of truth for available skills is the directory itself. The skills-index.yaml file in this directory is a derived cache (core skills only) — generated by build-skills-index, never edited manually. Project skills have their own index at .gaai/project/skills/skills-index.yaml.

Discovery Protocol

Skills are loaded in three phases — load the minimum needed, not everything:

Phase 1 — Filter by frontmatter (read SKILL.md frontmatter only)

Read skills-index.yaml for a fast aggregated view, or scan SKILL.md frontmatter directly if the index is absent or stale.

Frontmatter fields available for filtering:

Field	Values	Use for
`metadata.category`	`discovery` \| `delivery` \| `cross`	Narrow by agent track
`metadata.track`	`discovery` \| `delivery` \| `cross-cutting`	Secondary filter
`metadata.tags`	list of keywords	Cross-cutting capability search
`description`	one sentence	Primary relevance signal — what it does + when to activate
`metadata.id`	`SKILL-{CAT}-{NNN}`	Exact lookup by ID

Directive:

Use metadata.category to scope to the right directory first
Read description to confirm relevance — it is the single most important field
Use metadata.tags for cross-cutting capabilities (e.g. memory, governance, qa)
Do not load all skills — load only SKILL.md files whose description matches your task

Phase 2 — Load full SKILL.md

Load the full SKILL.md body only for skills confirmed relevant in Phase 1. Budget: <5,000 tokens per skill, <500 lines.

Phase 3 — Load references/ (execution only)

Load files in references/ or assets/ only during execution, never at discovery time.

Invocation Rules

Skills are never invoked implicitly — an agent always selects and invokes explicitly
Skills execute in isolated context windows — no shared state between skills
Skills never chain other skills — only agents orchestrate
Skills never access memory autonomously — context is always provided by the agent
Skills never make product or architectural decisions — they execute only

Skill Authoring Guidance

When to add a skill vs. when to add a rule

You want to...	Use...
Add a new execution capability (something an agent will do)	`create-skill`
Add a new constraint (something an agent must not do, or a standard it must follow)	`rules-normalize`

Skills are procedural: they perform a defined operation and produce outputs. They live in .gaai/core/skills/.

Rules are declarative: they state constraints, policies, and governance boundaries. They live in .gaai/core/contexts/rules/.

Decision test

Ask: "Does this describe how to do something, or whether something is allowed?"

"How to generate a Story from an Epic" → skill (generate-stories)
"Stories must have acceptance criteria before entering the backlog" → rule (orchestration.rules.md)
"How to compact memory when it exceeds a size threshold" → skill (memory-compact)
"How to archive a superseded DEC out of the active index" → skill (memory-archive-superseded)
"How to validate memory index discoverability invariants" → skill (memory-index-lint)
"Memory must never be auto-loaded by a skill" → rule (orchestration.rules.md)

If your answer is "how to do something" → skill. If your answer is "a constraint the system must enforce" → rule.

How to create each

New skill: invoke create-skill (.gaai/core/skills/cross/create-skill/SKILL.md) → create-skill Step 6 invokes build-skills-index to regenerate skills-index.yaml
New rule: invoke rules-normalize (.gaai/core/skills/cross/rules-normalize/SKILL.md)

Maintaning the Index

skills-index.yaml is generated — never edited manually.

To regenerate after adding or modifying a skill: → invoke build-skills-index (.gaai/core/skills/cross/build-skills-index/SKILL.md)

Final Rule

If a skill appears to "think", it is wrongly designed.

Delivery Skills

Skill	ID	Description
`browser-journey-test`	—	Browser-based journey testing for UI validation
`ci-watch-and-fix`	SKILL-DELIVERY-CI-WATCH-001	Watch GitHub Actions CI after PR creation, detect failures, extract logs, apply minimal fixes, and re-push — up to 3 cycles before escalating
`compose-team`	—	Read specialists registry and select the sub-agent team for a Story
`coordinate-handoffs`	SKILL-DEL-009	Validate sub-agent handoff artefacts, sequence phase transitions, manage retry and escalation logic
`delivery-high-level-plan`	SKILL-DELIVERY-HIGH-LEVEL-PLAN-001	Transform validated Stories into a clear, minimal, governed execution plan
`evaluate-story`	—	Assess complexity, identify domains, determine delivery tier
`frontend-design`	—	Domain-specific skill for frontend UI implementation
`implement`	—	Implement a Story from an execution plan
`prepare-execution-plan`	—	File-level decomposition of a high-level plan for Tier 2/3 Stories
`qa-review`	SKILL-QA-REVIEW-001	Validate implemented code against acceptance criteria — the hard quality gate
`remediate-failures`	SKILL-REMEDIATE-FAILURES-001	Correct failures detected during QA review

Cross Skills (selected)

Skill	ID	Description
`eval-run`	SKILL-CRS-025	Evaluate any output file against a structured evals.yaml assertions file and produce a score report with per-assertion pass/fail results. Activate when the Discovery Agent runs the Skill Optimize protocol to measure output quality or detect regressions.
`skill-optimize`	SKILL-CRS-026	Run a structured evaluate-analyze-improve cycle on any GAAI skill to measure quality, detect regressions, and propose targeted improvements. Activate when a skill needs baseline evaluation, after SKILL.md modifications, or when friction-retrospective flags a skill.
`pattern-transfer`	SKILL-CRS-027	Discover structurally similar patterns across domains, assess transfer viability via structural invariant checking, and propose domain adaptations with risk gates. Activate when Discovery identifies a problem that may have been solved in another domain.
`memory-delta-triage`	SKILL-MEMORY-DELTA-TRIAGE-001	Apply three deterministic heuristics to a single memory-delta and produce a structured triage verdict. Activate when Discovery processes raw memory-deltas from `contexts/artefacts/memory-deltas/`.

→ discovery/ — skills that produce artefacts → delivery/ — skills that orchestrate and execute → cross/ — skills for memory, context, governance → domains/ — domain-specific skill packs → Back to GAAI.md