Cursor里的Agent Skill是个好东西，但很多人不知道咋下手。今天就用Conventional Commits（约定式提交）当例子，从头到尾教你建目录、写SKILL.md、在Cursor里触发并验证。

一、选一个最小场景：Conventional Commits

Conventional Commits是一套常见的commit信息格式：<type>(<scope>): <description>，比如feat(auth): add login endpoint、fix(api): handle null response。团队统一用这套格式，历史记录好读，也方便做自动化（比如根据type生成更新日志）。

为啥拿这个当第一个Skill？

因为这活儿特别适合：任务单一、步骤固定、有明确的格式和示例。写进SKILL.md，以后你说"写一条commit"，助手就按同一套规范输出，不用每次重新教一遍。

二、建目录、写SKILL.md

1. 目录放哪儿？

在Cursor里，技能可以放两个地方：

• 项目内：项目根目录下.cursor/skills/（或.agents/skills/），跟着仓库一起走，团队都能用

• 个人：~/.cursor/skills/，只对你本机生效

先选一种。比如在项目根目录执行（Windows用PowerShell或Git Bash）：

mkdir -p .cursor/skills/commit-message

文件夹名建议和技能名一致，比如就叫commit-message。

2. SKILL.md里写什么？

每个技能必须有YAML frontmatter（文件最开头、用---包起来）和正文。

YAML必填两项：

• name：技能唯一标识，小写、用连字符，建议和文件夹名一样，比如commit-message

• description：用第三人称写"做什么+什么时候用"，带上用户对话里会出现的关键词（比如commit、提交、conventional commits）。助手靠description做隐式匹配，关键词写清楚才容易触发

正文写：步骤、格式说明、示例、注意事项。

3. 完整示例：commit-message

在.cursor/skills/commit-message/SKILL.md里写入：

---
name: commit-message
description: 根据当前代码改动生成符合 Conventional Commits 规范的 Git 提交信息；适用于用户说「写 commit」「写提交信息」「生成 commit message」「提交信息」「git commit」或提及 conventional commits 时。
---

# Conventional Commits 提交信息

当用户要求根据当前改动写一条 Git 提交信息时，按以下规范生成。

## 执行前

1. 执行 **`git status`**，查看工作区与暂存区状态。
2. 若存在 **"Changes not staged for commit"**（未暂存的改动），先执行 **`git add`**（或 `git add .` / 指定文件）将待提交内容纳入暂存区。
3. 再根据暂存区内容生成提交信息。

## 格式

    <type>(<scope>): <description>

- **type**（必填）：常用类型如 `feat`（新功能）、`fix`（修复）、`docs`、`style`、`refactor`、`test`、`chore`（构建/工具等），选最贴切的一个。
- **scope**（可选）：影响范围，如模块名、包名。
- **description**（必填）：简短说明，祈使句、小写开头，如「add login」而非「added login」。

## 规则

- subject 中，冒号后与 description 之间空一格；若有 scope，括号为英文半角。
- subject 总长度建议 72 字符内。若需详细说明，在 subject 后空一行再写 body；若有 BREAKING CHANGE 等 footer，再空一行书写。

## 避免

- 不在 description 用过去式（如 added、fixed），用祈使句（add、fix）。
- subject 末尾不加句号；不写过于笼统的 description（如「update code」）。

## 示例

- 改动：新增登录接口 → `feat(auth): add login endpoint`
- 改动：修复 API 返回 null 时崩溃 → `fix(api): handle null response`
- 改动：更新 README 安装说明 → `docs: update install section in README`
- 改动：重构用户模块 → `refactor(user): simplify validation logic`
- 破坏性变更：移除旧 API → `feat(api)!: remove deprecated getLegacy()`，或 subject 后空一行写 BREAKING CHANGE。

## 生成步骤

1. 执行 **`git status`**；若有 "Changes not staged for commit"，先执行 **`git add`**（或 `git add .`）再继续。
2. 简要概括当前改动（基于暂存区或工作区）。
3. 选择合适的 type 与 scope。
4. 用祈使句写 description，小写开头。
5. 输出一行 subject；若为破坏性变更或需补充说明，再写 body/footer。

保存后，这个技能就准备好了。

三、在Cursor里触发并验证

隐式触发

在Cursor的Agent对话里，正常说需求就行，比如：

• 「根据当前改动写一条commit」

• 「帮我写提交信息，用conventional commits」

助手会扫描已加载技能的description，命中「commit」「提交信息」「conventional commits」这些关键词后，就按SKILL.md里的步骤和格式输出。

显式触发

想强制走这条技能时，可以：

• 输入/，在列表里选commit-message（如果产品支持按技能名搜索）

• 或者直接说：「用commit-message技能根据当前改动写一条提交信息」

验证步骤

1. 在项目里做一点小改动（比如改一行注释或加个文件）

2. 在Agent对话里说：「根据当前改动写一条conventional commit」

3. 看助手是不是按feat/fix/docs这些格式、带scope和description输出。如果符合，说明技能生效了。

四、description与关键词为啥重要

隐式触发靠助手对「当前任务」和「技能描述」的匹配。如果description写得太泛（比如只写「帮助写提交信息」），可能不容易被选中；要是写上「commit、提交信息、conventional commits、git commit message」，用户说到其中任何一个，匹配概率就大。

写技能时多想想：用户会怎么说法？把这些说法和关键词都写进description。

五、技能不生效时怎么查

如果说了「写commit」但助手没按你的技能来，可以挨个检查：

• 路径对不对：技能放.cursor/skills/或~/.cursor/skills/下面了吗？文件夹名和name一致吗？

• description够不够：包含用户会说的关键词吗？可以适当补全同义词或常见说法

• 是不是被别的技能抢了：同一任务可能匹配多条技能，助手可能选了别的。可以试试显式「用xxx技能」指定这条

小结

从建目录、写SKILL.md（YAML+步骤+示例）到在Cursor里隐式/显式触发并验证，你就完成了第一个Agent Skill。

这技能以后每次帮你写commit，都按同一套规范来，不用再手把手教AI怎么写提交信息了。下次遇到重复性高的开发任务，都可以考虑写成Skill，省时省力。

本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！

链接: https://fly63.com/article/detial/13448