Agnostic AI Agent Sync
cliffordp/agnostic-ai-agent-sync
Gerencia skills unificadas entre agentes de IA com symlinks imutáveis
Ver no GitHubSincroniza um repositório único de skills e instruções entre múltiplos agentes de IA (Claude, Cursor, Codex, etc.) usando symlinks imutáveis no nível do SO. Sem dependências externas, protege arquivos contra exclusão acidental por atualizações de IDE e permite sincronização multi-dispositivo via pasta na nuvem.
Instalação
npx convez-ai cliffordp/agnostic-ai-agent-sync1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter instruções customizadas sincronizadas entre Cursor, Claude e Codex
- Proteger symlinks contra exclusão por atualizações de software
- Sincronizar skills entre múltiplos dispositivos via Dropbox/iCloud/OneDrive
Veredito

Solução robusta para fragmentação de configurações em ecossistema multi-agente. Implementação sólida com proteção OS-level, embora requeira familiaridade com symlinks e scripts shell/PowerShell.
README
A tradução para o português deste README ainda está na fila.
Agnostic AI Agent Sync
Maintain a single unified folder of AI agent skills and instructions, making it seamless to switch between Antigravity, Claude, Codex, Cursor, Qoder, Windsurf, and others.
Dependency-free, with OS-level immutable symlinks — protected from being accidentally deleted or overwritten by aggressive IDE updates.
The Problem
Using multiple AI coding tools means your custom instructions end up scattered across ~/.cursorrules, ~/.claude/skills/, ~/.codex/config/, etc. Updating one meant manually copy-pasting to all the others — and inevitably forgetting one.
Worse, existing sync approaches create regular symlinks that are easily overwritten by software updates, git checkout resets, or environment re-initialization. One bad update and your entire symlinked skill library vanishes.
💡 Modern Alternative: For users who prefer a protocol-level approach over file-system symlinks, check out AutoVault. It provides a standardized way to manage and "serve" skills to different agents using the Model Context Protocol (MCP), though it requires Node.js and does not offer the OS-level immutable locking found in this project.
The Solution
Agnostic AI Agent Sync creates symlinks from each AI coding tool's config location to a single "Hub" folder you control, then locks them at the OS level so nothing can silently delete them (like a new git clone command for that slick new Skill).
Why This Is Different
| Feature | Generic symlinks / npm tools | Agnostic AI Agent Sync |
|---|---|---|
| Survives app updates | ❌ Silently deleted | ✅ OS-level immutable lock |
Maps .cursorrules ↔ CLAUDE.md | ❌ Manual | ✅ Automatic |
| Dry-run before changes | ❌ YOLO | ✅ Full analysis + confirmation |
| Clean skill repos | ❌ Cloned repos pollute each other’s git state | ✅ Each repo is an independent sibling |
| Dependencies | Node.js / npm | Zero — native bash & PowerShell |
| Undo / unlock | Manual googling | ✅ Built-in unsync script removes locks and unlinks tools |
| Multi-device sync | ❌ Not handled | ✅ Native via cloud Hub folder (Dropbox/iCloud/OneDrive) |
How It Works
- Analyze — Scans your system for installed AI agents, classifies what exists at each path (real folder, existing symlink, nothing), and prints a clear plan.
- Confirm — Asks for your explicit
yapproval. If you say no, zero files are touched. - Implement — Backs up real folders, creates symlinks, and locks them with OS-level immutability (
chflagson macOS,chattron Linux,icaclson Windows).
Example Screenshots
Ran on Cliff's macOS after he already manually created symlinks (what this script would automatically do for you), indicating that it gracefully works even if you've partially implemented what this script does.
Setup Guide
Option A: One-liner (Mac / Linux)
Copy and paste this into your terminal — it downloads and runs the script directly:
curl -fsSL https://raw.githubusercontent.com/cliffordp/agnostic-ai-agent-sync/main/sync.sh -o sync.sh && chmod +x sync.sh && ./sync.sh
Option B: Clone the repo
Open your terminal (Mac/Linux) or PowerShell (Windows). Navigate to wherever you keep projects (e.g. cd ~/Documents), then run:
git clone https://github.com/cliffordp/agnostic-ai-agent-sync.git
cd agnostic-ai-agent-sync
Don't have
git? Click the green Code button on this page → Download ZIP → unzip it somewhere you'll remember → open your terminal inside that folder.
Step 2: Run the sync
The script will walk you through everything — including creating your Hub folder if you don't have one yet.
Mac / Linux
chmod +x sync.sh
./sync.sh
Windows
powershell -ExecutionPolicy Bypass -File .\sync.ps1
The script will:
- Ask where your Hub is (or help you create one)
- Auto-detect and offer to merge any existing skill files scattered across your local tools
- Scan your system for installed AI agents
- Show you exactly what it plans to do
- Wait for you to type
ybefore touching anything - Ask if you want to automatically configure global agent defaults (e.g., setting
AGENTS.mdas the default context for Gemini CLI and Aider)
Re-running is safe. The script remembers your Hub path (saved to
~/.agnostic-ai-agent-sync). Subsequent runs skip the wizard and go straight to analysis.
Step 3: Check status (anytime)
Run this from wherever you downloaded or cloned the script:
./sync.sh status
Shows a dashboard of all your synced agents — whether each link is healthy, locked, broken, or not yet synced.
Working with Skill Porter
Agnostic AI Agent Sync pairs perfectly with translation tools like Skill Porter. While they solve fundamentally different problems, they are highly complementary:
- Skill Porter solves the metadata format: It translates proprietary YAML files into JSON so a single skill repository can be universally parsed by Claude, Gemini, and others.
- Agnostic Agent Sync solves the storage pipeline: It ensures that once your universal skill exists, you only ever need to store one physical copy of it in your cloud Hub.
If you download a raw Claude-only skill into your Hub, you can run skill-porter convert to generate the missing Gemini metadata files directly inside that Dropbox folder. Then, because Agnostic Agent Sync acts as an OS-level bridge mapping both ~/.claude/ and ~/.agents/ back to your Hub, all your different AI tools instantly realize the skill is universally compatible without you having to manually duplicate or synchronize the folder across your IDEs!
What This Script Does vs. What It Doesn't Do
To prevent confusion, here is exactly what Agnostic Agent Sync handles:
✅ IT DOES: Act as a local filesystem bridge. It seamlessly maps the native configuration and skills/ folders belonging to all your local AI programs (Claude, Gemini CLI, Cursor, etc.) into a single unified directory (your Hub).
✅ IT DOES: Protect your custom skills, .cursorrules, and instructions from being overwritten or silently deleted when your IDEs run aggressive background software updates.
✅ IT DOES: Enable zero-effort multi-laptop synchronization if you choose to set your Hub location to a cloud storage folder like Dropbox or iCloud.
❌ IT DOES NOT: Act as a package manager. It does not download, parse, extract, or install third-party plugins from remote internet marketplaces (e.g., using /plugin install in Claude bypasses this bridge entirely because it hides files in proprietary sub-directories).
❌ IT DOES NOT: Untangle third-party GitHub megarepos. If you manually download a massive skills bundle from another author, you must ensure the SKILL.md folders are placed directly in your Hub directory, not buried deep inside random subfolders.
❌ IT DOES NOT: Translate file formats. If an AI tool rigidly requires a proprietary json manifest instead of a generic Markdown file, you still need to generate it (which is why we recommend using Skill Porter alongside this sync script).
Supported Agents
Because the script dynamically fetches tool paths from this repository linearly, the canonical list of supported AI tools is always up to date inside the agents.map file.
Currently supported tools out-of-the-box include:
- Claude Desktop
- Cursor (including
.cursorrules) - Windsurf
- Codex
- Qoder
- Antigravity
If an agent isn't installed on your machine, it's automatically skipped.
Not Currently Supported
These tools store their config in ways that aren't compatible with directory-level symlinking:
| Tool | Why |
|---|---|
| Cline | VS Code extension — global config lives inside VS Code's settings.json, not a standalone directory |
| Roo Code | VS Code extension — same architecture as Cline; per-project rules only (.roo/) |
| Aider | Config is a single YAML file (~/.aider.conf.yml), not a directory of skills |
| Continue.dev | Config is ~/.continue/config.json — a JSON blob mixing API keys with settings |
| GitHub Copilot | Config embedded in VS Code/JetBrains settings; per-repo via .github/copilot-instructions.md |
Unlocking / Undoing
Need to modify or remove the symlinks? Run the unlock script first:
Mac / Linux
chmod +x unsync.sh
./unsync.sh
Windows
powershell -ExecutionPolicy Bypass -File .\unsync.ps1
This script safely reverses the sync process without losing your new skills:
- Removes the immutable OS locks from all symlinks
- Deletes the symlinks to disconnect the local tools from your Hub
- Everything in your Hub is left untouched and safe
- Your
.backup_*folders are left untouched
Your AI coding tools will now generate clean, empty folders. If you want to keep the skills you installed while synced, simply copy them from your Hub back into the tool's local folder.
To re-link everything to the Hub later, just run sync.sh / sync.ps1 again.
FAQ
Q: How will I know if it's working? If you're using Claude Code, for example...
- go to your Terminal > type
claudeto get into Claude Code > then typelist all available skillsand it should list them for you. - Then,
exitClaude Code, run this script (see instructions, above), get back into Claude Code, and typelist all available skillsagain... and the same skills should be there. - Then, go to
~/.claude/skillsand see if that's a symlink to your Hub location and that your skills are found there. (NOTE: this script only manages global/user-level skills, not project-level ones.)
Q: Will this delete my existing skills?
No. Any existing folders or files are renamed to .backup_TIMESTAMP before a symlink is created. You can always find them right next to the original path. The script also offers to merge your scattered skills into the Hub before syncing. After a successful sync, you'll be asked if you want to clean up old backups.
Q: How do I remove old backup files?
The script offers to clean them up automatically after each sync. If you skipped that prompt, run ./sync.sh cleanup (or .\sync.ps1 cleanup on Windows) anytime. It lists every backup with its size and asks before deleting anything.
Q: Do I have to answer the Hub wizard every time?
No. After the first run, your Hub path is saved to ~/.agnostic-ai-agent-sync. Future runs remember it automatically and skip straight to the analysis.
Q: What if I install a new AI coding tool later?
Just re-run ./sync.sh. It auto-detects newly installed agents and offers to wire them up. Already-synced agents are left untouched.
Q: What if a brand new AI coding tool hits the market? Will I need to download a new script?
No! The sync scripts are dynamic. Upon launch, they silently parse the agents.map file hosted directly on this GitHub repository. When we add support for a new tool to the map, your local script will automatically support it the very next time you run it.
Q: How do I install new skills after syncing?
Navigate to your Hub's skills/ folder (or any synced path like ~/.claude/skills/ — they all point to the same place) and install normally. For example:
cd ~/.claude/skills/
git clone https://github.com/cliffordp/claude-skills
The new skill instantly appears in every synced tool. The immutable lock protects the symlink itself from being deleted — but writing inside the directory works normally.
Q: What if a symlink already points to the right place? The script detects this, skips re-creation, and just verifies the lock is applied. It's safe to run repeatedly.
Q: What if a symlink points somewhere unexpected?
The script flags it with a [WARN] in the analysis phase. You'll see exactly where it currently points and where it should point. If you confirm, it replaces it. If you abort, nothing changes.
Q: Do I need admin/root access?
On macOS, no. On Linux, chattr requires sudo (it will prompt). On Windows, Directory Junctions don't require admin — symlinks for .cursorrules may require Developer Mode enabled in Windows Settings.
Q: Can I sync skills across multiple computers?
Yes — that's a big reason this tool exists. Put your Hub folder in Dropbox, iCloud Drive, OneDrive, or any cloud-synced directory. Run ./sync.sh on each machine. They'll all point to the same shared Hub.
Q: Can I use iCloud Drive / Dropbox / OneDrive as my Hub? Absolutely. The script's guided setup even offers these as default choices. Cloud storage is the recommended location for your Hub.
Q: What actually goes in the Hub?
Two folders: skills/ (your reusable SKILL.md files, prompt libraries, etc.) and config/ (your CLAUDE.md or other global agent instructions). The script creates both automatically.
Q: What about per-project rules like .cursorrules in a repo?
This tool only manages global (user-level) config. Per-project files inside your repositories (.cursorrules, .claude/, .windsurf/rules/) are untouched and work as normal alongside these global symlinks.
Q: Can I have different skills for different AI coding tools? Not with this tool — the whole point is a single shared set. If you need tool-specific skills, manage those manually in per-project directories instead.
Q: Does this configure my agents for me?
The script offers an optional step at the end to set AGENTS.md as the default context file for tools like the Gemini CLI and Aider. This is strictly opt-in and checks for existing configurations to prevent accidental overwrites.
Q: My AI coding tool just updated and something seems broken. What do I do?
Run ./sync.sh status to check if the symlinks are still intact. If the lock held (which it should), you'll see all green. If something got overwritten, re-run ./sync.sh to repair it.
Q: How do I add support for a new AI agent?
Open the agents.map file in this repository and add a new line following the pattern. PRs welcome! Because the scripts fetch this file dynamically, your pull request will instantly distribute support for the new tool to all users without them needing to re-download the script.
Q: Does running the sync script require an internet connection?
No. The script silently attempts a 2-second fetch of agents.map from GitHub to grab the latest supported tool paths, but if you are offline, it instantly falls back to a hardcoded offline list. Zero telemetry, and zero mandatory dependencies.
Q: Can I install this via Homebrew?
Not currently. Because this tool relies on local script execution to detect your home directory (~/.claude, etc.) and manages state via a saved ~/.agnostic-ai-agent-sync config, dropping it into the /usr/local/bin / /opt/homebrew $PATH as a global executable isn't supported yet. The recommended approach is to keep the script in a dedicated directory (like ~/Documents/scripts/ or ~/GitHub/agent-sync/).
Q: Why is a Hub better than cloning skill repos directly into ~/.claude/skills/?
Without a Hub, cloning multiple skill repos into a single agent directory (like ~/.claude/skills/) mixes them together on disk. Running git status inside one repo shows the others as untracked files, requiring constant .gitignore maintenance. With a Hub, each skill repo is cloned as an independent sibling directory — clean git status, no .gitignore games, and every repo can be updated or removed without touching the others. See Cliff's claude-skills repo for a curated collection that follows this pattern.
License
MIT License — use it, star it, fork it, embed it in your workflows.
Disclaimer
This tool modifies symlinks and file system permissions on your machine. While it is designed with safety guardrails (dry-run analysis, confirmation prompts, automatic backups), you use it at your own risk. Always review the analysis output before confirming. The authors are not responsible for any data loss or misconfiguration resulting from use of this tool.
Disclosure
This codebase was generated with the assistance of AI coding tools. You should review the code prior to installing. Cliff tested the tool on macOS but not on Linux or Windows.