2026 Cursor Agent Skills 安装：团队配置教程

技能装好了但 Cursor 看不见 → 在目标仓库根目录用 skills.sh 安装，再检查 SKILL.md、作用域并重载 Cursor。

想让团队可复现 → 选择项目级目录，首次运行 /setup-matt-pocock-skills，把 Skills 管流程，把 Cursor Rules 管长期约束。

这篇适合 3 类人：希望快速启用 TDD、诊断和代码审查流程的个人开发者；需要统一多个成员 Agent 行为的技术负责人；以及要让本地和远程 Mac 工作区保持一致的分布式团队。

最后更新于 2026 年 8 月 13 日，数据核实自 Cursor Agent Skills 官方文档、Cursor 2.4 更新说明、mattpocock/skills README 与 skills CLI 文档。

先选项目级安装，别把团队配置放进个人目录

Cursor 当前会从项目级和用户级技能目录发现技能。项目级位置包括 .agents/skills/ 与 .cursor/skills/，用户级位置包括 ~/.agents/skills/ 与 ~/.cursor/skills/；每个技能都应是一个包含 SKILL.md 的文件夹。官方目录与文件格式说明 已明确这一点。

团队仓库优先采用项目级安装，原因不是“更专业”，而是更容易追踪变化：

• ✅ 技能文件能进入 Git，成员拉取仓库后可以复现。
• ✅ git diff 能看到脚本、引用资料和提示词的变化。
• ✅ 出现错误时，可以回退到上一个提交。
• ❌ 全局目录只对当前机器生效，换电脑、换用户或切换远程 Mac 后容易丢失。
• ❌ 在错误仓库执行命令，安装器可能把文件写进完全不相关的项目。

安装前先确认 4 个条件：

• node 与 npx 可以正常执行。
• 当前目录是目标仓库根目录。
• 当前分支允许写入配置文件。
• 你已经建立独立分支，方便审阅和回滚。

pwd
git rev-parse --show-toplevel
node --version
npx --version
git status --short

如果 git rev-parse --show-toplevel 返回的路径不是你准备配置的仓库，先停止。不要在家目录直接执行安装命令。

安装方式的取舍：skills.sh 可编辑，插件方案只选一个

Cursor 场景建议选择 skills.sh。它会把技能作为普通文件写入项目，适合团队审阅、修改和版本控制。skills CLI 基础用法 使用 npx skills add <owner>/<skill-name> 形式，运行时不要求你先全局安装 CLI。

mattpocock/skills README 同时提供两种理念不同的入口：

• 项目文件方案：通过 npx skills@latest add mattpocock/skills 选择技能，文件归你维护。
• Claude Code 插件方案：由插件统一管理整套技能，更新由上游控制。

这两种方式不要针对同一套技能同时启用。前者适合 Cursor 团队项目；后者适合不准备修改技能文件、希望跟随托管更新的成员。README 明确提醒，双装会让同一个技能出现两份。查看上游安装说明

首次安装：从仓库根目录落盘并核对文件

进入目标仓库根目录后，执行：

npx skills@latest add mattpocock/skills

安装器会让你选择需要的技能，以及要安装到哪些 Agent。第一次配置时，务必把 setup-matt-pocock-skills 选进去。其他技能不要一次性全选，先按团队当前流程添加，例如：

• 需求经常不清楚：选择 grill-me 或 grill-with-docs。
• 需要测试驱动开发：选择 tdd。
• 经常处理线上问题：选择 diagnose 或 diagnosing-bugs。
• 需要合并前检查：选择 code-review 或 review。
• 需要工单分诊：选择 triage。

skills.sh 页面当前列出了 49 个技能和聚合安装数据，但安装量只能说明传播范围，不能替代脚本安全审查或团队适配测试。项目技能列表 可用于确认当前名称，不要沿用旧文章里已经删除或改名的技能。

安装结束后，不要马上打开 Agent。先检查：

find .agents/skills .cursor/skills -name SKILL.md 2>/dev/null
git status --short
git diff --stat

你要确认 3 件事：

1. SKILL.md 位于技能自己的文件夹内，而不是直接散落在技能根目录。
2. 目录名称与文件前置元数据中的 name 一致。
3. 变更出现在当前仓库，而不是 ~/.agents/skills/ 或 ~/.cursor/skills/。

Cursor 官方要求 name 与 description 出现在 YAML 前置元数据中；name 还必须使用小写字母、数字和连字符，并与父目录名称匹配。

首次配置：手动运行 setup，再让其他技能读取结果

安装完成后，在 Cursor Agent 中手动输入：

/setup-matt-pocock-skills

这个技能不会主动替你运行。它的作用是询问并记录仓库级决策，包括：

• 使用哪个问题跟踪系统。
• triage 使用哪些分诊标签。
• 生成的领域文档放在哪里。

上游说明中，配置结果通常会写入 docs/agents/，并在仓库现有的 CLAUDE.md 或 AGENTS.md 中增加 Agent Skills 相关段落。setup 技能说明 还强调，这不是机械脚手架，而是先读取仓库现状，再让你确认后写入配置。

建议你在首次运行时逐项确认：

• 问题跟踪系统是否和仓库远程地址一致。
• 分诊标签是否已经存在，避免生成重复标签。
• 文档位置是否符合团队约定。
• 生成的 docs/agents/*.md 是否应该提交。
• CLAUDE.md 或 AGENTS.md 是否出现了正确的 Agent Skills 区块。

不要把这一步理解成“安装后的欢迎向导”。它是整个技能链的仓库初始化。后续的 triage、to-spec 和 to-tickets 依赖这些配置来判断工单位置、标签名称和文档上下文。

Skills 与 Rules：动态流程和长期约束分开维护

Cursor 在 2026 年 1 月 22 日发布的 2.4 更新中正式加入 Agent Skills。官方定位是：Skills 更适合动态上下文发现和程序化操作，Rules 更适合持续生效的声明式约束。

你可以按下面的规则分工：

放进 Skills 的内容：

• 如何执行 TDD。
• 如何诊断某类故障。
• 如何进行代码审查。
• 如何调用脚本、读取参考资料或生成工单。
• 只有在特定任务出现时才需要的步骤。

放进 Cursor Rules 的内容：

• 项目使用的语言版本。
• 不允许修改的目录。
• 测试命令和提交格式。
• API、日志、错误处理等长期规范。
• 每次 Agent 请求都应遵守的安全边界。

简单判断：如果这段文字描述“遇到某种任务时怎么做”，放 Skills；如果描述“无论做什么都必须遵守什么”，放 Rules。Cursor Rules 的作用域、自动应用方式和文件级匹配方式，可继续参考官方 Rules 文档。

不要把 disable-model-invocation: true 当成“技能失效”。它只表示 Agent 不会根据上下文自动调用该技能，你仍可以手动输入 /技能名。如果一个技能安装后完全不显示，先检查目录、SKILL.md 前置元数据和 Cursor 是否已经重载，再判断是否是作用域问题。

第一个真实任务：小范围验证，不要一次启用整套流程

完成 setup 后，选一个可以在短时间内验收的真实任务。不要用空白对话测试“技能是否存在”，因为这只能验证名称，不能验证上下文是否正确。

推荐用一个小型缺陷修复作为验收案例：

1. 先让 Agent 复述需求和验收条件。
2. 手动调用 /tdd，确认它是否先要求测试或复现步骤。
3. 如果测试失败，再调用 /diagnose，观察它是否读取错误日志和相关代码。
4. 修改完成后调用 /code-review，检查它是否关注回归风险。
5. 最后查看 Git diff，确认 Agent 没有修改约定之外的目录。

这个流程能暴露 3 类隐性问题：

• 技能名称写错，导致你调用了已经不存在的旧名称。
• 技能虽然可见，但 description 不符合实际任务，自动发现时不会触发。
• 技能引用的脚本或资料路径失效，Agent 只能输出说明，无法完成动作。

Cursor 会根据 description 判断技能是否与当前上下文相关，也支持通过 / 手动调用。技能还可以使用 paths 限定文件范围，减少无关任务中的上下文加载。

第一周治理：提交什么、更新什么、谁来批准

团队项目中，以下内容通常应该提交：

• 选定的 SKILL.md。
• 技能需要的 scripts/、references/ 和模板文件。
• setup-mattpocock-skills 生成的共享配置。
• 团队认可的 AGENTS.md 或 CLAUDE.md 变更。

以下内容更适合留在用户级目录：

• 个人快捷语句。
• 只服务于个人机器的路径。
• 尚未通过审查的实验技能。
• 包含本地凭据、内部地址或个人偏好的文件。

第三方技能不能因为安装量高就跳过审查。至少检查：

• 脚本是否会执行删除、上传或修改权限的命令。
• 引用文件是否包含敏感地址或凭据示例。
• 是否要求调用本地 CLI、网络服务或外部接口。
• Agent 是否会在没有确认的情况下写入生产相关文件。
• 技能描述是否过宽，可能在无关任务中自动触发。

更新前先查看上游差异，再决定是否执行：

npx skills update
git diff -- .agents/skills .cursor/skills

如果团队对技能做过本地修改，不要直接覆盖。先在测试分支更新，完成首个任务回归后再合并。需要撤销时，回退技能文件和对应的配置提交，不要只删除一个目录，否则 AGENTS.md 或 CLAUDE.md 可能仍然引用已经不存在的技能。

可勾选验收清单：通过、调整还是暂缓

• [ ] npx skills@latest add mattpocock/skills 在目标仓库根目录执行。
• [ ] setup-mattpocock-skills 已被首次选择并安装。
• [ ] 项目级目录中存在正确层级的 SKILL.md。
• [ ] name、description 与技能目录名称一致。
• [ ] Cursor 的 Customize → Skills 页面能看到项目技能。
• [ ] /setup-mattpocock-skills 已完成一次仓库级配置。
• [ ] docs/agents/ 中的文件经过人工检查。
• [ ] 至少完成一次 TDD、诊断或代码审查任务。
• [ ] Git diff 中没有意外写入用户级目录或错误仓库。
• [ ] 第三方脚本、引用资料和权限请求已完成审查。
• [ ] 更新流程包含测试分支、差异审阅和回滚方法。
• [ ] 本地与远程 Mac 工作区使用相同的仓库提交进行验证。

通过：技能目录、发现状态、setup 结果和首个任务都一致。
需调整：只有目录、元数据、Rules 分工或脚本权限存在问题，修正后重测。
暂缓推广：不同开发环境出现发现差异、权限失败或任务结果不可复现，先不要让全团队更新。

关于远程 Mac 的初始化、权限处理和交付验收，你可以继续查看 MacHTML 的开发环境帮助说明。本文不虚构远程环境的实测结果；没有本站真实记录时，不把公开文档推测成远程 Mac 的表现。

常见排障：为什么安装后技能仍然不可见

目录不对：先确认你打开的是包含 .agents/skills 或 .cursor/skills 的仓库根目录。多仓库窗口、嵌套仓库和错误工作区都可能让你检查错位置。

文件层级不对：正确结构应类似：

.cursor/
└── skills/
    └── tdd/
        └── SKILL.md

元数据不完整：SKILL.md 至少应有 name 和 description。name 应与父目录一致，不能使用带空格或大写字母的旧名称。

作用域不匹配：如果设置了 paths，技能只会在匹配文件出现时展示。测试时先移除过窄的路径限制，确认技能能够出现后再逐步收紧。

没有重载 Cursor：修改目录或元数据后，重新加载窗口，再到 Customize → Skills 检查。官方文档说明，已发现的项目技能会与 Rules 一起出现在 Agent Decides 区域。

重复安装：如果你同时用了 Claude Code 插件和 skills.sh 文件方案，同名技能可能来自不同位置。先保留一种来源，再删除另一份，最后重新加载 Cursor。

FAQ：安装位置、职责边界与版本来源

仓库根目录为什么比家目录更适合执行安装命令？

项目级安装要求当前路径明确指向目标仓库。你可以先运行 pwd 和 git rev-parse --show-toplevel，确认后再执行 npx skills@latest add mattpocock/skills。这样生成的技能文件能够进入 Git，团队成员也能从同一提交恢复目录、元数据和脚本，而不是依赖某台电脑的全局状态。

安装完成后，Cursor 仍然没有显示技能，应该按什么顺序排查？

先检查 .agents/skills 或 .cursor/skills 下是否存在技能文件夹和 SKILL.md，再核对 name、description、目录名及作用域字段。随后重载 Cursor，并到 Customize → Skills 查看。如果设置了 disable-model-invocation: true，自动触发会被关闭，但手动斜杠调用仍可使用。

哪些内容应该写成 Skills，哪些内容应该写进 Rules？

把 TDD、故障诊断、分诊和代码审查等“遇到特定任务才执行”的步骤写成 Skills；把语言版本、目录边界、测试命令、提交规范和安全要求等“每次都要遵守”的约束写进 Cursor Rules。不要复制同一内容，否则一处更新、另一处未更新时会出现冲突。

团队仓库和个人机器分别适合哪种技能目录？

团队项目优先使用 .cursor/skills 或 .agents/skills，因为文件可以评审、提交、复制和回滚。全局目录适合个人快捷语句、实验性技能及不应进入仓库的本地路径。包含脚本、网络调用或权限操作的技能，应在进入共享仓库前完成代码审查。

插件托管和可编辑文件方案怎样避免重复来源？

同一套 mattpocock/skills 只保留一个来源。需要在 Cursor 中修改并纳入团队 Git 管理时，采用 skills.sh 文件方案；希望由 Claude Code 插件统一托管时，采用插件方案。两者并用会让同名技能来自不同位置，造成触发歧义、更新来源不清和回滚困难。

如果你已经完成本地验证，下一步不是盲目增加技能数量，而是对照团队的远程 Mac 初始化流程，确认权限、目录、重载和回滚都能重复执行。仅靠个人 Mac 上一次成功的安装，无法证明分布式团队已经具备可交付的 Agent 工作空间。

相比项目级 Mac 方案，临时在个人电脑上维护技能通常有 3 个问题：环境路径不一致、全局目录难以审计、成员之间的 Cursor 状态无法稳定复现。若你需要的是短期测试、多人共享的临时开发环境，或要在交付前验证一套可回滚的 Cursor Agent 工作空间，可以进一步了解 MacHTML 的远程 Mac 开发环境，再按验收结果决定是否采用租赁方案，而不是把长期重负载和本地物理接口需求一律迁移到远程环境。

常见问题