在 Cursor 里创建并使用 Skill

Skill 是什么

Skill 是 Cursor 中一种教 Agent「怎么做某件事」的说明文档。它本质上是 Markdown 文件，不是插件，也不单独运行；Agent 在合适的时候读取它，按照其中的步骤和规则执行任务。

常见的用途包括：团队 Code Review 标准、提交信息格式、某个 API 的调用流程、网络连通性检查等。与其每次在对话里重复粘贴同一段 prompt，不如把这些说明固化成 Skill，Agent 可以自动发现并套用。

基本信息

注意：不要把自定义 Skill 放在 ~/.cursor/skills-cursor/，那是 Cursor 内置 Skill 的保留目录。

运作原理

1. 发现：Cursor 会扫描项目里的 .cursor/skills/ 和你个人目录下的 ~/.cursor/skills/，收集所有 Skill。
2. 匹配：当你在 Agent 对话里描述需求时，Agent 会依据各 Skill 的 description 字段判断「这份 Skill 是否和当前问题相关」。description 里写的触发词（如「网络」「连通」「Code Review」）越具体，匹配越准。
3. 执行：若匹配成功，Agent 会读取对应的 SKILL.md，按正文中的步骤执行命令、生成输出，并按 Skill 中定义的格式（如表格、清单）回复你。

也就是说：你写的是「说明书」，Agent 按说明书办事。说明书写得好，Agent 就执行得稳。

如何创建：以「网络连通性检查」为例

下面用一个简单的 network-connectivity Skill 为例，说明从零创建一个 Skill 的完整流程。

1. 创建目录结构

在项目根目录下：

.cursor/skills/network-connectivity/
└── SKILL.md

项目级 Skill 放在 .cursor/skills/ 下，会随仓库一起分享给协作者。

2. 编写 SKILL.md

主文件分两部分：YAML 元数据和 Markdown 正文。

元数据（frontmatter）

---
name: network-connectivity
description: >-
  Verifies outbound HTTPS and package-registry connectivity from the current
  environment using curl and pnpm. Use when the user asks whether the network is
  OK, to test internet connectivity, DNS, proxy issues, or registry reachability,
  or when they mention 网络, 连通, 联网, ping, or connectivity checks.
---

• name：Skill 的唯一标识，用小写字母、数字、连字符，最多 64 个字符。
• description：最重要的一栏。要写清 WHAT（做什么）和 WHEN（什么情况下该用），并包含足够多的触发词，方便 Agent 在对话中识别。建议用第三人称（如 "Verifies..."），不要用 "I help you..." 这类口吻。

正文：步骤与输出模板

正文里写明 Agent 要执行什么、如何判断成功/失败、以及如何汇报结果：

# Network connectivity test

## Steps

### 1. General HTTPS
curl -sI --max-time 5 https://www.cloudflare.com
- Pass: 出现 HTTP 状态行（如 HTTP/2 200）
- Fail: 超时、连接失败或无状态行

### 2. pnpm registry
pnpm ping
- Pass: 退出码 0，显示延迟
- Fail: 非零退出码或超时

### 3. Optional（仅在 1 或 2 失败时）
检查 HTTPS_PROXY、HTTP_PROXY 等环境变量，或执行 nslookup / dig 排查 DNS。

## Report template

| Check        | Result | Detail |
|-------------|--------|--------|
| HTTPS (curl)| OK/FAIL| ...    |
| pnpm ping   | OK/FAIL| ...    |

**Conclusion:** [一行总结：OK / 部分失败 / 完全不可达，以及建议的下一步]

这样 Agent 就知道：先跑 curl，再跑 pnpm ping，按表格输出结论。需要时才会做可选步骤。

3. 可选：补充文档

如果步骤较多或需要详细说明，可以加 reference.md、examples.md 等，在 SKILL.md 里用链接引用，保持主文件简洁。

如何使用

方式一：自然语言触发（推荐）

打开 Cursor Agent，用自然语言描述需求，例如：

• 「检查一下网络是不是通的」
• 「pnpm 源能不能连上」
• 「按 network connectivity skill 测一下网络」

若描述里包含「网络」「连通」「registry」「代理」等词，Agent 会根据 description 匹配到该 Skill，读取 SKILL.md，执行步骤并输出报告。

方式二：@ 引用文件

若 Agent 没有自动选用该 Skill，可在输入框输入 @，选择 Files，选中 .cursor/skills/network-connectivity/SKILL.md，再说：「请按这个 Skill 检查网络并输出报告。」

这样会把 Skill 全文放进上下文，行为最稳定。

方式三：手动执行

不经过 Agent 时，直接在终端执行 Skill 里的命令，自行对照 Pass/Fail 说明判断：

curl -sI --max-time 5 https://www.cloudflare.com
pnpm ping

---

Skill 把「你在对话里会反复交代的那段说明」固化成文档，让 Agent 在合适时机自动读取并执行。先理解它是什么、怎么运作，再按「元数据 + 步骤 + 输出模板」的结构去写，就能在 Cursor 里高效复用你的工作流程。