Skip to main content
tools:
  - <name>                  # bare-string shorthand
  - name: <string>
    hint: <string>          # optional

​
Type

array[ToolEntry]

​
Required

No. Omit tools: if you don’t depend on any external CLIs. When absent everywhere, gaal doctor renders no Tools section and gaal sync prints no banner.

​
Where it can appear

tools: is valid in two places:
LocationMeaning
Top level of gaal.yamlTools required by the workspace as a whole.
Inside a skills[] entryTools required specifically by that skill collection.
Both forms accept the same schema. At check time, gaal unions the two lists and deduplicates by name; a top-level entry wins over a per-skill entry with the same name. See Behaviour below.

​
Entry fields

​
name

FieldTypeRequired
namestringyes
The executable name to look up on PATH. Uses Go’s exec.LookPath, so Windows .exe resolution is handled automatically.

​
hint

FieldTypeRequired
hintstringno
Free-form install instruction shown when the tool is missing. Typically a one-liner like brew install tree-sitter or a URL. gaal does not parse or execute the hint; it’s displayed as-is.

​
Bare-string shorthand

A plain string is equivalent to an object with only name set: 
tools:
  - gh          # same as { name: gh }
  - rtk         # same as { name: rtk }
Mix shorthand and full form freely: 
tools:
  - gh
  - rtk
  - name: tree-sitter
    hint: "brew install tree-sitter"

​
Example

gaal.yaml
schema: 1

tools:
  - gh
  - name: rtk
    hint: "cargo install rtk"

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

​
Behaviour

  • Presence only. gaal runs exec.LookPath(name) for each entry. No version parsing, no execution of the tool.
  • Dedup by name. Top-level and per-skill tools: are unioned; the first occurrence wins. Top-level is collected before per-skill, so a workspace-level entry with a hint overrides a bare per-skill mention of the same name.
  • Merge across scopes. tools: follows the standard config merge chain (system → user → workspace). A higher-priority scope replaces lower-priority entries with the same name.
  • gaal doctor. Adds a tools: section to the output. Found tools render ✓ <name> (on PATH: <resolved>). Missing tools render ! <name> — missing from PATH (required by: <source>; hint: <hint>) and bump the exit code to 1 (warning).
  • gaal sync. Prints a compact one-time banner to stderr at the start of sync listing any missing tools, then proceeds normally. Exit code is unaffected; sync never blocks on missing tools.

​
Out of scope

The following are intentionally not supported today:
  • Version checks. --version parsing varies too much across tools.
  • Installation. gaal does not install tools. hint is display-only.
  • Skill-repo-declared tools. Tools must be declared in your own gaal.yaml; gaal does not read tool requirements from inside skill source repos.

gaal doctor

gaal sync

Using gaal doctor

The gaal.yaml file