Skill 是一份给 Agent 看的操作手册：用 Markdown 把「什么时候用、按什么步骤做、产出长什么样」写清楚，让 Agent 在特定场景下自动按你的团队习惯干活，而不是每次临时猜。

---

一、Skill 是什么

简单说：Skill = 可复用的任务说明书。

适合做成 Skill 的事情通常是：

• 有固定流程（发版、查库、写接口文档）
• 有团队规范（Code Review、Commit 格式）
• Agent 本身不懂的领域知识（内部 API、编码约定、校验脚本）

不适合做成 Skill 的：一次性问答、通用编程常识、随时会变的临时决策。

---

二、放在哪里

类型	路径	适用场景
个人 Skill	~/.cursor/skills/技能名/	你自己跨项目通用
项目 Skill	.cursor/skills/技能名/	跟仓库一起共享给同事

目录结构一般是：

my-skill/
├── SKILL.md          # 必填：主说明
├── reference.md      # 可选：详细参考
├── examples.md       # 可选：示例
└── scripts/          # 可选：辅助脚本
    └── validate.py

注意：不要往 ~/.cursor/skills-cursor/ 里写东西，那是 Cursor 内置 Skill 的目录。

---

三、SKILL.md 怎么写

每个 Skill 必须有一个 SKILL.md，开头是 YAML frontmatter，后面是正文：

---
name: my-skill-name
description: 做什么，以及什么时候该用。Use when ...
---

# 技能标题

## Instructions
给 Agent 的逐步说明。

## Examples
具体输入/输出例子。

必填字段

字段	要求	作用
name	最多 64 字符，小写字母/数字/连字符	唯一标识
description	最多 1024 字符，不能为空	决定 Agent 会不会自动选用这个 Skill

可选：disable-model-invocation: true —— 默认建议加上，表示「只有用户点名时才加载」；只有希望 Agent 根据上下文自动触发时，才去掉它。

---

四、最关键的一行：description

Agent 主要靠 description 判断「要不要读这个 Skill」。写不好，Skill 等于不存在。

写法原则：

1. 用第三人称（会注入系统提示，不要写「我可以帮你…」）
2. 同时写清 WHAT（做什么） 和 WHEN（何时触发）
3. 带上用户可能说的关键词

好例子：

description: 按团队规范做 Code Review，检查正确性、安全与可维护性。Use when reviewing PRs, code changes, or when the user asks for a code review.

坏例子：

description: 帮助处理文档

---

五、正文怎么写才有效

1. 假设 Agent 已经很聪明

只写它不知道的东西：内部约定、固定模板、必须跑的命令、禁止事项。不要科普「什么是 PDF」。

2. 主文件控制在约 500 行以内

细节放到 reference.md / examples.md，在 SKILL.md 里用链接引用。引用只深一层，别套娃。

3. 自由度要匹配任务脆弱度

自由度	适用	例子
高（文字原则）	多种做法都行	Code Review 原则
中（模板/伪代码）	有偏好但仍可微调	报告结构
低（固定脚本）	必须一致、容易错	数据库迁移、校验

4. 常用写法模式

• 模板型：规定输出结构
• 示例型：给 Input → Output
• 工作流型：分步 checklist
• 分支型：先判断场景再走不同流程
• 校验环：改完 → 跑脚本 → 失败就修 → 通过再继续

5. 脚本什么时候加

能写成稳定脚本的，就放进 scripts/：比让 Agent 每次现写代码更可靠，也更省 token。写清楚是「执行」还是「只当参考读」。

---

六、推荐开发流程

Phase 1：想清楚

1. 这个 Skill 解决什么具体问题？
2. 个人用还是项目用？
3. 用户说什么话时应该触发？
4. Agent 缺什么领域知识？
5. 有没有必须遵守的输出格式 / 现成范例？

Phase 2：设计

1. 起名：processing-pdfs 这种，别叫 helper / utils
2. 写好 description（含触发词）
3. 列大纲：步骤、模板、是否需要脚本

Phase 3：实现

1. 建目录
2. 写 SKILL.md
3. 按需补 reference / examples / scripts

Phase 4：自检

• description 有 WHAT + WHEN，第三人称
• SKILL.md 不太长，术语统一
• 链接只深一层，没有过期时间表述
• 真正对话里试一次：能不能被发现、步骤能不能跟下来

---

七、一个完整小例子

code-review/
├── SKILL.md
├── STANDARDS.md
└── examples.md

---
name: code-review
description: Review code for quality, security, and maintainability following team standards. Use when reviewing pull requests, examining code changes, or when the user asks for a code review.
---

# Code Review

## Quick Start

1. 检查正确性与边界情况
2. 检查安全问题
3. 评估可读性与可维护性
4. 确认测试是否够用

## Feedback 格式

- Critical：合并前必须改
- Suggestion：建议改进
- Nice to have：可选

## Additional Resources

- 详细规范见 [STANDARDS.md](STANDARDS.md)
- 示例见 [examples.md](examples.md)

---

八、常见踩坑

1. description 太虚 → Agent 发现不了
2. 写太长 → 抢上下文，反而干扰
3. 一次给太多可选方案 → 写一个默认路径 + 一个例外即可
4. 路径写成 Windows 反斜杠 → 统一用 scripts/foo.py
5. 把时间写死在正文里 → 容易过期；旧方案放到「旧模式」小节里

---

九、一句话总结

写 Skill 的本质不是写文档给人读，而是写一份短、准、可执行的 Agent 指令：description 负责「被发现」，正文负责「做对」，细节和脚本负责「做稳」。