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

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.
This is read-only, nothing is changed yet.

​
3. Initialise gaal.yaml

The interactive wizard turns the audit into a real config file:
After confirming, init writes a fully-populated gaal.yaml to the chosen path.
No TTY? Use the non-interactive form:
--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.
Exit codes: 0 = nothing to do, 1 = changes pending, 2 = error.

​
5. Optional: add a registry skill

You can search the default registry without changing your config:
For the default skills.sh registry, this uses npx skills find behind the scenes. Make sure npx is available on PATH. You do not need VERCEL_OIDC_TOKEN or skills.sh API auth. Install adds the selected skill to gaal.yaml and runs sync by default:
Use --project if the skill should live only in this repo, or --no-sync if you want to review the YAML before syncing.

​
6. Sync for real

​
7. Check your work

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

Find skills

Search and install registry skills.

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.