AI Skills Sync 🌐

An elegant, lightweight, out-of-the-box global skills synchronization gateway for multi-agent frameworks.

English | 中文

🇬🇧 English

In scenarios involving hybrid development with multiple AI agents (OpenCode, Qoder, Cursor, Claude Code, Antigravity, etc.), each framework requires loading its own skills (Skills/Tools/Commands). Instead of manually maintaining these repeatedly under each framework, you can use ai-skills-sync to configure once, and sync everywhere!

Our core philosophy: Zero mental burden, one-click collection of existing skills from all frameworks, automatic aggregation and distribution, seamlessly bridging any AI Agent framework.

💡 Core Principles (Important! Please read first)

ai-skills-sync adopts a "Two-way Synchronization" architecture, rather than a simple one-way push. When executing aisync sync, the tool performs the following five phases:

Phase 1: 📥 Collect       ← Reverse-collects installed skills from native directories of all frameworks
Phase 2: 📂 Discover      ← Scans searchPaths configured by the user (like ~/.global-skills, ./skills)
Phase 3: 🔗 Merge         ← Merges and deduplicates skills from both sources
Phase 3.5: 🏠 Centralize  ← Aggregates native skills from all frameworks into the ~/.global-skills/ central repo
Phase 4: 📤 Distribute    ← Distributes the complete skill set back to all enabled framework directories

What does this mean?

You don't need to manually manage anything! Suppose you installed a code-review plugin in Claude Code and an auto-debug skill in Qoder:

1. Run aisync sync
2. The tool automatically goes to Claude Code's ~/.claude/plugins/ and Qoder's ~/.qoder/skills/ to collect these skills.
3. They are centrally aggregated into the ~/.global-skills/ repository (making it easy for you to see them all at a glance).
4. Then they are automatically distributed to OpenCode, Cursor, Antigravity, and all other frameworks.

Run once, synchronize everywhere!

Anti-Loop Mechanism

You might wonder: "If it writes skills into Qoder, won't it collect them back the next time it runs?" The answer is NO:

• Symlink/Junction Mode: The tool creates symbolic links, and during collection, it recognizes and skips them automatically.
• Copy Mode (Windows Fallback): The tool injects a hidden marker <!-- aisync:managed --> into generated SKILL.md files; collection skips these.
• These two mechanisms ensure that infinitely repeated runs will not cause dead loops or data inflation.

💫 Features

• 🔄 Two-way Synchronization: It not only pushes skills out but also automatically reverse-collects installed native skills from various frameworks.
• 🏠 Central Repository: All collected skills are aggregated into ~/.global-skills/, letting you view everything in one directory.
• 🌍 Global & Local Discovery: Supports uniform reading from a global directory as well as automatic scanning of the current project's root.
• 🔗 Native Symlink Compatibility: Some frameworks strictly require skills to be stored within their own folders. This tool natively generates zero-footprint symbolic links (Junction/Symlink) across different frameworks. This breaks path restrictions without moving files. This is now the default aggressive behavior across all platforms.
• 📝 Automatic Metadata Parsing & Smart Patching: Just place a SKILL.md inside a skill folder. Even if it's an external plugin (like an official Claude plugin with only a README), the sync gateway intelligently falls back to deep copying and automatically injects a compliant SKILL.md entity patch upon landing.
• 💥 Painless Conflict Resolution: In the case of identically named skills, it uses automated strategies like "Newest Version Override" or "Keep Original", while never overwriting framework-native data.
• 🔥 Hot-Reloading: Run aisync watch as a resident daemon to instantly synchronize any changes across all frameworks.
• 📦 One-Click Update: aisync update bulk-pulls all Git-tracked community skills to their latest versions.

🤖 Supported Agent Frameworks

| Framework | Adapter | Global Skill Path | Project Level Path | Collection Source | |------|--------|-------------|-----------|----------| | OpenCode | opencode | ~/.config/opencode/skills/{name}/SKILL.md | .opencode/skills/{name}/SKILL.md | 📥 Distribute Only | | Qoder | qoder | ~/.qoder/skills/{name}/SKILL.md | .qoder/skills/{name}/SKILL.md | 📥 Distribute Only | | Cursor IDE | cursor | — (Project-level only) | .cursor/rules/*.mdc | 📥 Distribute Only | | Claude Code | claudecode | ~/.claude/commands/*.md | .claude/commands/*.md | ✅ Two-way Collection (Marketplace) | | Antigravity | antigravity | ~/.gemini/antigravity/skills/{name}/SKILL.md | .agent/skills/{name}/SKILL.md | 📥 Distribute Only |

📦 Installation

# Global installation (Recommended)
npm install -g @pzx/ai-skills-sync

# Or install locally in a project
npm install @pzx/ai-skills-sync --save-dev

# Or run directly via npx (No installation required)
npx @pzx/ai-skills-sync sync

🚀 Quick Start (Idiot-proof)

Scenario 1: One-click sync across all frameworks (Core Scenario)

Just run in your terminal:

aisync sync

The tool will automatically:

1. Collect installed skills from the native directories of every framework.
2. Scan ~/.global-skills and ./skills under the current project.
3. Centralize all skills into ~/.global-skills/.
4. Distribute the complete skill set to all smart agent frameworks on the computer.

Scenario 2: Project-Specific Sync

Run in the project root:

aisync init

This generates a .aiskillsrc.json config:

{
  "searchPaths": [
    "./skills",
    "./agent-skills",
    "~/.global-skills"
  ],
  "frameworks": {
    "opencode": true,
    "qoder": true,
    "cursor": true,
    "claudecode": true,
    "antigravity": true
  }
}

Now running aisync sync collects framework skills and grabs the project's private skills.

Scenario 3: I want skills to sync automatically

aisync watch

Starts a daemon. If any framework modifies or adds a skill file, all frameworks synchronize instantly.

Scenario 4: Bulk update community skills

aisync update

Automatically identifies and skips your manually written private skills, bulk-pulling Github-tracked community skills to their latest versions in one click.

🇨🇳 中文 (Chinese)

AI Skills Sync 是一个高雅、轻量、开箱即用的"多智能体框架全局技能同步网关"。

在多智能体（OpenCode, Qoder, Cursor, Claude Code, Antigravity 等）混合开发的场景下，每个框架都需要加载各自的技能（Skills/Tools）。与其在每个框架下重复手动维护，不如使用 ai-skills-sync 进行一次配置，全网同步！

我们的核心理念是：零心智负担，一键收集所有框架已有技能，自动汇总分发，无缝桥接任何 AI Agent 框架。

💡 核心原理（重要！请先阅读）

ai-skills-sync 采用**"双向同步"**架构，而非简单的单向推送。执行 aisync sync 时，工具会执行以下 五个阶段：

Phase 1: 📥 收集 (Collect)     ← 从所有框架的原生目录中反向收集已安装的技能
Phase 2: 📂 扫描 (Discover)    ← 扫描用户配置的 searchPaths（如 ~/.global-skills, ./skills）
Phase 3: 🔗 合并 (Merge)       ← 将两个来源的技能合并去重
Phase 3.5: 🏠 汇集 (Centralize) ← 将所有框架的原生技能汇集到 ~/.global-skills/ 中央仓库
Phase 4: 📤 分发 (Distribute)  ← 将完整技能集分发到每个启用的框架目录中

这意味着什么？

你不需要手动管理任何东西！ 假设你在 Claude Code 里安装了 code-review 插件，在 Qoder 里安装了 auto-debug 技能：

1. 运行 aisync sync
2. 工具自动去 Claude Code 的 ~/.claude/plugins/ 和 Qoder 的 ~/.qoder/skills/ 里收集这些技能
3. 它们被统一汇集到 ~/.global-skills/ 中央仓库（方便你一览）
4. 然后自动分发给 OpenCode、Cursor、Antigravity 等所有其他框架

一次运行，全网同步！

防循环机制

你可能会想："它把技能写入 Qoder 后，下次再运行不会把写入的又收集回来吗？"答案是不会：

• Symlink/Junction 模式：工具创建的是符号链接，收集时会自动识别并跳过
• 拷贝模式（Windows 兜底）：工具在生成的每个 SKILL.md 中注入了一个隐藏标记 <!-- aisync:managed -->，收集时检测到此标记会自动跳过
• 这两种机制共同保证了无限次重复运行也不会产生死循环或数据膨胀

💫 特性

• 🔄 双向同步：不仅能向外推送技能，更能自动从各个框架中反向收集已安装的原生技能。
• 🏠 中央仓库：所有收集的技能自动汇集到 ~/.global-skills/，一个目录看到全部。
• 🌍 全局 & 局部双重发现：支持从全局目录统一读取，也支持自动扫描当前项目根目录。
• 🔗 原生 Symlink（符号链接）兼容：某些框架强制要求技能必须存放在它自己的框架文件夹内。本工具原生支持在不同框架中生成零占用的符号链接（Junction/Symlink），在不转移文件的前提下完美突破路径限制。现在这是所有平台的默认激进行为。
• 📝 无脑元数据解析与智能修补：只需在技能文件夹内存放 SKILL.md 即可。甚至如果是来自外部的特殊插件（如 Claude 官方仅含 README 的插件），同步网关也会智能降级触发热拷贝，并在落地瞬间自动植入合规的 SKILL.md 实体补丁。
• 💥 极简冲突处理：如果发现同名技能，内置「新版本覆盖」或「原位保留」的自动决策策略，且绝不覆盖框架原生数据。
• 🔥 热重载：aisync watch 常驻监听，任何修改瞬间同步。
• 📦 一键更新：aisync update 批量拉取所有 Git 追踪的社区技能到最新版本。

🤖 支持的智能体框架

| 框架 | 适配器 | 全局技能位置 | 项目级位置 | 收集来源 | |------|--------|-------------|-----------|----------| | OpenCode | opencode | ~/.config/opencode/skills/{name}/SKILL.md | .opencode/skills/{name}/SKILL.md | 📥 仅分发 | | Qoder | qoder | ~/.qoder/skills/{name}/SKILL.md | .qoder/skills/{name}/SKILL.md | 📥 仅分发 | | Cursor IDE | cursor | —（仅项目级） | .cursor/rules/*.mdc | 📥 仅分发 | | Claude Code | claudecode | ~/.claude/commands/*.md | .claude/commands/*.md | ✅ 双向反抽 (Marketplace) | | Antigravity | antigravity | ~/.gemini/antigravity/skills/{name}/SKILL.md | .agent/skills/{name}/SKILL.md | 📥 仅分发 |

📦 安装

# 全局安装（推荐）
npm install -g @pzx/ai-skills-sync

# 或在项目中局部安装
npm install @pzx/ai-skills-sync --save-dev

# 或通过 npx 直接运行（无需安装）
npx @pzx/ai-skills-sync sync

🚀 极简用法（傻瓜式）

场景一：一键同步所有框架的技能（最核心场景）

直接在终端运行：

aisync sync

场景二：针对特定项目

在项目根目录运行：

aisync init

这会生成一个 .aiskillsrc.json 配置文件。

场景三：我想让技能自动同步

aisync watch

开启守护进程，任何一个框架中新增或修改了技能文件，所有框架瞬间同步。

场景四：批量更新社区技能

aisync update

自动识别并跳过你自己手写的私有技能，一键把所有 Git 追踪的社区技能拉到最新版本。

📄 License

MIT