📋 本文目录

01 · 为什么需要 Agent Skill（而非重复 Prompt）

在 Cursor、Claude Code 等 AI 编程助手中，Agent Skill 是一套可被智能体按需发现、激活并执行的指令包。与每次对话里临时粘贴的长 Prompt 不同，Skill 以 SKILL.md 文件形式沉淀在仓库或用户目录中，由系统在合适的任务场景自动挂载——相当于给 Agent 一本「岗位手册」，而不是每次面试都重新口述一遍公司规章。

重复 Prompt 的典型问题是：不可版本化、难以在团队间共享、无法被其他 Agent 运行时复用。当你把「按我们公司的 PR 规范写描述」「部署前要跑这三条命令」写进 Skill，新同事打开同一仓库即可获得一致行为；而聊天记录里的 Prompt 会在换模型、清上下文或切换项目后彻底消失。2026 年起，Cursor 2.4+ 将 Skill 与 Rules、MCP 并列纳入 Agent 能力栈，Skill 专门承载流程性、领域性、可重复的工作流知识。

若你已在本地跑 OpenClaw、OpenHuman 等 Agent，可把 Skill 理解为「只教 Agent 怎么做某类事」的模块化扩展；与通用 Rules（始终生效的约束）和 MCP（对外部系统的实时调用）形成互补。下文会给出对照表，避免三者混用导致上下文膨胀。

02 · 三大痛点：重复 Prompt 的代价

在把团队经验沉淀为 Skill 之前，多数团队会先经历下面三类低效模式：

上下文漂移：同一段「提交信息必须中文、禁止 force push」的说明，在不同会话里被模型截断或遗忘，导致偶发违规操作；长 Prompt 占用 token，挤占真正用于读代码的窗口。
知识孤岛：资深工程师脑子里的部署 checklist 无法传递给实习生使用的 Agent；每人维护自己的「魔法 Prompt」文档，合并时互相覆盖，无人负责评审。
脚本型工作流不敢自动化：Skill 里若包含 bash、npm publish 等命令，在主力开发机上直接让 Agent 执行风险过高；缺乏可丢弃的隔离环境试跑，团队宁愿继续手工复制命令。

Agent Skill 通过版本控制的 Markdown + 可选脚本目录解决前两点；第三点则建议结合本文第十节的「租用 Mac 五步隔离试跑」——在干净 macOS 节点验证后再合并进生产仓库。

03 · Skill 与 Rule 决策矩阵

Cursor 用户常问：「这段说明该写进 .cursor/rules 还是 Skill？」核心区别在于是否始终注入与是否绑定特定任务类型。

维度	Agent Skill	Cursor Rule
加载时机	任务匹配时按需激活	会话内持续生效
典型内容	PR 流程、发布检查、SDK 集成步骤	代码风格、禁止 amend、语言偏好
存放位置	`.cursor/skills/` 或用户级 skills	`.cursor/rules/` 或 `AGENTS.md`
对 token 影响	仅相关任务时占用	每条 Rule 都可能常驻
适合谁维护	领域负责人（DevOps、SDK 组）	架构 / 工程规范负责人

简单决策口诀：「希望 Agent 每次对话都遵守」→ Rule；「只有用户提到某类任务时才需要」→ Skill。 切勿把 500 行的部署手册塞进 always-on Rule，否则会拖慢所有无关对话。

04 · 目录结构与 SKILL.md 规范

项目级 Skill 推荐放在仓库根目录的 .cursor/skills/<skill-name>/SKILL.md；个人通用 Skill 可放在 ~/.cursor/skills-cursor/（Cursor 内置模板类 Skill 也使用此路径）。每个 Skill 是一个文件夹，而非单文件散落。

                        # 推荐目录示例

.cursor/skills/deploy-staging/

├── SKILL.md          # 必需：frontmatter + 主流程

├── scripts/          # 可选：可执行脚本

│   └── smoke-test.sh

└── references/       # 可选：长文档，按需读取

    └── rollback.md

SKILL.md 顶部必须使用 YAML frontmatter，其中 name 与 description 为必填项。description 是路由键：Agent 在「发现阶段」只读所有 Skill 的 name + description，据此决定是否进入「激活阶段」加载全文。因此 description 应写清做什么、何时用、边界条件，而不是营销口号。

                        ---

name: deploy-staging

description: Staging 环境发布检查清单。在用户要求部署到 staging、预发布验证或执行 smoke test 时使用。包含 SSH 与 npm 步骤，不用于生产。

---

# Staging 发布

## 前置条件

...

05 · 三级渐进加载机制

为控制上下文成本，Cursor Agent Skill 采用三级渐进加载，与 Claude 文档中的 Skill 设计一致：

第一级 · 发现（Discovery）：启动或规划任务时，系统扫描可用 Skill 列表，仅将每个 Skill 的 name + description 注入元数据层，供模型判断「是否需要某本手册」。
第二级 · 激活（Activation）：当用户意图与 description 匹配时，将整个 SKILL.md 正文载入上下文，Agent 按其中步骤执行。
第三级 · 按需（On-demand）：scripts/、references/ 下的附属文件默认不加载；仅当 Skill 正文指示「读取 references/foo.md」或「运行 scripts/bar.sh」时，Agent 才通过工具读取或执行。

理解这三级后，你会明白为何要把长 API 文档拆到 references/，以及为何主文件应保持在约 500 行以内——超过后不仅难维护，激活阶段也会一次性吃掉过多 token。

06 · 如何创建 Skill（六步流程）

创建方式分两类：对话内引导与手工编写。

方式 A：使用 /create-skill（推荐新手）

在 Cursor Agent 对话中输入 /create-skill 或自然语言「帮我创建一个 Skill」，会进入官方 create-skill 引导流程：收集用途、触发场景、步骤与约束，并生成符合 frontmatter 规范的目录结构。适合第一次把口头经验结构化。

方式 B：手工六步（适合团队标准化）

定义单一职责：一个 Skill 只解决一类任务（例如「创建 GitHub PR」），不要合并无关流程。
撰写可路由的 description：用第三人称写清触发词与排除场景（「不用于生产环境」）。
mkdir 并创建 SKILL.md：在 .cursor/skills/your-skill/ 下新建文件，填写 frontmatter 与分步说明。
拆分附属资源：超过 100 行的参考表、Shell 脚本放入 references/、scripts/，正文中用链接指向。
本地对话验证：用与 description 一致的说法请求 Agent，确认 Skill 被激活且步骤正确。
提交 PR 并写 README 索引：在团队文档中列出可用 Skill，避免成员重复造轮子。

团队还可将 Skill 目录纳入 CI：检查 frontmatter 字段、禁止提交密钥、对 scripts/*.sh 做 shellcheck——与对待普通代码相同。

07 · 最佳实践与硬限制

📌 三条硬数据（2026 生态）：

开放技能目录 agentskills.io 已索引超过 31,000 个社区 Skill，覆盖 DevOps、测试、文档、安全审计等垂直场景；
Cursor 自 2.4+ 起在 IDE 内原生支持项目级与用户级 Skill 发现，并与 Agent 模式深度集成；
官方 create-skill 规范建议 SKILL.md 正文控制在约 500 行以内，更长内容应拆至 references，以符合三级加载的激活成本模型。

实践要点汇总：

description 即路由键：写「Use when…」式触发条件，避免模糊形容词；
单一职责：多个独立流程应拆成多个 Skill，便于发现阶段精准匹配；
脚本注明副作用：会改磁盘、调 API、发版的步骤必须加粗警告；
与 Rule 分工：全局「禁止」放 Rule，流程「怎么做」放 Skill；
定期修剪：过时的 Skill 比没有更糟——会在错误任务上激活误导 Agent。

08 · 2026 技能生态一览

2026 年 Agent Skill 已从「Cursor 私有技巧」演进为跨工具 interchange 格式。agentskills.io 提供开放规范与搜索，社区贡献的 Skill 可 fork 后按团队规范改写 description 与脚本路径。Cursor Marketplace（内置扩展市场）则分发经过初步审核的 Skill 包，适合快速引入「写 commit message」「生成 CHANGELOG」等通用能力。

与本地 Agent 栈结合时，常见模式是：用 Skill 固化仓库内工作流，用 MCP 连接 Jira、数据库、浏览器；用 Rule 锁定安全红线。若你在 Mac 上跑 OpenClaw 与 OpenHuman 双 Agent，可为各自维护独立 .cursor/skills 目录，避免记忆与工具权限混用。

硬件选型方面，编写 Skill 本身对算力要求不高；但若 Skill 内含本地模型推理或 Xcode 构建步骤，可参考 M4 macOS 算力与价格对照，评估是按天租用还是自购更划算。

09 · FAQ：Skill、MCP 与作用域

Skill 和 MCP 有什么区别？

Skill 是静态/半静态的 Markdown 指令与可选脚本，教 Agent「按什么顺序思考与操作」；MCP（Model Context Protocol） 是运行时协议，让 Agent 调用外部工具（查库、发 Slack、操作浏览器）。Skill 不会自动替代 MCP：你需要实时读生产数据库时，仍应配置 MCP Server；需要统一「发版前检查清单」时，用 Skill。

全局 Skill 和项目 Skill 放哪里？

项目级：<repo>/.cursor/skills/，随 Git 共享，适合团队规范。用户级：~/.cursor/skills-cursor/ 或工具文档中的用户 skills 路径，适合个人偏好（如你喜欢的 PR 模板）。Agent 会合并扫描；同名时以项目级覆盖为准（具体行为以 Cursor 当前版本文档为准）。

Skill 会被自动执行吗？

Skill 指导 Agent 如何执行，但是否调用终端、是否写文件仍受 Agent 权限与用户确认策略约束。含破坏性命令的 Skill 务必在 description 中标注，并优先在隔离环境试跑。

可以从 agentskills.io 直接导入吗？

多数社区包提供文件夹下载或 Git 子模块方式；导入后务必重写 description以匹配你们仓库的技术栈（包管理器、分支策略），并审查 scripts/ 内容，勿盲目信任第三方 shell。

远程接入与计费细节可参考：《按天租用 Mac 指南：SSH、VNC 与费用 FAQ》。

10 · 租用 Mac 隔离试跑脚本型 Skill（五步）

当 Skill 包含 npm test、docker compose、签名打包等命令时，不建议先在个人主力机上让 Agent 全自动执行。更稳妥的做法是在可丢弃的租用 Mac 上完成验证，再合并到 main 分支。

租用节点：选择 Apple Silicon、预装 Xcode / Homebrew 的 macOS 镜像（如 Mac mini M4），通过 SSH 或 VNC 接入。
克隆仓库到隔离机：使用只读 token 或临时 fork，避免 Skill 脚本接触生产密钥。
仅启用待测 Skill：暂时禁用其他实验性 Skill，缩小变量，观察 Agent 是否按 SKILL.md 逐步执行。
记录命令与退出码：将终端输出保存为验收证据，失败则改 SKILL.md 或 scripts，而非直接在生产机重试。
通过后合并并归档环境：确认无误后提交 Skill PR；释放租用实例，避免持续计费。

Windows 云主机或 Linux VPS 虽可跑部分 Node/Python Skill，但涉及 Xcode、iOS 签名、Apple 公证、Keychain 的步骤仍依赖真实 macOS。许多团队把「云端 Windows 开发 + 本地 Mac 出包」拆成两套环境，结果在路径、证书与 CocoaPods 上反复踩坑。按天租用 Mac 可在与生产一致的系统上试跑 Skill，成本远低于误操作导致的证书吊销或连夜排障；算力单价也可对照 M 系列租用与自购 TCO 再决策。