> ## 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.

# skills

> SKILL.md collections to install per agent.

```yaml theme={"theme":"nord"}
skills:
  - source: <string>
    registry: <string>      # optional
    agents: <[string] | ["*"]>
    global: <bool>          # optional, default false
    target_subdir: <string> # optional
    select: <[string]>      # optional
    tools: <[ToolEntry]>    # optional
```

## Type

`array[SkillEntry]`

## Required

No. Omit `skills:` if you have nothing to install.

## Entry fields

### `source`

| Field    | Type   | Required |
| -------- | ------ | -------- |
| `source` | string | yes      |

Where the skills come from. Accepts:

| Format           | Example                                |
| ---------------- | -------------------------------------- |
| GitHub shorthand | `anthropics/skills`                    |
| Full HTTPS URL   | `https://github.com/anthropics/skills` |
| Git SSH URL      | `git@github.com:anthropics/skills.git` |
| Local path       | `./company-skills` or `~/my-skills`    |

The source can contain one or many skills. Each top-level subdirectory containing a `SKILL.md` is one skill.

### `registry`

| Field      | Type   | Required |
| ---------- | ------ | -------- |
| `registry` | string | no       |

Registry provenance for entries created by `gaal skill install`, usually `skills.sh`.

`registry` does not change how `gaal sync` fetches skills. Sync remains source-based and uses `source:`. Registry-backed entries are still distinct from legacy entries that have the same source but no `registry:`.

### `agents`

| Field    | Type             | Required |
| -------- | ---------------- | -------- |
| `agents` | array of strings | yes      |

Either a list of registry names (`[claude-code, cursor, codex]`) or the wildcard `["*"]`.

`["*"]` resolves at sync time to **agents currently detected on this machine**. Use `gaal sync --force` to expand it to every registered agent regardless of detection.

For registry installs, omitted `agents` and `agents: ["*"]` are not treated as equivalent. `gaal skill install` writes `agents: ["*"]` explicitly when you accept the default.

### `global`

| Field    | Type | Required | Default |
| -------- | ---- | -------- | ------- |
| `global` | bool | no       | `false` |

| Value   | Install layout                           |
| ------- | ---------------------------------------- |
| `false` | `./.<agent>/skills/<name>` (per-project) |
| `true`  | `~/.<agent>/skills/<name>` (per-user)    |

### `target_subdir`

| Field           | Type   | Required |
| --------------- | ------ | -------- |
| `target_subdir` | string | no       |

Optional subdirectory under the resolved agent skills directory. Use it when an agent supports grouping skills, or when you want two entries from the same source to land in different folders.

The value must be relative and cannot contain `..`.

### `select`

| Field    | Type             | Required |
| -------- | ---------------- | -------- |
| `select` | array of strings | no       |

Names (matching subdirectory names in the source) of specific skills to install. Empty or omitted = install everything in the source.

### `tools`

| Field   | Type                                | Required |
| ------- | ----------------------------------- | -------- |
| `tools` | array of [ToolEntry](/schema/tools) | no       |

CLI tools this skill collection depends on. Checked for presence by `gaal doctor` and surfaced in the `gaal sync` missing-tool banner. Accepts the same shorthand and full forms as the top-level `tools:` block — see [Tools](/schema/tools).

## Example

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

  - source: anthropics/skills
    agents: ["*"]
    global: false

  - source: vercel-labs/agent-skills
    agents: [claude-code, cursor]
    select: [test-writer, code-reviewer]
    global: true

  - source: ./company-skills
    agents: [claude-code, cursor]
    global: false

  - source: ./company-skills
    agents: [codex]
    target_subdir: team

  - source: obra/superpowers
    agents: ["*"]
    tools:
      - name: tree-sitter
        hint: "brew install tree-sitter"
```

## Behaviour

* Sources are fetched once per sync and reused across all targeted agents.
* Skills already at the right version are reported `= unchanged`.
* Skills no longer in the config are left alone unless you pass `--prune`.
* If `select:` is empty or omitted, the entry covers every skill in the source.
* Install identity is based on `source`, `registry`, normalized `agents`, `global`, and `target_subdir`.

## Related

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

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

  <Card title="Configure skills" icon="gear" href="/configure/skills" />

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