One tool to rule them all: Sync, Centralize, and Share AI Agent configurations and skills.
agent-sync solves the fragmentation of the AI agent ecosystem by providing a unified workflow for your CLI tools.
🔗 Protocol Support — agent-sync supports DotAgents Protocol (
~/.agents/skills/hub) for portable skills. Optional GitAgent Protocol support can be enabled in config.
- Unified Skills Hub: Stop duplicating skills across different agents. Centralize everything in
~/.agents/skills/and let every agent (Claude, Gemini, Opencode, etc.) use them. - Private Backup & Sync: Keep your agent configurations and custom skills safely backed up in a private GitHub repository. Seamlessly sync your entire environment between multiple machines.
- Share with the World: Effortlessly publish your best custom skills to a public repository, allowing the community to benefit from your specialized agent tools.
- Extension Support: Automatically detects and backs up skills from agent extensions (e.g., Opencode Superpowers, Cursor extensions) with their symlink structures preserved.
| Agent | Config Files | Skills Path | Method |
|---|---|---|---|
| claude-code | settings.json |
~/.claude/commands/ |
Copy |
| gemini-cli | settings.json |
~/.gemini/tools/ |
Copy |
| opencode | opencode.json |
~/.config/opencode/skills/ |
Config |
| pi.dev | settings.json, models.json |
~/.pi/agent/skills/ |
Native |
| qwen-code | settings.json |
~/.qwen/skills/ |
Copy |
| Agent | Config Files | Skills Path | Method |
|---|---|---|---|
| cline | state.json |
~/.cline/skills/ |
Copy |
| cursor | settings.json |
~/.cursor/skills/ |
Native |
| roocode | custom_modes.yaml |
~/.roo/skills/, ~/.agents/skills/ |
Native |
| windsurf | config.json |
~/.codeium/windsurf/skills/ |
Copy |
# Recommended (isolated install)
pipx install agent-sync
# Or via pip
pip install agent-syncagent-sync init # Create repo + wizard
agent-sync push # Backup to GitHubagent-sync link https://github.com/user/repo.git
agent-sync pull # Restore configsagent-sync setup # Change agents/options
agent-sync config show # View current configUse these standard names for consistency:
| Purpose | Repository Name | Example |
|---|---|---|
| CLI Tool | agent-sync |
renatocaliari/agent-sync |
| Private Configs | agent-sync-configs |
renatocaliari/agent-sync-configs |
| Public Skills | agent-sync-public |
renatocaliari/agent-sync-public |
Why these names?
- ✅ Consistent - All start with
agent-sync- - ✅ Clear - "private" and "public" make purpose obvious
- ✅ Discoverable - Easy to find via GitHub search
- ✅ Standard - Follows common naming patterns
Example Setup:
# Initialize private configs (first machine)
agent-sync init --name agent-sync-configs
# Link on additional machines
agent-sync link https://github.com/YOUR_USERNAME/agent-sync-configs.git
# Publish your skills (share with community)
# Note: agent-sync publish is for CREATING a public repo, not installing from one.
# To install skills from a public repo, use npx skills:
#
# npx skills add renatocaliari/agent-sync-public
# npx skills add https://github.com/user/skill-repo
agent-sync publish add https://github.com/YOUR_USERNAME/agent-sync-public.gitagent-sync uses a categorized help structure. Run agent-sync --help to see all options.
init- Initialize a new sync repository (first machine)link <url>- Connect to an existing repository (other machines)push- Backup local changes to GitHub[-m, --skills-only, --configs-only]pull- Download and apply changes from GitHub[--force, --skills-only, --configs-only]status- Check sync state per agent
agents- List supported agents and their sync methodenable <agent>/disable <agent>- Toggle sync for a specific agentsetup- Interactive wizard to reconfigure agents and options
-
skills list- List all centralized skills in~/.agents/skills/ -
skills centralize- Auto-import scattered skills from agents to hub--yes- Non-interactive: skip all orphan skills--import-all- Import all orphans without TUI (old behavior)--dry-run- Preview changes without modifying anything--copy- Copy instead of move--distribute- After centralizing, copy all skills to all agent directories
🛡️ Safety features (v0.15+): Interactive TUI selects which orphans to import (default: none). Content comparison via hash detects divergent copies. Post-selection prompt: Keep or Remove unselected. 🔗 DotAgents Protocol: Structure automatically follows
.agents/convention (https://dotagentsprotocol.com/) -
skills diff- Show differences between local and remote skills -
skills reconcile- Resolve divergences between local and remote -
skills delete- Delete skills from hub and all agent directories (interactive)
publish run- Run interactive publish flow (select skills/agents to share)publish add <url>- Add a publish repository (where YOU will publish your skills)publish list- List configured publish repositoriespublish remove <url>- Remove a publish repository
💡 Install skills from public repos: Use
npx skills add <source>from vercel-labs/skills. Example:npx skills add renatocaliari/agent-sync-public
repos list- Show ALL repositories (sync + publish) with status
config show- View current configurationconfig edit- Open configuration file in editorconfig repo- View, set, or remove repository URLconfig reset- Reset config to defaults (keeps repo linked)generate-config- Generate default config file (useful as starting point)update- Check for and install CLI updatesversion- Show version informationsecrets- Manage secrets sync (disabled by default)
agent-sync supports agent extensions that create subdirectories with skills (e.g., Opencode Superpowers, Cursor extensions).
Example structure:
~/.config/opencode/
├── superpowers/
│ └── skills/ # Extension skills
└── skills/
└── superpowers → symlink → ../superpowers/skills/
Supported:
- Extension subdirectories (e.g.,
~/.config/opencode/superpowers/skills/) - Internal symlinks (preserved)
- External symlinks (removed)
- Multiple extensions simultaneously
- Skills with special characters (
__,-)
How it works:
push- Detects extensions, backs up skills + symlinks, creates.agent-sync-manifest.jsonpull- Reads manifest, restores extension skills and symlinks to original locations
See full documentation: Extension Support
I welcome contributions to keep this project growing and stable. You don't need to be a Python expert to help.
- Add New Agents: Support for new AI CLIs is data-driven. Just add a few lines to src/agent_sync/agent_registry.yaml.
- Bug Fixes & UX: Found a clunky TUI flow or a bug? Open a PR!
- Improve Docs: Help me make these guides clearer.
If you are an AI model (LLM) contributing to this project, please read AGENTS.md for versioning and architectural mandates.
Inspired by opencode-synced, expanded to support multiple agent CLIs and other powerful features.
agent-sync supports two protocols for AI agent configuration.
The DotAgents Protocol provides a vendor-neutral skills hub — all your skills in one place, usable across agents.
| Your Benefit | How It Works |
|---|---|
| One skills folder | All skills live in ~/.agents/skills/ |
| Cross-agent sharing | Skills work with Claude, Gemini, Opencode, etc. |
| Version controlled | Backed up in your private GitHub repo |
Quick start:
# Move scattered skills to hub
agent-sync skills centralize
# Your skills are now in ~/.agents/skills/
# Push to backup
agent-sync pushLearn more at dotagentsprotocol.com
The GitAgent Protocol provides comprehensive agent definitions with identity, constraints, and compliance mapping.
Enable in your config:
protocols:
gitagent:
enabled: true
patterns:
- "agent.yaml"
- "SOUL.md"
- "RULES.md"
- "DUTIES.md"Your agent definitions are backed up alongside your other configs.
Learn more at gitagent.sh
MIT License - see LICENSE for details.