Composing Skills and Skill Sets

An agent that does one job needs one set of instructions. An agent that does the same job in two different contexts needs two — and hardcoding load_skill calls forces you to pick one, or to ship two agents. Skill sets solve that. You bundle a small library of skills with your agent, group them into named sets in gaia-agent.yaml, and let exactly one set activate per launch — chosen explicitly, or by whatever runtime signal your agent already has. This guide builds a worked example: a code-review agent that reviews differently for a library than for an application.

Prerequisites: you have an agent package with a gaia-agent.yaml — see Custom Agents. Background on the format itself is in Agent Skills and Skill Format.

1. Bundle the skills

Put each skill in its own directory inside your importable package, so the wheel and any frozen binary ship it:

my_agent/
├── __init__.py
├── agent.py
└── skills/
    ├── review-basics/SKILL.md
    ├── api-compatibility/SKILL.md
    ├── changelog-discipline/SKILL.md
    └── ux-regression/SKILL.md

A skills/ folder beside your package rather than inside it works from a source checkout and then vanishes from an installed wheel — the classic works-on-my-machine failure. Keep it inside the package and declare it as package data ([tool.setuptools.package-data]), plus --add-data if you freeze a binary.

A skill is a SKILL.md: frontmatter plus a Markdown body. Keep the body short — it is injected into the system prompt when the skill loads, and every token it takes is a token your tool results no longer have.

---
name: api-compatibility
description: Check a change for breaking API surface. Use when reviewing a diff that touches public functions, classes, or types.
version: 0.1.0
metadata:
  gaia:
    tools_required:
      - read_file
      - search_code
---

# API Compatibility

A change is breaking if an existing caller stops compiling or starts behaving
differently. Removed or renamed public symbols, narrowed parameter types,
widened return types, and changed defaults all qualify.

- Identify the public surface the diff touches, then find its callers with
  `search_code` before judging severity.
- A new required parameter is breaking; a new optional one is not.
- Report each finding as `<symbol> · <what breaks> · <who calls it>`.

tools_required names registry tools the skill’s recipe consumes — it does not grant anything. A name your agent has not registered is logged at load time, so a skill that cannot execute its own recipe is diagnosable rather than silently useless.

2. Declare the sets

Three top-level keys in gaia-agent.yaml:

id: my-agent
name: My Review Agent
version: 0.1.0
language: python

# Always on, whichever set is active.
skills:
  - review-basics

# Named, mutually exclusive. Exactly ONE is active per launch.
skill_sets:
  library:
    - api-compatibility
    - changelog-discipline
  application:
    - ux-regression
    - changelog-discipline

# Applies when nothing selects a set.
default_skill_set: application

changelog-discipline is in both sets — sets overlap, they do not partition. The one thing a set may not do is re-declare a skill that is already in the always-on skills: list; that contradiction fails to parse. An entry is a plain name or a mapping:

skill_sets:
  library:
    - api-compatibility                # required (the default)
    - name: changelog-discipline
      version: ">=0.1.0"               # checked against the installed version
      required: false                  # missing/incompatible ⇒ logged, skipped

3. Point the agent at both

from pathlib import Path
from typing import ClassVar, List, Optional

from gaia.agents.base.agent import Agent

_HERE = Path(__file__).resolve().parent


class MyReviewAgent(Agent):
    # Highest-precedence discovery root: the skills you bundle always win over a
    # same-named user or Claude Code copy. Both lines below are optional — a
    # skills/ folder and a gaia-agent.yaml beside this module are found without
    # them; name them explicitly only when they live somewhere else.
    SKILL_DIRS: ClassVar[List[str]] = [str(_HERE / "skills")]
    # Opt in to the declarative blocks.
    SKILL_MANIFEST: ClassVar[Optional[str]] = str(_HERE / "gaia-agent.yaml")

That is enough. Agent.__init__ resolves a set and loads it — the always-on skills plus that set’s, in declaration order.

4. Choose the set at runtime

Selection resolves in one order, every time:

Explicit — `skill_set=`

MyReviewAgent(skill_set="library"), which your CLI surfaces as --skill-set library. Highest precedence, and never second-guessed.

Your selector hook

Override select_skill_set() to answer from state the agent already has.

`default_skill_set`

The manifest’s declared default.

The hook is one method:

    def select_skill_set(self) -> Optional[str]:
        """Pick a set from the repository being reviewed."""
        kind = self.detect_project_kind()      # your own logic
        if kind is None:
            # Unknown is a real answer. Returning None resolves the manifest's
            # default explicitly — never guess a set.
            return None
        return "library" if kind == "library" else "application"

Never guess, and never fall back. A name neither the manifest declares raises SkillSetError listing the valid sets — whether it came from --skill-set or from your hook. An agent running with the wrong capability bundle is worse than one that refuses to start, and a hook that returns a set it invented is a wiring bug, not a reason to improvise.

5. Verify what actually loaded

agent = MyReviewAgent(skill_set="library")

agent.active_skill_set        # 'library'
sorted(agent.loaded_skills)   # ['api-compatibility', 'changelog-discipline', 'review-basics']

The startup log names the set, the rule that chose it, and every skill that loaded:

Skill set 'library' active (chosen by: explicit) — loaded 3 of 3 declared
skill(s): review-basics, api-compatibility, changelog-discipline

And from the CLI:

gaia skill list          # every discovered skill, with its root and precedence
gaia skill info api-compatibility

Switching sets mid-session is one call — the previous set’s skills are unloaded first, so a stale set never lingers in the prompt:

agent.load_skill_set("application")

Budget the set

Loading a set injects each body into the system prompt. Three skills of ~250 tokens each is ~750 tokens gone from a window your tool results were already using — enough to overflow a tight context and turn a working run into a context_length_exceeded error. Two habits keep it safe:

Keep bodies short. Procedure and judgement calls, not prose. If a skill needs reference material, put it in a file the body links to — resources load only when the agent actually reads them.
Subtract the cost where you budget context. If your agent sizes a tool-result envelope against the window, take the loaded set’s cost out of that budget. The email agent’s bulk-triage path does exactly this — and measure the result: its three-skill personal set costs ~1,334 prompt tokens, cutting that envelope from 6,144 to 4,810 (the four-skill work set, to 4,070). Losing a fifth to a third of the room for tool results is why its sets are currently switched off pending an eval.

A worked example in the tree

The email agent is the reference implementation of this pattern. It bundles six instruction-only skills and its manifest carries two sets — personal (triage, newsletter digests, travel itineraries) and work (triage, meeting scheduling, action-item extraction, escalation routing), with inbox-triage in both — plus a selector that keys off the connected mailbox: a personal Microsoft account picks personal, a work/school account picks work. A Gmail mailbox carries no equivalent signal, so its kind is unknown, the selector returns None, and the manifest’s default applies — explicitly, never by assuming a work mailbox is personal.

Read it as a code reference, not as “skills are on by default in a shipped agent”: the email agent’s skill_sets: and default_skill_set: blocks are commented out in gaia-agent.yaml pending an eval that shows the skills help, so on the shipped binary it loads no skills at all. The wiring is what’s worth copying; whether to turn it on is an eval question for your own agent too.

Agent Skills — architecture, discovery, selection
Skill Format — the full field grammar
Custom Agents — building the agent the skills attach to
CLI Reference → Skills — gaia skill list|info|create|import|export

Getting Started

C++ Framework

Python Framework

Composing Skills and Skill Sets

1. Bundle the skills

2. Declare the sets

3. Point the agent at both

4. Choose the set at runtime

5. Verify what actually loaded

Budget the set

A worked example in the tree

​1. Bundle the skills

​2. Declare the sets

​3. Point the agent at both

​4. Choose the set at runtime

​5. Verify what actually loaded

​Budget the set

​A worked example in the tree

​Related

1. Bundle the skills

2. Declare the sets

3. Point the agent at both

4. Choose the set at runtime

5. Verify what actually loaded

Budget the set

A worked example in the tree

Related