skillsync —— 跨工具链 AI Agent 技能同步器

技能简介

skillsync 是一款专为 AI Coding Agent 打造的技能（Skill）管理工具，核心解决多 Agent 用户技能库散落、版本不一致、迁移困难的痛点。它能自动扫描 Codex、Claude Code、WorkBuddy 等主流工具的技能目录，对每个 SKILL.md 进行四类分级，输出统一清单，并支持安全的跨平台同步。零依赖，Python 3.11+ 标准库即可运行。

核心能力

1. 多源技能扫描：自动发现主流 AI Agent 的技能目录（~/.codex/skills/、~/.claude/skills/、市场插件缓存等），统一建档。
2. 智能分类评级：将每个 SKILL.md 分为四类——A类（跨平台可直接用）、B类（缺外部依赖）、C类（需针对目标平台重写）、D类（绑定源平台不可迁移），每项决策附带原因说明。
3. 差异对比与变更检测：skillsync check 对比上游快照，发现哪些技能有更新，支持 cron 定时监控。
4. 安全同步：sync 操作全程 dry-run 先行，强制更新前自动备份旧版，排除 .venv/、.env、node_modules/、pycache/ 等敏感目录，确保不泄露密钥和大型虚拟环境。
5. 生成可提交索引：index 命令输出 INDEX.md 和 inventory.json，可直接提交到代码库或喂给其他 Agent 读取。
6. JSON 机器可读输出：scan --json 输出结构化 JSON，方便接入 CI/CD 或其他自动化流水线。
7. 零依赖纯 Python：无需 pip install，仅需 Python 3.11 以上标准库（argparse、json、pathlib、shutil、tomllib）。
8. 安装方式灵活：支持 pipx（推荐隔离安装）、pip、源码直接运行三种方式。

安装配置

方式一：pipx（推荐，隔离安装）

pipx install agent-skill-sync

方式二：pip

pip install agent-skill-sync

方式三：源码运行（无需安装）

git clone https://github.com/kina-cmd/agent-skill-sync && cd agent-skill-sync
python -m skillsync.cli --help

使用步骤

第 1 步：查看当前技能状态

skillsync status

第 2 步：扫描并生成分类清单

skillsync scan                  # 扫描所有发现源
skillsync scan --category B    # 只看缺依赖的 B 类技能
skillsync scan --json          # 机器可读 JSON 格式输出

第 3 步：生成完整索引（可提交到代码库）

skillsync index --out ./output --lang zh

这会生成 INDEX.md（人类可读）和 inventory.json（程序用）。

第 4 步：检查上游变更

skillsync check           # 对比上次快照，输出变更摘要
skillsync check --quiet  # 静默模式，仅返回一行摘要，适合 cron

第 5 步：同步技能到目标平台（始终先 dry-run）

skillsync sync --dry-run                    # 预览同步计划，不做任何修改
skillsync sync --categories A              # 只同步可直接用的 A 类
skillsync sync --categories A,B --force   # 强制更新已 drifting 的副本（自动备份旧版）

适用场景

1. 多 Agent 用户：同时使用 Claude Code、Codex、Windsurf 等多个 AI 编程工具，希望统一管理分散在各地的技能库。
2. 技能库迁移：换 Agent 平台时，快速识别哪些技能可直接迁移、哪些需要重写、哪些完全不可用。
3. 依赖维护：B 类技能缺 MCP server 或 CLI 依赖时，skillsync 会列出具体缺失项，有针对性安装。
4. 团队技能标准化：将 skillsync index 输出的 inventory.json 纳入团队文档，确保所有人技能版本一致。
5. 自动化巡检：通过 cron + check --quiet，定期汇报技能库健康状况，无需人工介入。
6. CI/CD 集成：scan --json 输出可被 CI 读取，在流水线中检查技能同步状态。

适用人群

• 多 Agent 深度用户：日常同时使用 2 个以上 AI 编程工具的开发者。
• AI 工具链管理者：负责维护团队 AI 编程规范和技能库的工程师。
• 技能开发者：编写 SKILL.md 时，用 skillsync 验证技能的跨平台可迁移性。
• DevOps/平台工程师：需要将 AI 技能同步接入 CI/CD 或自动化运维流程。

工作原理

skillsync 的核心是一个"扫描→解析→分类→对比→同步"的五段流水线：

1. 扫描（Scan）：自动发现配置的技能根目录，读取每个 SKILL.md 的 frontmatter 元数据。
2. 分类（Classify）：基于启发式规则对每个技能评级——检查是否引用了平台私有字段（如 AGENTS.md、image_gen 等），检查所有外部命令是否在 PATH 中可用（通过 shutil.which 和 [deps] 表探针）。
3. 建档（Index）：将分类结果写入 inventory.json 和 INDEX.md，记录每个技能的分类理由和缺失依赖。
4. 对比（Check）：将当前状态与上次快照对比，识别新增/删除/变更的技能。
5. 同步（Sync）：按分类过滤，只同步 A/B 类技能；强制更新前自动将旧版移入 .skillsync-backup/，确保零数据丢失。

官方链接

• GitHub：https://github.com/kina-cmd/agent-skill-sync
• PyPI：https://pypi.org/project/agent-skill-sync/