Cursor Agent Skill 入门指南：用一个真实案例教你从 0 到 1

本文通过一个真实的开发场景——“OpenSpec CLI 无法读取加密 .md 文件”——带你理解 Cursor Agent Skill 是什么、怎么写、怎么触发，以及为什么它能让你的 AI 编程助手变得更聪明。

---

一、Skill 是什么？一句话理解

Skill 就是你写给 Cursor AI 的操作手册。

你遇到过这种场景吗？

• 某个操作你教了 AI 一次，下次它又忘了
• 某个工作流你反复在聊天里描述，每次都要重新解释
• 某个工具的使用姿势很特殊，AI 总是猜错

Skill 的本质就是：把你教 AI 的经验，固化成一份文档，让它每次遇到同类问题时自动读取、自动执行。

不是插件，不是脚本，不需要编译——就是一个 Markdown 文件。

---

二、真实案例：问题是怎么来的

我们的项目里有一个 OpenSpec 工作流，用来管理功能变更的生命周期：提案 → 规格 → 设计 → 任务 → 实施 → 归档。

当我完成了 fix-document-extraction 这个变更的全部实施，执行归档命令时：

openspec archive "fix-document-extraction" -y

CLI 报错了：

Delta parsing found no operations for extraction-preview-ui.
Aborted. No files were changed.

奇怪的是，用 Cursor 的 Read 工具读这些 .md 文件，内容完全正确——## ADDED Requirements、### Requirement: 等结构一应俱全。

根因：项目对 .md 文件做了磁盘加密（TSD）。Cursor 的 Read 工具内置了解密层，能看到明文；但 OpenSpec CLI 是一个 Node.js 进程，直接从文件系统读，拿到的是密文——一堆 %TSD-Header-... 开头的二进制垃圾。

解决方案：用 Cursor 读出明文 → 写回磁盘覆盖密文 → 再跑 CLI → 加密层后续会自动重新加密。

问题是——下次遇到同样的情况，AI 还记得这个解法吗？

这就是 Skill 的用武之地。

---

三、Skill 的文件结构

一个 Skill 就是一个目录，里面必须有一个 SKILL.md：

.cursor/skills/
└── openspec-decrypt-for-cli/
    └── SKILL.md          ← 唯一必需的文件

存放位置

位置	路径	谁能用
个人级	~/.cursor/skills/skill-name/	你的所有项目
项目级	.cursor/skills/skill-name/	这个仓库的所有协作者

我们这个案例放在项目级（.cursor/skills/），因为加密是这个项目特有的。

---

四、SKILL.md 怎么写

4.1 必须有 YAML 头部

---
name: openspec-decrypt-for-cli
description: Fix OpenSpec CLI failures caused by encrypted .md files. Use when openspec validate, openspec archive, or openspec sync fails with errors like "No delta sections found" or "Delta parsing found no operations".
---

两个字段：

• name：小写字母 + 数字 + 连字符，最多 64 个字符
• description：最关键的字段——Cursor 用它来决定什么时候该读这个 Skill

4.2 description 怎么写才有效

description 决定了 Skill 能不能被 AI “发现”。写法有三个要点：

1) 用第三人称（因为它会被注入到系统提示词里）

✅ Fix OpenSpec CLI failures caused by encrypted .md files.
❌ I help you fix OpenSpec CLI failures.

2) 既写"做什么"，也写"什么时候用"

✅ Fix OpenSpec CLI failures caused by encrypted .md files.
   Use when openspec archive fails with "No delta sections found".

❌ Handles encrypted files.  （太模糊）

3) 包含具体的触发关键词

把你希望 AI 能识别的错误信息、命令名、场景描述都写进去：

"No delta sections found", "Delta parsing found no operations",
"openspec validate", "openspec archive"

这样当这些词出现在对话或命令输出中时，AI 更容易匹配到这个 Skill。

4.3 正文：写清楚步骤

正文就是操作手册。以我们的案例为例：

# OpenSpec: Decrypt MD Files for CLI

## When to Use

Detect this situation when ANY of these appear in CLI output:
- "Delta parsing found no operations"
- "No delta sections found"
- YAML warnings containing garbled binary like `%TSD-Header-`

## Steps

1. **列出所有加密的 .md 文件**
2. **用 Cursor Read 工具读取明文**
3. **用 Write 工具写回磁盘**（覆盖密文为纯 UTF-8）
4. **运行 openspec validate 验证**
5. **重试原来的 CLI 命令**

4.4 写作原则

原则	说明
简洁	AI 本身很聪明，只写它不知道的。不要解释什么是 Markdown
< 500 行	SKILL.md 主文件控制在 500 行以内
具体	给命令、给路径、给期望输出，不要说"大概这样做"
一致术语	全文统一用"加密/密文/明文"，不要混用"编码/乱码/加密"

---

五、Skill 是怎么被触发的

这是最常被误解的部分。Skill 不是自动运行的脚本，它的触发机制是：

你发消息 → Cursor 扫描所有 Skill 的 description
         → 找到匹配的 Skill → 读取 SKILL.md
         → AI 按照里面的步骤执行

触发场景举例

你说的话 / 发生的事	会触发吗	原因
“帮我归档这个变更” → CLI 报 delta parsing 错误	会	AI 看到错误关键词，匹配 description
“openspec archive 报 No delta sections found”	会	你的消息里有触发关键词
“归档失败了，md 文件加密了”	会	“加密” + “归档失败” 匹配 description
CLI 在后台静默失败，没人提起	不会	没有对话触发
跟 Skill 无关的普通编码问题	不会	description 不匹配

关键认知

Skill 是给 AI 的备忘录，不是给机器的自动化脚本。
它确保 AI 在遇到特定问题时，有一套已验证的标准流程可以遵循——而不是每次重新猜测。

---

六、完整示例：我们写的 Skill

下面是本文案例的完整 SKILL.md，你可以当作模板参考：

---
name: openspec-decrypt-for-cli
description: Fix OpenSpec CLI failures caused by encrypted .md files.
  Use when openspec validate, openspec archive, or openspec sync fails
  with errors like "No delta sections found", "Delta parsing found no
  operations", or "No deltas found" due to on-disk encryption that
  Cursor can read through.
---

# OpenSpec: Decrypt MD Files for CLI

When .md files in openspec/changes/ are encrypted on disk, OpenSpec CLI
cannot parse them — but Cursor can read the plaintext via its Read tool.

This skill bridges the gap: read via Cursor, write plaintext back, run
CLI, then let the encryption layer re-encrypt.

## When to Use

Detect this situation when ANY of these appear in openspec CLI output:
- "Delta parsing found no operations"
- "No delta sections found"
- "No deltas found"
- YAML warnings containing garbled binary like %TSD-Header-

## Steps

1. Identify all encrypted .md files in the change directory
2. Read each file via Cursor's Read tool (sees decrypted content)
3. Write plaintext back to disk via Write tool
4. Run: openspec validate "<change-name>"
5. Retry the original CLI command

## Integration with Archive Workflow

1. First attempt: openspec archive "<name>" -y
2. If delta parsing errors → trigger this skill
3. After plaintext rewrite + validate → retry archive

## Notes

- Only touch files inside openspec/changes/<name>/
- The encryption layer will re-encrypt automatically

---

七、创建你自己的第一个 Skill

现在你已经理解了 Skill 的工作原理，可以试着为自己的场景创建一个。

快速检查清单

• 想清楚：这个知识/流程，AI 下次还会忘吗？→ 如果会，就值得写成 Skill
• name：小写 + 连字符，简短有意义
• description：包含触发关键词，写明"做什么"和"什么时候用"
• 正文：步骤清晰，命令具体，< 500 行
• 放对位置：个人通用 → ~/.cursor/skills/；项目专属 → .cursor/skills/

适合做成 Skill 的场景

• 项目特有的部署流程
• 特殊的代码生成模板
• 团队的 PR 规范和 Review 标准
• 特定工具链的使用姿势（比如本文的 OpenSpec + 加密）
• 反复出现的 debug 套路

不适合做成 Skill 的场景

• 通用编程知识（AI 已经知道）
• 一次性的操作（不会重复）
• 需要实时数据的判断（Skill 是静态文档）

---

八、总结

概念	一句话
Skill 是什么	给 AI 的操作手册，Markdown 格式
怎么触发	Cursor 根据 description 自动匹配，或你主动提到相关场景
核心文件	SKILL.md，必须有 YAML 头部（name + description）
description 怎么写	第三人称 + 做什么 + 什么时候用 + 触发关键词
正文怎么写	简洁、具体、< 500 行、步骤清晰
放哪里	~/.cursor/skills/（个人）或 .cursor/skills/（项目）

Skill 的价值不在于它有多复杂，而在于它把一次性的经验变成了可复用的知识。你教 AI 一次，它就永远记住了。

---

本文基于 Cursor Agent Skill 机制，结合 项目中 OpenSpec 归档遇到加密文件问题的真实案例撰写。