Skip to main content
By the end of this page you’ll have a working gaal.yaml, every detected agent skill imported into it, and a clean gaal sync that completes without errors.

​
1. Confirm the install

$ gaal version
gaal v0.1.0
built 2026-04-18T09:00:00Z
If this fails, head back to Install.

​
2. See what’s on your machine

gaal audit scans your project, your home directory, and each agent’s package-manager paths for skills and MCP servers, without writing anything. 
$ gaal audit
discovered:
  skills (project)
    .claude/skills/code-review     (claude-code)
    .cursor/skills/test-writer     (cursor)
  skills (global)
    ~/.claude/skills/git-helper    (claude-code)
  mcps
    ~/.config/claude/claude_desktop_config.json
      filesystem, git
This is read-only, nothing is changed yet.

​
3. Initialise gaal.yaml

The interactive wizard turns the audit into a real config file: 
$ gaal init
? How should we create your gaal.yaml?
  ▸ Import everything detected on this machine
    Start from an empty documented skeleton
? Where should this configuration apply?
  ▸ Project (./gaal.yaml)
    Global (~/.config/gaal/config.yaml)
After confirming, init writes a fully-populated gaal.yaml to the chosen path.
No TTY? Use the non-interactive form:
gaal init --import-all --scope project
--empty and --import-all are mutually exclusive; one is required when stdin isn’t a TTY.

​
4. Preview the sync

Always preview before the first real sync. --dry-run runs the full planner without touching disk. 
$ gaal sync --dry-run
plan:
  repositories
    + clone   src/example          (git, main)
  skills
    + install code-review          → claude-code, cursor
    = unchanged git-helper         → claude-code
  mcps
    + upsert  filesystem           → claude_desktop_config.json
Exit codes: 0 = nothing to do, 1 = changes pending, 2 = error.

​
5. Sync for real

$ gaal sync
✓ src/example          cloned
✓ code-review          installed in claude-code, cursor
✓ filesystem           upserted in claude_desktop_config.json
sync complete in 1.2s

​
6. Check your work

$ gaal status
repositories
  src/example          git · main · clean
skills
  code-review          claude-code, cursor
  git-helper           claude-code
mcps
  filesystem           ~/.config/claude/claude_desktop_config.json

$ gaal doctor
✓ config: gaal.yaml is valid
✓ skills: all sources reachable
✓ mcps:   all target files writable
✓ agents: 3 installed, 0 misconfigured

​
You’re done

Commit gaal.yaml to your dotfiles repo and gaal sync will reproduce this exact setup on every other machine you own.

How gaal works

The mental model behind sync, audit, and renderers.

Sharing across machines

The dotfiles pattern in detail.

Add an MCP server

Inline definitions and remote sources.

Continuous service mode

Run gaal as a daemon that re-syncs on a schedule.