一、常见误解
很多人第一次接触 Skills，以为它只是“给 Cursor 写规则文档”。这个理解太窄了。
Skills 的本质是可复用的能力模块。它不只是“规定输出格式”，而是可以封装任意需要多步操作、特定上下文或外部工具配合的任务。
二、三种类型
| 类型 | 核心作用 | 典型场景 |
|---|---|---|
| 约束型 | 规定格式和边界 | commit 规范、代码注释风格 |
| 流程型 | 固定多步操作 | PR 审查流程、部署前置检查 |
| 工具型 | 集成外部能力 | 调用 API、执行脚本、解析日志 |
实际使用中，一个 Skill 往往是三种类型的混合体。比如 PR 审查 Skill：既约束标题格式（约束型），又执行拉 diff→检查→报告（流程型），还可能调用 Jira API 查单号状态（工具型）。
三、存放位置
全局 Skills：~/.cursor/skills/
作用于所有仓库。适合 commit 规范、通用注释风格。
项目 Skills：<项目根>/.cursor/skills/
仅作用于当前仓库。适合业务命名规则、内部系统集成。
优先级：项目 Skills 覆盖全局 Skills。
四、触发机制
自动触发
在 Skill 文件的 description 中描述使用场景。Cursor 根据用户当前操作自动判断加载。
示例：
description: Use when writing or reviewing commit messages, git log, or changelog entries
手动调用
对话中输入“使用 xxx Skill 帮我……”或通过 Command Palette 选择。
五、完整流程
flowchart TD
A[用户执行操作] --> B{Cursor 匹配描述}
B -->|匹配| C[加载 Skill]
B -->|不匹配| D[默认行为]
C --> E{识别类型}
E -->|约束型| F[按规则输出]
E -->|流程型| G[执行步骤序列]
E -->|工具型| H[调用外部能力]
F --> I[返回结果]
G --> I
H --> I
六、实战案例
案例一：commit 规范（约束型）
配置前，Cursor 输出 update code、fix bug 等无效信息。
配置 git-conventional-commits Skill 后，输出：
feat(cloud): 支持项目资源增量同步
fix(login): 修复 token 过期后未刷新
案例二：PR 自动审查（流程型）
一个 PR 审查 Skill 封装以下步骤：
- 拉取当前 PR 的 diff
- 扫描调试代码（
console.log、print、debugger） - 验证 commit 类型是否符合规范
- 输出结构化报告
用户只需说“审查这个 PR”，四步自动完成。
案例三：日志分析（工具型）
一个日志分析 Skill 可以：
- 读取
.log文件 - 按正则提取错误堆栈
- 调用
grep/jq过滤 - 输出分类汇总和频率统计
用户不再需要手动组合 shell 命令。
七、修复类提交演示
flowchart LR
A[编写修复代码] --> B[触发 fix 类型]
B --> C[生成标题<br/>fix(auth): token过期未刷新]
C --> D[生成 body<br/>原因/方案/影响]
D --> E[一键确认提交]
实际输出：
fix(auth): token过期后未刷新
原因：session超时未触发刷新逻辑
方案：拦截器增加401处理
影响：仅影响jwt过期场景
八、关键提醒
- description 决定触发率：写“use when writing commit”比写“commit helper”准确得多
- 非强制执行：Cursor 尽量遵守 Skill，但关键规则仍需 CI/hook 兜底
- 混合使用：不要被三种类型限制，一个 Skill 可以同时包含约束、流程和工具调用
九、起步建议
- 从约束型开始，放一个 commit 规范到全局 Skills
- 使用一周，观察触发效果，调整 description
- 按需增加流程步骤（如自动检查）
- 需要外部能力时再集成工具调用
一个 Skill 配置正确后，用户不再需要每次重复解释规则，也不需要手动执行多步操作。这是 AI 辅助编码从“对话”走向“自动化”的关键一步。
