Syncing & Distributing Skills

The drift problem in multi-agent environments

Modern developers rarely use a single AI agent tool in isolation. Different workflows leverage Claude Code, Gemini Antigravity, Codex CLI, Cursor, Devin, and GitHub Copilot. Each host harness maintains its own isolated skills configuration directory.

When skills are manually copied between these directories, synchronization breaks down immediately. Enhancements authored in your primary project do not propagate to agent harnesses, bug fixes made during an agent session remain trapped in local caches, and multiple versions of the same skill diverge.

Zero-drift directory junctions

Reactive Skills solves drift at the operating system level using NTFS Directory Junctions on Windows and POSIX symbolic links on macOS and Linux.

Instead of duplicating files, consumer satellites point directly to the authoritative authoring repository. This delivers three concrete benefits:

• Instant bidirectional updates: Edits in your authoring repository are instantly active across all agent runtimes with zero latency.
• In-session learning captured: When an agent refines a skill during a pairing session, the changes are made directly in the git-tracked authoring repo.
• Zero disk overhead: Avoids duplicating large multi-state skill trees across ten different harness directories.

1. Synchronizing via AXI CLI

The AXI CLI provides a synchronization entrypoint via axi sync (or npx -y @reactive-skills/axi sync). It can sync an entire workspace or a single target skill.

npx -y @reactive-skills/axi sync tdd-flow

sync: tdd-flow
mode: link (junction)
source: C:\Users\user\Desktop\skills\tdd-flow
targets:
  ~/.agents/skills/tdd-flow → linked
  ~/.claude/skills/tdd-flow → linked
  ~/.gemini/config/skills/tdd-flow → linked
  ~/.devin/skills/tdd-flow → linked
status: 4 linked, 0 errors

Common synchronization commands and flags:

• axi sync — syncs all skills found in registered authoring sources across all satellites.
• axi sync <skill-name> — syncs only the specified skill.
• axi sync <skill-name> --dry-run — previews changes and validation results without writing to disk.
• axi sync <skill-name> --copy — forces physical file copying instead of junctions.
• axi sync <skill-name> --source <dir> --target <dir> — overrides default source discovery and target paths.

2. Synchronizing via MCP Server

When operating inside GUI editors or host environments like Cursor, Claude Desktop, or VS Code, agents invoke the native reactive_sync tool.

{
  "skill": "tdd-flow",
  "link": true,
  "dryRun": false
}

The tool returns a structured JSON payload detailing each target operation, whether existing folders were backed up, and any errors encountered.

3. Source discovery & known satellites

The sync engine discovers authoring sources automatically from ~/.agents/sources.json and the active working directory. It knows about all standard agent harness skill locations out of the box.

4. Automatic safety backups

Before replacing an existing physical folder with a directory junction, the synchronizer automatically moves the prior directory to a timestamped backup folder under .sync-backups/.