skills-manager：跨设备同步你的 AI Agent Skills

2026 年，Coding Agent 遍地开花，Skill 变成了 AI 干活的关键配置。Claude Code、Cursor、OpenCode、Gemini CLI——每个 Agent 都能通过 Skill 获得前端设计、TDD、API 设计之类的专项能力。问题是：换台电脑，这些 Skill 怎么同步过去？ 我写了 skills-manager 来解决这个问题。

为什么需要 skills-manager

Skills 的现状

vercel-labs/skills 定义了一套开放标准，可以像安装 npm 包一样给 AI Agent 装技能。它用 .skill-lock.json 记录安装状态，在 ~/.agents/skills/ 下管理技能文件。

单台机器上没问题。但换台电脑就麻烦了。

问题

比如我办公室的 Mac 上配了十几个 Agent，每个 Agent 都有自己的 Skill 路径：

~/.cursor/skills/          ← Cursor
~/.claude/skills/          ← Claude Code
~/.config/opencode/skills/ ← OpenCode
~/.gemini/skills/          ← Gemini CLI
~/.copilot/skills/         ← GitHub Copilot
~/.agents/skills/          ← Cline 和其他通用 Agent

回家换台电脑，或者同事也想用这套配置，怎么办？

1. 手动备份：记住 41 个 Agent 的路径，逐一拷贝
2. 手动软链接：每台机器重新创建几十个 symlink
3. 新增了 Skill 或 Agent？所有机器再来一遍

太繁琐了。

skills-manager 的解法

skills-manager 把这个过程变成 dotfiles 管理的体验。它是 vercel-labs/skills 的配套工具：skills 负责安装和管理技能，skills-manager 负责备份、同步和分发。

就三个命令：

快速上手

安装

Node.js >= 20，推荐安装 GitHub CLI（gh）用于认证。

# 直接运行（无需安装）
npx @tc9011/skills-manager push

# 或者全局安装
npm install -g @tc9011/skills-manager

三步同步

Step 1：在当前机器备份

skills-manager push

首次运行时，如果 ~/.agents/ 还不是 Git 仓库，它会交互式引导你：

1. 自动执行 git init
2. 提示你输入 GitHub 仓库地址（如 tc9011/my-skills）
3. 自动配置 remote 并推送

Step 2：在另一台机器恢复

skills-manager pull --repo tc9011/my-skills

Step 3：完成

pull 结束后会自动跑 link，把技能分发到本地安装了的 Agent。没拉到新内容就跳过。

整个过程大约 10 秒。

核心概念

先说几个设计决策。

.skill-lock.json 是只读的

.skill-lock.json 由 vercel-labs/skills 生成和维护，skills-manager 只从中读取 lastSelectedAgents 字段来确定你上次选了哪些 Agent。不创建、不修改、不删除。

~/.agents/ 是 Git 仓库根目录

我把整个 ~/.agents/ 作为 Git 仓库根目录：

~/.agents/                  ← Git 仓库根目录
├── .skill-lock.json        ← 由 vercel-labs/skills 管理（只读）
└── skills/
    ├── frontend-design/
    ├── systematic-debugging/
    └── api-design-principles/

这样lock 文件和 skills 目录就能保持一致，方便后面用vercel-labs/skills对 skills进行升级和维护。

软链接策略

link 命令在全局模式下创建相对路径软链接，这和 vercel-labs/skills 自身的链接方式一致：

~/.cursor/skills/my-skill        → ../../.agents/skills/my-skill
~/.claude/skills/my-skill        → ../../.agents/skills/my-skill
~/.config/opencode/skills/my-skill → ../../../.agents/skills/my-skill

而在项目模式（link --project）下，因为项目目录和 ~/.agents/ 在完全不同的目录树中，使用绝对路径软链接或直接拷贝文件。

41 个 Agent 全覆盖

内置了 41 个 Agent 的注册表，跟 vercel-labs/skills 同步。每个 Agent 记录了全局路径（globalPath）和项目路径（projectPath）：

三大命令详解

push：备份到 GitHub

skills-manager push
skills-manager push -m "新增了 Vue 开发技能"

push 做了这些事：

1. 检查 Git 仓库：如果 ~/.agents/ 不是 Git 仓库，自动运行 git init
2. 检查 Remote：如果没有 remote，交互式提示输入 GitHub 仓库地址
3. 认证：按优先级获取 GitHub Token
4. 提交并推送：git add → git commit → git push

认证的解析顺序是：

gh auth token → $GITHUB_TOKEN → $GH_TOKEN → 交互式提示运行 gh auth login

如果三种方式都没有 Token，会直接弹出选择框让你运行 gh auth login，而不是丢一个错误让你自己猜。

pull：从 GitHub 恢复

skills-manager pull --repo tc9011/my-skills   # 首次：指定仓库
skills-manager pull                            # 后续：使用已有 remote
skills-manager pull --skip-link                # 只拉取，不链接

pull 比看上去复杂，边界情况不少：

• 全新机器：自动 git clone
• 已有仓库：git fetch → 检测远程默认分支（main 或 master）→ git pull --rebase
• Detached HEAD：checkout -B branch origin/branch 修复
• 缺失本地分支：fetch 后从远程 ref 创建
• 无变化时跳过 link：比较 pull 前后的 HEAD commit

这些都是实际用的时候碰到的。比如第二台电脑上首次 pull，git checkout master 直接报 pathspec 'master' did not match any file(s) known to git，因为 clone 之后只有远程 tracking ref，没有本地分支。开发的时候不容易想到，但用户一定会碰到。

link：分发技能

skills-manager link
skills-manager link --agents cursor opencode claude-code

流程：

1. 读 .skill-lock.json，拿到 lastSelectedAgents 列表
2. 扫描本机哪些 Agent 目录存在
3. 弹出多选框，本地存在的自动预选
4. 为选中的 Agent 创建相对路径 symlink
5. 保存选择到 ~/.config/skills-manager/config.json，下次恢复

为什么只预选本地存在的 Agent？因为你没装 Cursor 的话，强行创建 ~/.cursor/skills/ 没什么意义。完成后会看到报告：

✓ Linked: cursor, opencode, claude-code, gemini-cli
⚠ Skipped (not installed locally): junie, kilo, augment

项目级别的 Skills 管理

全局链接适合个人用。团队协作的话，我更倾向把 Skill 放到项目目录里，git clone 下来就能直接用。

使用方式

skills-manager link --project
# 或者简写
skills-manager link -p

你会经历三个交互环节：

1. 选择 Agent

从你的 Agent 列表中选择这个项目需要支持哪些 Agent。比如这个项目只用 Cursor 和 Claude Code。

2. 选择 Skills

从你的技能库中挑选需要的技能。默认全选，你可以取消不需要的。

3. 选择分发方式

项目结构

完成后，你的项目目录会是这样的：

./my-project/
├── .agents/skills/           ← 通用 Agent 共享（Cline、Copilot 等 10 个 Agent）
│   ├── frontend-design/
│   └── systematic-debugging/
├── .claude/skills/           ← Claude Code 专用
│   ├── frontend-design/
│   └── systematic-debugging/
├── .cursor/skills/           ← Cursor 专用
│   ├── frontend-design/
│   └── systematic-debugging/
└── .trae/skills/             ← Trae 专用
    ├── frontend-design/
    └── systematic-debugging/

去重

10 个 Universal Agent（Cline、Copilot、Amp、OpenCode 等）在项目模式下共享 .agents/skills/ 路径。选了 5 个 Universal Agent，文件也只拷贝一次。trae 和 trae-cn 同理，共享 .trae/skills/。

团队协作场景

举个实际场景：

1. 在自己机器上配置好全局 Skills
2. 在项目中运行 skills-manager link -p，选择 Copy 模式
3. 把 .cursor/skills/ 等目录提交到 Git
4. 团队成员 git pull 后，所有人的 Cursor、Claude Code 都自动获得这些技能

团队成员 git pull 下来就能用，不需要额外配置。

认证机制

push 和 pull 需要 GitHub 认证，link 不需要。

认证解析顺序：

没有 Token 的时候不会直接报错，而是弹出选择框引导你授权。新手用户看到 “Error: No token found” 和看到一个交互提示，体验差很多。

总结

vercel-labs/skills 管理技能本身，skills-manager 管理技能的同步。Push 备份到 GitHub，Pull 恢复到新机器，Link 把技能分发到各个 Agent，加个 --project 就能做项目级隔离。

# 试试看
npx @tc9011/skills-manager --help

项目在 GitHub 上开源。

欢迎关注我的其它发布渠道

WeChat