Create Skill

---
name: create-skill
description: Guide creation of a new GAAI skill following the agentskills.io spec and GAAI best practices. Activate when adding a new skill to the .gaai/core/skills/ catalog.
license: ELv2
compatibility: Works with any filesystem-based AI coding agent
metadata:
  author: gaai-framework
  version: "1.0"
  category: cross
  track: cross-cutting
  id: SKILL-CRS-016
  updated_at: 2026-02-26
  status: stable
inputs:
  - skill_intent: description of what the skill should do
  - skill_category: discovery|delivery|cross
  - skill_track: discovery|delivery|cross-cutting
  - existing_skills: list of current skills to check for overlap
outputs:
  - .gaai/core/skills/{category}/{skill-name}/SKILL.md
  - updated .gaai/core/skills/README.skills.md entry
---

# Create Skill

## Purpose / When to Activate

Activate when:
- A new capability is needed that no existing skill covers
- A skill is being extracted from agent logic that has become reusable
- Extending a forked GAAI installation with project-specific skills

This skill is self-referential: it uses the agentskills.io spec to author a spec-compliant skill.

---

## Prerequisites

Before activating:
1. Confirm no existing skill already covers the intended capability (check `README.skills.md`)
2. Confirm the new skill is a **pure execution unit** — it executes, it does not reason
3. Confirm the skill belongs to exactly one category (discovery / delivery / cross)
4. Have a clear, one-sentence description of: WHAT it does and WHEN to activate it

If a skill "appears to think" in the design, it is wrongly scoped. Redesign or split.

---

## Process

### Step 1 — Name and classify

Derive the skill name from the action it performs:
- Use lowercase kebab-case
- Name should be a verb phrase: `generate-stories`, `qa-review`, `memory-compact`
- Category: discovery (produces artefacts) | delivery (implements/validates) | cross (shared utility)

Verify name does not conflict with an existing skill in `README.skills.md`.

### Step 2 — Define inputs and outputs explicitly

List every input the skill requires. Be specific:
- What file paths does it read?
- What structured data does it receive from the invoking agent?
- What context is assumed to be present?

List every output the skill produces:
- File paths created or modified
- Structured data returned to the agent
- Side effects (backlog state changes, memory updates)

If inputs or outputs are unclear, the skill is not ready to be written. Clarify first.

### Step 3 — Write the SKILL.md frontmatter

```yaml
---
name: {skill-name}                  # matches directory name exactly
description: {one sentence}         # WHAT it does + WHEN to activate
license: ELv2
compatibility: Works with any filesystem-based AI coding agent
metadata:
  author: {author}
  version: "1.0"
  category: {discovery|delivery|cross}
  track: {discovery|delivery|cross-cutting}
  id: SKILL-{CAT}-{NNN}
  updated_at: {YYYY-MM-DD}
  status: stable|experimental       # use experimental for new/unproven skills
inputs:
  - {input_1}: {description}
  - {input_2}: {description}
outputs:
  - {output_path_or_description}
---
```

**Description rule:** Must be one sentence, ≤ 1024 characters. Format:
> "{Verb phrase that describes the output} when {activation condition}."

Example: "Generate Stories from an Epic with testable acceptance criteria when Discovery is refining a new feature scope."

### Step 4 — Write the skill body

Required sections:

```markdown
# {Skill Title}

## Purpose / When to Activate
When and why an agent should invoke this skill. Be explicit.

## Process
Numbered steps. Each step produces a specific output or advances the state.
Steps must be deterministic: same inputs → same outputs.

## Quality Checks
What must be true for the output to be acceptable.
List as assertions, not descriptions.

## Outputs
Exact file paths or structured outputs produced.

## Non-Goals
What this skill must NOT do. Prevents scope creep.
```

Add a final line if applicable:
> **No silent assumptions. Every {X} becomes explicit and governed.**

### Step 5 — Create directory and file

```
.gaai/core/skills/{category}/{skill-name}/SKILL.md
```

`SKILL.md` filename is always uppercase (spec requirement).

Optional subdirectories (create only if needed):
- `references/` — supporting documents the skill references
- `assets/` — templates or static files the skill produces

### Step 6 — Update ALL relevant indices (MANDATORY)

This step is non-negotiable. A skill that is not indexed is invisible to agents.

**6a. Skills index YAML:**
- Invoke `build-skills-index` to regenerate both `.gaai/core/skills/skills-index.yaml` (core) and `.gaai/project/skills/skills-index.yaml` (project)
- Verify the new skill appears in the generated index with correct `id`, `name`, `path`, and `tags`

**6b. Skills README:**
- Core skills: update `.gaai/core/skills/README.skills.md` — add the skill to the appropriate category section
- Project skills: update `.gaai/project/skills/README.md` — add the skill to the appropriate section

**6c. Domain index (if domain-scoped skill):**
- If the skill belongs to a domain (e.g., `domains/content-production/`), update the domain's `index.md` in memory:
  - `.gaai/project/contexts/memory/domains/{domain}/index.md` — add a row to the skills table
- This ensures domain sub-agents discover the skill when loading their domain context

**Failure to update any of these indices means the skill is effectively invisible** — agents cannot discover it, and it will not be loaded during delivery or discovery sessions.

### Step 7 — Reference in agent file

If the skill is intended for a specific agent (Discovery) or a delivery sub-agent, add it to the agent's skill list in:
- `.gaai/core/agents/discovery.agent.md` — Skills Used section
- Or the relevant sub-agent file in `.gaai/core/agents/sub-agents/` (planning, impl, qa)
- Or neither, if it's a general cross skill invoked opportunistically

---

## Quality Checks

- Skill name matches directory name exactly
- `SKILL.md` frontmatter has `name` and `description` at top level (spec requirement)
- Description is ≤ 1024 characters, one sentence
- All inputs are explicitly declared
- All outputs are explicitly declared with file paths where applicable
- Skill body has all 5 required sections
- Non-Goals section explicitly prevents scope creep
- `README.skills.md` updated
- `health-check.sh` passes after creation

---

## Non-Goals

This skill must NOT:
- Design agent behavior or orchestration logic (that is an agent concern)
- Make decisions about when to activate the skill (the invoking agent decides)
- Merge or replace an existing skill (deprecation requires explicit human decision)

**A skill that appears to think is wrongly designed. Redesign before authoring.**