聊聊 Agent Skills 这个东西

1. Agent Skills 是什么

简单说，Agent Skills 就是你写给 AI 看的"操作手册" 。它是一个放在特定目录下的 SKILL.md 文件，AI 在遇到相关任务时会自动去读它，然后按里面写的方式干活。

类比一下：

把 Cursor Agent 想象成刚入职的新同事，Skills 就是你递给他的操作手册------不是公司规章（那是 Rules），也不是外部系统的接口文档（那是 MCP），而是"碰到这类问题，按这套流程搞定"的具体指南。

为什么需要它？

• 团队有自己的编码规范，AI 根本不知道
• 某些重复流程（比如写 commit、处理分页列表）每次都要手动纠正 AI
• 项目用了私有组件库，AI 总生成错误的组件名
• 希望 AI 在特定场景下输出固定格式

---

2. Skills、Rules、MCP --- 傻傻分不清楚？

这三个东西确实容易混，但定位其实很清晰：

维度	Skills	Rules	MCP
本质	领域知识 + 操作手册	行为约束 + 偏好设置	外部工具 / 数据源接口
作用范围	特定任务场景	所有对话 / 所有代码	需要访问外部系统时
触发方式	任务匹配时按需读取	始终注入到系统提示	显式调用工具函数
内容形式	Markdown 操作指南	简短规则列表	函数 schema + 服务端实现
存储位置	~/.cursor/skills/ 或 .cursor/skills/	.cursorrules 或 .cursor/rules/	MCP server 配置
典型例子	"Vue 列表页请求规范"	"不输出整文件内容"	"调用浏览器截图工具"
维护成本	中（按功能模块维护）	低（全局少量规则）	高（需要服务端部署）

遇到问题，该用哪个？决策很简单：

需要访问外部数据/工具（数据库、浏览器、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 标题

## 核心规则 / 操作步骤
...

放哪里的区别

位置	路径	适用场景
个人 Skill	~/.cursor/skills/	跨项目复用，个人工作流
项目 Skill	.cursor/skills/	团队共享，随代码库一起版本控制

注意：~/.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（介词小写）	List of Items
按钮、下拉选项	Sentence case	Save changes

有啥用：英文大小写是最容易出错的细节，规则统一了就不会出现同个页面一会儿 Title Case 一会儿全大写的问题。

---

ui-standards --- UI 间距与边距规范

什么时候触发：写或审查 UI 组件布局

核心规则：

• 按钮间距：ml-6 / mr-6
• 图标间距：mr-5 / ml-5
• 文字 + 按钮/输入框：5px
• 空状态图标与文字：mb-10

有啥用：间距这种东西最容易每个人写法不一样，固化成标准省去很多 review 来回。

---

vue-coding-standards --- Vue 文件编码规范

什么时候触发 ：写或审查 *.vue 文件

核心规则摘要：

规则	内容
代码顺序	props → data → computed → watch → 生命周期 → function
常量定义	在 <script>（非 setup）中定义，减少硬编码
loading 命名	GET 请求用 isFetching，其他用 isSending
函数命名	不加动词前缀：search() 而非 doSearch()
函数写法	声明式函数，不用箭头函数
属性命名	不以 _ 或 $ 开头

---

vue-component-usage --- Vue 业务组件引用规范

什么时候触发：写业务组件、引用 UI 组件、拆分页面

核心内容：

1. 组件优先级 ：src/viewComponents/common > src/components > custom-vue3-component
2. 组件清单 ：内置 custom-vue3-component 的完整列表（xTable、xBtn、xModal 等 30+ 个）
3. 页面拆分 ：List 页面拆成 SearchBox.vue + List.vue + Detail.vue
4. 查询条件双状态：草稿状态（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 的上下文窗口，每一行都在和其他信息抢空间。

• SKILL.md 建议控制在 500 行以内
• 只写 AI 默认不知道的东西（别去解释 JavaScript 基础语法）
• 详细参考内容放 reference.md，主文件里链过去就行

根据任务特性选写法

任务特性	推荐写法
多种方案都行	文字指南（保留 AI 自由发挥空间）
有偏好但可灵活变通	伪代码 / 模板
必须严格一致（如 commit 格式）	具体规则 / 精确示例

核心放主文件，细节放子文件

## 完整 API 参数说明
详见 [reference.md](reference.md)

用例子比用文字描述有效得多

对于输出格式类 Skill，"好的 vs 坏的"比大段描述更直接：

✅ `search()` --- 正确
❌ `doSearch()` / `handleSearch()` --- 别这么写

---

7. 还有哪些能用上的场景

这些场景日常容易忽视，但用 Skills 来处理效果很好：

Code Review 自动化

把团队的 CR checklist 写成 Skill，AI 审代码时自动对照：

## Review 必查项
- [ ] 没有硬编码的魔法数字
- [ ] 错误边界处理完整
- [ ] 组件命名符合 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「怎么做这件事」的操作手册
Rules	告诉 AI「所有事都要遵守的规矩」
MCP	给 AI「用外部工具的能力」

Skills 真正的价值在于把团队的隐性知识显性化。那些"大家都懂但 AI 不知道"的规范、模式、约定，通过 Skills 沉淀下来，AI 才能真正融入团队，而不只是个通用代码生成器。