agentdots-sync

Safely synchronize explicitly selected local agent assets with a Git remote. This Skill copies files; it does not translate AGENTS.md, CLAUDE.md, platform rules, or configuration formats into one another.

Platform selection

Use --platform to select safe defaults. Run --list-platforms when the platform or defaults are uncertain. Built-in profiles cover codex, claude-code, opencode, grok-build, codebuddy-code, workbuddy, and custom; aliases such as claude, grok, and codebuddy resolve to canonical names.

WorkBuddy and custom require an explicit --root; custom also requires one or more --asset. For project-level assets, override both --root and --asset rather than assuming that global and project layouts match. Use this Skill only where the agent can access the local filesystem and execute Python; browser-only chat surfaces cannot synchronize local configuration directories.

Safety contract

Default to read-only inspection. Before a write, replacement, rollback, or push:

1. Resolve the canonical platform, direction, local root, backup directory, remote, branch, and every selected asset.
2. Show those exact targets and obtain explicit authorization for this run. “Sync it” is not permission to choose a direction or overwrite files.
3. Execute only the approved command with --yes. Stop on any Git, validation, lock, or permission failure.

Never use cross-platform defaults to copy one platform's instruction file over another platform's differently named file. If the user wants format conversion, treat that as a separate transformation task.

Resolve the script from this loaded Skill's actual directory. Replace <skill-root> below with that absolute path.

Workflow

python3 <skill-root>/scripts/sync.py --list-platforms
python3 <skill-root>/scripts/sync.py --platform <platform> --doctor
python3 <skill-root>/scripts/sync.py --platform <platform> --plan
python3 <skill-root>/scripts/sync.py --platform <platform> --apply --plan --remote <url> --branch <branch>

After the user approves the exact plan, use one mutation mode:

python3 <skill-root>/scripts/sync.py --platform <platform> --restore --yes --remote <url> --branch <branch>
python3 <skill-root>/scripts/sync.py --platform <platform> --apply --yes --remote <url> --branch <branch>
python3 <skill-root>/scripts/sync.py --platform <platform> --push --yes --remote <url> --branch <branch> --message <text>
python3 <skill-root>/scripts/sync.py --platform <platform> --rollback --yes

Repeat --asset <path> to override profile assets. Use --root <path> or --backup-dir <child-path> only when the resolved profile defaults do not match the user's real layout.

--apply and --restore back up existing selected local assets before replacement. A first apply with no existing selected asset has nothing to back up. Rollback protects current requested assets, then restores only the requested intersection recorded in the selected backup manifest. Push stages only selected paths and never force-pushes.

Stop conditions

Never install or authenticate Git tooling, create or guess repositories or branches, resolve conflicts automatically, synchronize a home directory, bypass target validation, remove an unverified lock, or run concurrent mutations against the same root.