痛点：Skills 缺乏「项目级锁定」机制

使用 Cursor 的朋友想必都深有体会——Skills 可以为每个项目挂载一系列“技能”，让 AI 按照既定规则高效运作，确实便捷。然而，官方提供的 skills add 命令，并不会将配置写入项目文件。这意味着什么？一旦换一台设备、换一位开发者，你就得重新手动添加一遍。团队中谁安装了哪些技能、谁没装，根本无从查证。

问题的根源在哪里？Skills 本身是按照“当前用户 + 当前目录”进行安装的，技能文件会存放到 .cursor/skills/ 这类目录下，却永远不会在项目中生成类似 package.json 的清单文件。结果导致：

• 你执行了 skills add vercel-labs/agent-skills，同事克隆项目后没有这段配置，安装的技能与你完全不同；
• 换电脑或重装系统时，只能靠记忆或翻文档再手动 add 一遍；
• 多人协作时，团队究竟使用了哪几个 skill、分配给哪些 agent，缺少唯一的事实依据。

因此，这里实际需要解决两个关键问题：第一，需要一份声明文件，明确写明需要安装哪些内容；第二，需要一个命令，能依据这份声明一次性全部安装齐备。skills-manifest 正是为此而生的工具。

skills-manifest 是什么

简单来说，skills-manifest 是一个针对 skills 的项目级清单管理器。你只需维护一个 skills-manifest.json 文件，在其中清楚写明“从哪个仓库安装哪些 skill、分配给哪些 agent”。然后在项目根目录运行一次 skills-manifest install，它就会按照清单自动调用 skills add，并将结果同步到 Cursor、Claude Code 等工具的相应目录中。

这样一来，所有人执行 pnpm i 之后，再跑一遍 install，大家使用的技能就完全一致了，再也不需要依靠口头沟通或手动复制配置。

从零开始：init 初始化

在项目根目录执行下方命令即可开始使用：

npx skills-manifest init

它会自动帮你完成以下几件事：

1. 将 skills 和 skills-manifest 安装到 devDependencies 中；
2. 如果项目中还没有 skills-manifest.json，它会生成一份带有默认 agents 配置的模板文件；
3. 在 .gitignore 中添加 skills，避免将拉取下来的 skill 源码提交到仓库；
4. 在 package.json 的 scripts.prepare 中自动追加 skills-manifest install 命令。这样，其他开发者执行 pnpm i 后，就会自动按照 manifest 配置安装一遍技能。

当然，如果你不想使用 init 命令，也能手动安装：pnpm add skills skills-manifest -D，然后自行创建 skills-manifest.json 文件，再手动修改 prepare 脚本。

依然可用 npx skills 为项目添加技能

安装并运行过 skills-manifest install 之后，你只需像往常一样使用 npx skills add （或 pnpx skills add ）向项目中添加 skill。该操作会自动同步到 skills-manifest.json 文件中。团队其他成员下次执行 pnpm i 时，就能自动拉取到同样的技能，省心省力。

配置结构长什么样

skills-manifest.json 文件主要包含两大块内容：agents 和 skills。

• agents：需要同步到的 AI 客户端。例如 cursor、claude-code。执行 install 时，它会将这些 agent 对应的目录（如 .cursor、.opencode）从 .agents 同步过去。
• skills：以“仓库”为 key，value 有三种写法：
  • 数组：只安装列出的 skill 名称，例如 ["find-skills"]；
  • 对象：{ "skill-a": true, "skill-b": false }，只安装值为 true 的；
  • true：该仓库下的所有 skill 全部安装。

来看一个具体的示例：

{
    "$schema": "https://raw.githubusercontent.com/hairyf/skills-manifest/main/skills-manifest.schema.json",
    "agents": ["cursor", "claude-code"],
    "skills": {
        "vercel-labs/skills": ["find-skills"],
        "vercel-labs/agent-skills": {
            "vercel-composition-patterns": true,
            "vercel-react-best-practices": true
        }
    }
}

仓库名可以使用短名称（如 vercel-labs/skills），也可以用完整 URL（如 https://github.com/vercel-labs/skills）。配置好之后，在项目中执行：

pnpm exec skills-manifest install

它就会按照这份清单，依次执行 skills add，并将 .agents 同步到 .cursor、.opencode 等目录。这样一来，Cursor 和 Claude Code 使用的就是同一套技能了。

此外，install 命令还会在 node_modules/skills 中注入一个包装脚本，让本机的 skills 命令和 manifest 实现双向同步：

• 当你执行 skills add [--skill ...] 时，包装脚本会顺带执行 skills-manifest add [...]，自动将仓库和技能写入 skills-manifest.json；
• 当你执行 skills remove <技能名...> 时，包装脚本会根据 manifest 中哪些 repo 包含这些技能，对每个 repo 执行 skills-manifest remove <技能名...>，从 manifest 中删除对应的项。

如果只是临时添加一个 skill，不希望它被写入 manifest，可以加上 --skip-manifest 参数：

skills add --skip-manifest

这样一来，团队既可以通过 manifest 一键同步，也能在日常中直接使用 skills add/remove 操作，manifest 会自动跟随更新，非常灵活。

与 OpenSkills / AGENTS.md 搭配使用（可选）

如果你希望 AI 客户端不仅能够“安装”技能，还能“看到”项目中有哪些技能以及各自的用途，可以再配合 OpenSkills 使用。

先按照上述步骤用 skills-manifest 安装好技能，然后在项目中执行：

npx openskills sync

OpenSkills 会根据当前安装的 skills，生成或更新 AGENTS.md 文件（或你指定的其他文件）。Claude Code、Cursor、Windsurf 等工具读取该文件后，就能自动发现并选用这些技能。如此一来，“安装”和“发现”两个环节就全打通了。

总结

• skills-manifest 通过一份 skills-manifest.json 文件，声明项目需要使用的 skills 以及分配给哪些 agents。执行 skills-manifest install 即可按声明安装并同步到各客户端目录。
• install 命令会注入包装脚本：之后在本机使用 skills add / skills remove 时，会自动同步到 manifest，无需额外操作。
• 借助 skills-manifest.json 和 prepare 脚本，团队成员在克隆项目后，只需执行 pnpm i 就能自动复现同一套技能，彻底杜绝各装各的混乱局面。
• 如果需要让 AI 读取“项目里有哪些技能”，可以再加一步 npx openskills sync 来生成 AGENTS.md 文件。