> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getgaal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure skills

> Cookbook for the skills: block of gaal.yaml.

This page is a working reference for the `skills:` block. For the conceptual model, see [Concepts → Skills](/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:

```bash theme={"theme":"nord"}
gaal skill search frontend
gaal skill install frontend-design
```

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.

```yaml theme={"theme":"nord"}
schema: 1
repositories: {}
skills:
  - source: anthropics/skills
    registry: skills.sh
    select:
      - frontend-design
    agents: ["*"]
    global: true
mcps: []
```

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:

```text theme={"theme":"nord"}
frontend-design
skills.sh/frontend-design
anthropics/skills:frontend-design
skills.sh/anthropics/skills:frontend-design
```

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

```yaml theme={"theme":"nord"}
skills:
  - source: vercel-labs/agent-skills
    agents: ["*"]
```

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

## Install specific skills, in specific agents

```yaml theme={"theme":"nord"}
skills:
  - source: anthropics/skills
    agents:
      - claude-code
      - github-copilot
    select:
      - frontend-design
      - skill-creator
```

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

## Install globally (across every project on this machine)

```yaml theme={"theme":"nord"}
skills:
  - source: my-utils
    agents: [claude-code]
    global: true
```

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

## Mix project and global

```yaml theme={"theme":"nord"}
skills:
  # global utilities, available in every project
  - source: my-utils
    agents: [claude-code, cursor]
    global: true

  # codebase-specific reviewer, only for this project
  - source: ./skills/reviewer
    agents: ["*"]
    global: false
```

## Source from a local directory

```yaml theme={"theme":"nord"}
skills:
  - source: ./company-skills
    agents: [claude-code, cursor]
    global: false
```

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

```yaml theme={"theme":"nord"}
skills:
  - source: https://github.com/microsoft/github-copilot-for-azure
    agents: [github-copilot]
    global: true
```

## Source from SSH

```yaml theme={"theme":"nord"}
skills:
  - source: git@github.com:acme/private-skills.git
    agents: ["*"]
```

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.

```yaml theme={"theme":"nord"}
skills:
  - source: ./company-skills
    agents: [codex]
    target_subdir: team
```

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`:

```bash theme={"theme":"nord"}
gaal sync --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:`.

## Related

<CardGroup cols={2}>
  <Card title="gaal skill" icon="terminal" href="/cli/skill" />

  <Card title="Concepts: skills" icon="brain" href="/concepts/skills" />

  <Card title="Agent integrations" icon="robot" href="/agents/overview" />

  <Card title="Pruning" icon="scissors" href="/workflows/pruning" />

  <Card title="Schema: skills" icon="file-code" href="/schema/skills" />
</CardGroup>