聊聊 Agent Skills 这个东西
|
zhenglin
2026年3月6日 10:39
本文热度 159
|
1. Agent Skills 是什么
简单说，Agent Skills 就是你写给 AI 看的"操作手册"。它是一个放在特定目录下的 SKILL.md 文件，AI 在遇到相关任务时会自动去读它，然后按里面写的方式干活。
类比一下：
把 Cursor Agent 想象成刚入职的新同事，Skills 就是你递给他的操作手册——不是公司规章（那是 Rules），也不是外部系统的接口文档（那是 MCP），而是"碰到这类问题，按这套流程搞定"的具体指南。
为什么需要它？
2. Skills、Rules、MCP — 傻傻分不清楚？
这三个东西确实容易混，但定位其实很清晰：
遇到问题，该用哪个？决策很简单：
需要访问外部数据/工具（数据库、浏览器、API）？
→ MCP
是全局性的行为偏好（语言、输出格式、禁止什么）？
→ Rules
是某个具体场景下的专业知识或工作流程？
→ Skills
3. Skill 文件长什么样
目录结构
~/.cursor/skills/
└── skill-name/
├── SKILL.md # 必须有，主文件
├── reference.md # 可选，详细参考文档
├── examples.md # 可选，用法示例
└── scripts/ # 可选，辅助脚本
└── validate.py
SKILL.md 格式
---
name: skill-name # 小写字母 + 连字符，最多 64 字符
description: 第三人称描述，说清楚"什么场景用"和"能做什么"
---
# Skill 标题
## 核心规则 / 操作步骤
...
放哪里的区别
注意：~/.cursor/skills-cursor/ 是 Cursor 内置目录，别往里放自定义 Skill。
4. 我当前整理的 Skill
目前配置了 6 个 Skill，覆盖 Vue 前端开发的核心场景：
api-list-fetch — Vue 列表页 API 请求规范
什么时候触发：写分页列表页、处理请求错误、同步查询状态
核心内容：
onSuccess 里更新 total / page / size
onError 调用 initialPage() 重置状态
onComplete 把实际发送的参数同步回 SearchBox 组件
刷新按钮直接调接口，不刷整页
有啥用：避免每次列表页都写出风格不一的分页逻辑，尤其是 onComplete 同步输入框这个细节特别容易漏。
gitc — Git Commit 规范自动提交
触发方式：输入 @gitc <描述>
核心内容：
自动识别 type（feat / fix / refactor / perf / docs 等）
把中文描述翻译成英文祈使句
生成符合 @commitlint/config-conventional 的 commit message
直接跑 git add src/ + git commit + git push
示例：
@gitc 修复日期格式化 bug
→ git commit -m "fix: correct date formatting"
有啥用：再也不用手动想 commit message 怎么写了，而且能直接过 husky 的 commit-msg 校验。
i18n-text-rules — 英文 i18n 文本大小写规则
什么时候触发：生成或审查英文翻译键
核心规则：
有啥用：英文大小写是最容易出错的细节，规则统一了就不会出现同个页面一会儿 Title Case 一会儿全大写的问题。
ui-standards — UI 间距与边距规范
什么时候触发：写或审查 UI 组件布局
核心规则：
按钮间距：ml-6 / mr-6
图标间距：mr-5 / ml-5
文字 + 按钮/输入框：5px
空状态图标与文字：mb-10
有啥用：间距这种东西最容易每个人写法不一样，固化成标准省去很多 review 来回。
vue-coding-standards — Vue 文件编码规范
什么时候触发：写或审查 *.vue 文件
核心规则摘要：
vue-component-usage — Vue 业务组件引用规范
什么时候触发：写业务组件、引用 UI 组件、拆分页面
核心内容：
组件优先级：src/viewComponents/common > src/components > custom-vue3-component
组件清单：内置 custom-vue3-component 的完整列表（xTable、xBtn、xModal 等 30+ 个）
页面拆分：List 页面拆成 SearchBox.vue + List.vue + Detail.vue
查询条件双状态：草稿状态（SearchBox 内部持有）vs 已提交状态（Page 持有的 lastParams）
有啥用：这是内容最多的一个 Skill，解决了"AI 不知道项目有哪些私有组件"的根本问题，同时规范了页面的架构模式。
5. AI 怎么知道该用哪个 Skill
Cursor Agent 处理请求时，会扫描所有 Skill 的 description 字段，判断当前任务是否匹配。匹配到了，就先完整读 SKILL.md，再按里面的指南干活。
所以 description 怎么写，直接决定 Skill 能不能被触发：
# 写得太模糊 — 基本不会触发
description: Vue 相关规范
# 写得好 — 包含做什么 + 什么时候用 + 关键词
description: Vue *.vue 文件编码规范，涵盖代码顺序、常量定义、ref 用法、析构赋值、
函数命名、loading 命名、属性命名等规则。当编写或审查 *.vue 文件代码
风格、命名规范、变量定义方式时使用。
记住一点：用第三人称写，带上场景触发词（"当...时使用"）。
6. 怎么写一个好用的 Skill
精简比详尽更重要
Skill 内容会占 AI 的上下文窗口，每一行都在和其他信息抢空间。
根据任务特性选写法
核心放主文件，细节放子文件
代码高亮：
## 完整 API 参数说明
详见 [reference.md](reference.md)
用例子比用文字描述有效得多
对于输出格式类 Skill，"好的 vs 坏的"比大段描述更直接：
✅ `search()` — 正确
❌ `doSearch()` / `handleSearch()` — 别这么写
7. 还有哪些能用上的场景
这些场景日常容易忽视，但用 Skills 来处理效果很好：Code Review 自动化
把团队的 CR checklist 写成 Skill，AI 审代码时自动对照：
- [ ] 没有硬编码的魔法数字
- [ ] 错误边界处理完整
- [ ] 组件命名符合 PascalCase
- [ ] 没有直接修改 props
文档模板生成
把 PRD、技术方案的固定格式写进 Skill，AI 生成时自动套用结构，不用每次重新描述文档框架。
测试用例规范
规定单测文件命名、describe/it 块结构、Mock 方式，避免每个文件风格各异。
API 接口约定
把后端的统一响应格式（比如 { code, message, result } 结构）、鉴权方式、错误码含义写进 Skill，AI 处理接口调用时自动对齐，不再生成和实际不符的解构代码。
8. 容易踩的坑
把 Rules 的内容写进了 Skill
全局性的行为约束（比如"不输出完整文件"）应该放 Rules，不要放进按需触发的 Skill 里。
Skill 内容太宽泛
# 错误：范围太大，触发时啥都匹配不上
name: frontend
description: 前端相关规范
# 正确：聚焦具体场景
name: vue-coding-standards
description: Vue *.vue 文件编码规范...当编写或审查 *.vue 文件时使用
一个 Skill 塞了所有内容
每个 Skill 应该只干一件事。本项目把规范拆成 vue-coding-standards、vue-component-usage、ui-standards 三个，各管各的，比合并成一个大 Skill 好维护，触发也更准。
没认真写 description
Description 是 AI 发现 Skill 的唯一入口。写得模糊，Skill 基本等于摆设。
9. 动手写第一个 Skill
第一步：确定放哪
- 个人用、跨项目复用 →
~/.cursor/skills/ - 团队共享、项目专属 →
.cursor/skills/（提交到 git）
第二步：建目录和文件
mkdir ~/.cursor/skills/my-skill
touch ~/.cursor/skills/my-skill/SKILL.md
第三步：写 SKILL.md
---
name: my-skill
description: [第三人称描述能做什么]。当[触发场景]时使用。
---
# My Skill
## 核心规则
1. 规则一
2. 规则二
## 示例
✅ 正确写法
❌ 错误写法
第四步：验证一下
在 Cursor 里触发相关任务，看 AI 有没有引用 Skill 里的内容。也可以直接在对话里点名：按照 my-skill 的规范...
最后总结一下
Skills 真正的价值在于把团队的隐性知识显性化。那些"大家都懂但 AI 不知道"的规范、模式、约定，通过 Skills 沉淀下来，AI 才能真正融入团队，而不只是个通用代码生成器。
参考文章：原文链接
该文章在 2026/3/6 10:39:08 编辑过
400 186 1886
