Auto-sync

Every state-changing agents command runs this wrapper around its core logic:

1. git pull --ff-only
2. (the actual agents logic — fetch, lockfile mutate, symlink…)
3. git add -A agents.toml agents.lock.toml skills/ instructions/ agents/
4. git commit -m "<auto-generated message>"
5. git push

You never invoke git directly. The lockfile is always in sync with the remote before you mutate, so two machines can’t accidentally fork the truth.

Read-only commands stay local

skills list, skills show, status, project list, and remote list never touch the network or git. skills find queries the skills.sh registry but never writes to git. To check for remote drift, run agents apply — that triggers the pre-pull.

Soft-fail on every git stage

Stage failure	Behavior
Pre-pull network error	Warn, proceed with local lockfile state.
Pre-pull fast-forward refused	Warn, continue (local commits will push next).
Push rejected (remote moved)	Auto-pull-rebase, push again.
Push to no-remote (scaffolded repo, no origin yet)	Silently skip, warn once.
Pre-pull would create a true conflict	Hard error. Resolve manually, then re-run.

In every soft-fail case, your local change is not rolled back — the next successful operation will sync it up.

Explicit sync

Run agents sync when you want to reconcile the agents-config repo with git without changing the lockfile. It runs git pull --rebase --autostash, then git push. It does not stage or commit working-tree changes.

Opt-out

Either flag works:

agents --no-sync skills add foo/bar --skill xyz -y
AGENTS_NO_SYNC=1 agents skills add foo/bar --skill xyz -y

Use this when you want to batch several edits and commit yourself, or on a devbox without network access.

What goes in each commit message

Deterministic, one commit per command:

Command	Message
skills add foo/bar --skill A --skill B	add github:foo/bar :: A, B
skills update	update :: 3 entries refreshed
skills update foo	update :: foo (sha abc → def)
skills remove foo	remove :: foo
skills deactivate foo	deactivate :: foo
skills activate foo	activate :: foo
import foo	import :: foo (github:owner/repo)
apply (only when tree_sha drift detected)	apply :: 5 entries materialized