Skip to main content
This page is a working reference for the skills: block. For the conceptual model, see Concepts → Skills.

​
Add a skill from the registry

Use gaal skill search to discover registry skills, then gaal skill install to add one to your config:
By default, install uses the skills.sh registry, writes to the selected config file, installs globally, targets every detected agent with agents: ["*"], and runs gaal sync. For the skills.sh registry, gaal uses the official CLI surface through npx skills find for discovery and lookup. Make sure npx is available on PATH. No VERCEL_OIDC_TOKEN or skills.sh API auth is required.
Use --project for a project-local entry, --agents claude-code,codex to target specific agents, or --no-sync to update YAML without syncing. gaal does not run npx skills add for the final installation. It writes normal skills: config and then syncs it, so gaal.yaml remains the source of truth. Accepted refs include:
In non-interactive shells, pass --yes before install mutates the config. If a loose ref is ambiguous, gaal prints the choices and exits non-zero; --yes does not auto-pick.

​
Install everything from a GitHub repo to every detected agent

Defaults: global: false (project-local), every skill in the source.

​
Install specific skills, in specific agents

select: matches the skill directory name in the source repo.

​
Install globally (across every project on this machine)

Files land under ~/.claude/skills/ and are visible to Claude Code in every project.

​
Mix project and global

​
Source from a local directory

Relative paths resolve against the directory of the gaal.yaml file. ~/-prefixed paths resolve against the user’s home directory.

​
Source from a full URL

​
Source from SSH

Authentication uses your local SSH agent.

​
Install into a subdirectory

Use target_subdir: when you want selected skills placed under a folder inside the resolved agent skills directory.
The subdirectory must be relative and cannot contain ...

​
Force install into every registered agent

By default, the ["*"] wildcard expands only to agents detected on this machine. If you want gaal to populate skill directories for agents that aren’t installed yet (for example, to pre-stage a fresh machine), use --force:
This applies only to entries with agents: ["*"]. Explicit agent lists are honoured as-is.

​
Behaviour at sync time

  • Skills already at the right version are reported = unchanged.
  • New skills are added.
  • Skills no longer in the config are left in place unless you pass --prune.
  • Each skill source is fetched once per sync and reused across all agents that target it.
  • For registry-installed entries, registry: is provenance only. Sync continues to fetch the source:.

gaal skill

Concepts: skills

Agent integrations

Pruning

Schema: skills