Skill 说明
Skill（技能） 泛指给 AI Agent（智能体） 用的、可复用的说明性资产：通常用 Markdown 等文本写成，告诉模型「在什么场景下、按什么步骤、用什么标准」完成一类重复性或专业性很强的工作。它和一次性写在聊天框里的长提示不同，Skill 往往会被 持久保存、按需加载，适合沉淀团队规范、个人工作流、领域知识（例如发布 checklist、代码评审口径、数据库查询约定等）。
Skill 并非 Cursor 独有——不同编辑器、CLI、云侧 Agent 平台都可能提供「可挂载的指令包」「项目级提示库」等同类能力；名称和文件格式也各不相同。下文在讲 目录、SKILL.md、frontmatter 时，主要以 Cursor 当前的 Agent Skill 形态 为例，便于你对照落地；在其他工具里请以其官方说明为准。
可以把 Skill 理解成：可版本化、可共享的「专长模块」，用来补足模型对「你的环境」的默认知识。
若你已了解概念，需要 在 Cursor 中的路径、落盘方式与对话里怎么用，见：在 Cursor 中配置与使用 Skill。想找 可安装的 Skill 方向与示例名，见：Skill 推荐与清单。
Skill 和 Rules、MCP 的简单区分
下表便于 在 Cursor 里 把常见能力分清边界（其他产品命名可能不同）：
| 能力 | 大致作用 |
|---|---|
Rules（如 .cursor/rules） | 偏「全局约束与习惯」：编码风格、项目约定、始终要记住的禁令等 |
| Skill | 偏「完成某类任务的操作手册」：分步骤流程、模板、检查清单、可选脚本说明 |
| MCP | 偏「连外部工具/数据」：拉取 Issue、查文档、调 API 等 |
三者可以一起用：Rules 定基调，Skill 教做事方法，MCP 提供实时数据或动作。（若不在 Cursor 中，可类比为「全局策略 / 任务手册 / 工具连接」的组合。）
目录与文件约定（以 Cursor 为例）
以下 目录与文件名 描述的是 Cursor 当前采用的 Skill 落盘形态；其他平台未必叫 SKILL.md，但「主说明 + 可选附件」的思路是相通的。
skill-name/
├── SKILL.md # 必填：主说明
├── reference.md # 可选：细则，按需再读
├── examples.md # 可选：示例
└── scripts/ # 可选：辅助脚本
└── validate.pySKILL.md 基本结构
文件顶部使用 YAML frontmatter，至少包含 name 与 description：
---
name: my-skill-name
description: 用第三人称写清「做什么」和「何时用」，便于 Agent 匹配场景。
---
# 技能标题
## 步骤一
…字段要点：
name：小写字母、数字、连字符，最长约 64 字符，作为标识。description：非常关键。Agent 会依据它判断是否与当前任务相关；建议写清 能力（WHAT） 与 触发条件（WHEN），并用第三人称（例如「生成符合团队规范的提交信息」），避免「我可以帮你…」这类口吻。disable-model-invocation（可选）：若设为true，通常表示 不要仅靠环境上下文自动拉起，更适合「只有你点名才用」的技能；是否省略取决于你希望它是「默认可被发现」还是「显式调用」——以你当前 Cursor 版本行为为准，可在设置或官方文档中核对默认值。
正文宜 短而可执行：主文件建议控制在合理长度内；长文放到 reference.md 等，由主文件一层链接过去，避免一次塞满上下文。
写好 Skill 的几条实践
- 只写模型缺的那部分：默认模型已经很强，重复百科会浪费上下文。
- 给模板和检查清单：比抽象原则更易执行。
- 路径与命令用正斜杠：文档里统一
scripts/helper.py，避免 Windows 反斜杠带来的歧义。 - 避免强时效表述：少写「截至某年某月必须用某接口」，改为「当前推荐 / 旧版见附录」。
小结
Skill 本质是 给 Agent 的、可复用的任务说明书；在 Cursor 里常以 SKILL.md + frontmatter（如 description）为载体，帮助 Agent 判断何时加载。通用写法与原则见上文；仅与 Cursor 相关的路径、编辑与调用，见：在 Cursor 中配置与使用 Skill。按场景挑选示例 Skill（如 ui-ux-pro-max、karpathy-guidelines 等），见：Skill 推荐与清单。
Cursor 产品界面与选项可能随版本变化；若与本文不一致，以 Cursor 官方文档 为准。