SKILL.md file (and any supporting files in the same directory). Coding agents pick up skills from a known directory on disk, .claude/skills, .cursor/skills, .github/skills, and so on.
gaal’s job is to take a single skill source and install it into the right directory for every agent you target.
Why skills are interesting
Each agent has its own skill convention, but the content is portable. Acode-review skill written for Claude Code works in Cursor, Codex, and Copilot with no changes. Without gaal you copy the directory three times. With gaal you write one entry and let the renderers fan it out.
Sources
A skill source can be any of:
A source can contain one or many skills. Each top-level directory inside the source that contains a
SKILL.md is one skill.
Registry search and install
You can writeskills: entries by hand, or use the registry commands to discover and add them:
skills.sh. Search is config-optional, so you can run it before creating a gaal.yaml.
For the skills.sh registry, gaal discovers matches through the official CLI surface, npx skills find <query>. Make sure npx is available on PATH. No VERCEL_OIDC_TOKEN or skills.sh API auth is required for gaal’s v1 registry workflow.
Install resolves a registry reference, writes or updates the selected config file, and runs gaal sync by default. It defaults to global installation and writes agents: ["*"] explicitly:
registry: records where the entry came from. Sync still uses source: to fetch the skills. gaal does not run npx skills add; it uses registry discovery to write normal skills: config, then syncs that config.
Targeting agents
Every skill entry says which agents to install it for:["*"] is a wildcard that resolves at sync time to the agents currently installed on this machine. Agents that aren’t installed are skipped. Use gaal sync --force to install into every registered agent regardless of whether the agent is detected.
Project vs global
Each entry chooses one of two install layouts:
Use project for skills tied to one repo (CI helpers, codebase-specific reviewers). Use global for skills you want available everywhere (your personal git-helper, formatting preferences).
Manual
skills: entries default to global: false when the field is omitted. gaal skill install defaults to global installation and writes global: true.Selecting a subset
By default every skill in the source is installed. Useselect: to install only specific ones:
What gets written where
For every (source × agent) pair, gaal writes the selected skills under the agent’s skills directory using the agent’s native layout. For example, with this entry:Behaviour during sync
- Skills already at the right version are reported
= unchanged. - New skills are added.
- Skills that are no longer in the config are left alone unless you pass
--prune. - Sources are fetched once per sync and reused across all agents that target them.