Skip to main content

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.

gaal.yaml is the entire user-facing surface of gaal. Everything else, commands, audit, planning, rendering, exists to read this file and reconcile it against your filesystem.

​
File location

gaal looks for the configuration file in this order:
  1. The path passed to --config, if any.
  2. gaal.yaml in the current working directory.
  3. ~/.config/gaal/config.yaml (user scope).
  4. /etc/gaal/config.yaml (system scope).
When multiple are present, the higher-priority file overrides the lower one. See Scopes for the merge rules.

​
Top-level keys

gaal.yaml
schema: 1

repositories:
  # local-path: { type, url, version }

skills:
  # - { source, agents, global, target_subdir, select }

content:
  # - { source, agents, global, root, paths }

mcps:
  # - { name, agents, global, source | inline }

tools:
  # - <name> or { name, hint }

hooks:
  # pre-sync: [...]
  # post-sync: [...]

telemetry: false   # opt-in, user/system scope only
KeyTypeRequiredPurpose
schemaintegerrecommendedConfig version, always 1 for the current gaal release. Stable forever.
repositoriesmapnoVCS-managed sources cloned into your workspace.
skillsarraynoSKILL.md collections to install per agent.
contentarraynoGeneric file and directory mappings for agent instructions, rules, commands, and settings.
mcpsarraynoMCP server entries upserted into agent config files.
toolsarraynoCLI tools expected on PATH, reported by gaal doctor.
hooksobjectnoCommands that run before and after gaal sync.
telemetryboolnoOpt-in anonymous usage telemetry. Off by default.
Every key is independent. A file with only skills: is a valid gaal.yaml and a sync only touches skills.

​
A complete example

gaal.yaml
schema: 1

repositories:
  src/gaal:
    type: git
    url: https://github.com/getgaal/gaal.git
    version: main

  src/dataset:
    type: tar
    url: https://example.com/releases/dataset-2024.tar.gz
    version: dataset-2024

skills:
  - source: anthropics/skills
    agents: ["*"]
    select: [frontend-design, skill-creator]

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

content:
  - source: ./agent-files
    agents: [claude-code]
    root: workspace
    paths:
      AGENTS.md: CLAUDE.md

mcps:
  - name: filesystem
    agents: [claude-code]
    global: true
    inline:
      command: uvx
      args: [mcp-server-filesystem, ~/projects]

  - name: github
    source: https://example.com/mcp/github.json
    agents: [claude-code, github-copilot]
    global: true

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

hooks:
  post-sync:
    - command: git
      args: ["-C", "~/docs", "pull", "--ff-only"]

​
Validate before sync

Two ways to check a gaal.yaml is well-formed: 
$ gaal doctor
✓ config: gaal.yaml is valid

$ gaal sync --dry-run
plan:
  ...
Both surface schema errors with line numbers.

​
IDE auto-completion

gaal schema writes the JSON Schema for gaal.yaml. Drop it into your editor and you get inline validation and completion as you type: 
gaal schema -f schema.json
See gaal schema for VS Code and JetBrains setup.

Repositories

Skills

MCP servers

Scopes