Skill 是一个文件夹，可以包含 Markdown、脚本、资产、数据、配置等。Agent 会自主发现和使用其中的所有内容。

把它想成一个小型项目，而不是一份文档。

这个非常重要
如果是一个很小的skill,用文件也是没问题的,但是俺公司有一个2000字的文档,ai根本读不到…而且拓展性极差

skills/<name>/ ├── SKILL.md # 入口：路由表 + 优先级 ├── rules/ # 长期约束 ├── workflows/ # 步骤流程 ├── references/ # 背景资料：架构、坑点、索引 │ └── gotchas.md # 已知的坑（通常是最高价值内容） ├── docs/ # 可选：提示词、报告 └── scripts/ # 可选：辅助脚本、脚手架工具

Skill 文件夹能放什么

image1438×544 39.8 KB

来自 Anthropic 的关键洞察： 让 Agent 花时间在组合和编排上，而非从头写样板代码。Skill 文件夹中的脚本和可复用资产能显著降低 Agent 的出错率。

image1404×392 24.5 KB

小项目从最小模板开始，当单文件开始膨胀、出现重复或需要主动维护时，再升级到完整目录结构。

image1412×330 37.3 KB

混在一起会怎样？在 300 行约束中翻找检查清单，或者一个"规则"文件里藏着流程步骤。Agent 浪费 token 读无关内容，维护也变成噩梦。

边缘情况分类

有些内容既是解释性的又容易违反（如"输入验证的坑"），按形式决定：

• “你必须做 X”（指令性的）→ Rule
• “小心 X”（警告性的）→ Reference（references/gotchas.md）
• 第 1 步、第 2 步、第 3 步（流程性的）→ Workflow

文件大小参考值

image858×380 20.9 KB

非常重要
这个也是很重要的一个事情,一个良好的skill,如果单个文件太大,不可避免会导致agent无法读到正确的内容,那么在一定情况下自动拆或者合并规则文件是必须的,但是也不是一定要触发,如果大于标准但是都是同一个模块的,那么也不应该拆分

行数是信号，不是命令。超标触发评估，不是自动拆分。

SKILL.md 应该很短（<= 100 行），只负责告诉 Agent 读什么、什么时候读。

一个skill里面的文件最重要的是什么呢?

name?version?description?还是下面的内容?,我相信答案一定是description

4.1 Description = 触发条件

description 字段是 Agent 决定"要不要激活这个 Skill"的依据。它不是摘要，是触发条件。

# 错误 — Agent 无法匹配 description: API development helper # 正确 — 明确触发短语 + 激活条件 description: > This skill should be used when the user asks to "add a new API endpoint", "write controller logic", "fix a backend bug", or "add a database migration". Activate when the task involves REST routes, request validation, service layer logic, or MyBatis mapper changes.

质量检查：

image890×330 15.8 KB

一个 Description 写不好的 Skill，等同于不存在。

4.2 两层路由：Always Read + Common Tasks

第一层 — Always Read（每次任务都读，2-3 个文件）：

## Always Read 1. `rules/project-rules.md` 2. `rules/coding-standards.md`

第二层 — Common Tasks（按任务类型路由到不同文件）：

## Common Tasks - Add Controller → read `rules/backend-rules.md` + follow `workflows/add-controller.md` - Fix bug → read task-relevant `rules/*.md` + follow `workflows/fix-bug.md`; ref: `references/gotchas.md` - **Other / unlisted task** → proceed with Always Read; check `workflows/` for closest match

规则：

• Agent 只读当前任务需要的文件，不多读
• 每个条目必须列出精确路径，不能只写"follow the workflow"
• Common Tasks 控制在 8-10 条以内；超出时按领域分组
• 必须包含 “Other / unlisted task” 兜底条目

4.3 Known Gotchas

在 SKILL.md 中暴露最关键的坑点摘要，链接到详细内容：

## Known Gotchas - Filter 必须在 app init 之前注册，否则首次渲染空白 → see `references/gotchas.md#filter-registration`

坑点是整个 Skill 中价值密度最高的内容。

为什么需要内联路由表

Agent 在长对话中会压缩历史上下文。“Scan skills/*/SKILL.md” 这样的自然语言指令会在压缩后丢失。内联路由表直接嵌入在入口文件中，压缩后仍存活。

各工具入口

image1378×328 25.2 KB

关键： 如果正式 Skill 在 skills/<name>/ 但没有 .cursor/skills/<name>/SKILL.md，Cursor 永远发现不了它。

薄壳模板

所有薄壳共享同一个核心结构（<= 15 行）：

Formal docs live under `skills/`. Read `skills/*/SKILL.md`. ## Quick Routing (survives context truncation) | Task | Required reads | Workflow | |------|---------------|----------| | Fix bug | `rules/project-rules.md` + `rules/coding-standards.md` | `workflows/fix-bug.md` | | Add feature X | `rules/<domain>-rules.md` | `workflows/<task>.md` | | Other | `rules/project-rules.md` | Check `workflows/` for closest match | ## Auto-Triggers - Before declaring any non-trivial task complete → run Task Closure Protocol

Auto-Triggers

薄壳不只做路由，还编码事件→动作映射。最重要的一条是 Task Closure Protocol 的触发。

核心机制：不再把 AAR 当作可选的附加步骤，而是定义为任务完成的一部分。

协议定义

一个任务在以下条件全部满足前不算完成： 1. 主体工作完成并验证 2. 30 秒 AAR 扫描（4 个问题——全部 "否" 则到此结束） 3. 如果任何一个 "是" → 通过录入标准 → 通过则记录 任何 workflow 不得在跳过第 2 步的情况下声明完成。

AAR 的 4 个问题

- [ ] 新模式？ — 用了未记录的模式或约定吗？ - [ ] 新陷阱？ — 遇到了不提前知道就会浪费大量时间的问题吗？ - [ ] 缺失规则？ — 因为缺少某条规则导致走了弯路吗？ - [ ] 过时规则？ — 发现现有规则已经不准确或不再适用吗？

为什么要降低触发门槛

之前：“After behavior-changing bug fix → run AAR”——Agent 倾向于把自己的改动归类为不算，从而跳过复盘。

现在：“Before declaring any non-trivial task complete → run Task Closure Protocol”。判断门槛从"行为变化"降低到"非琐碎"，后者更容易正确判断。

跳过条件明确且窄：仅格式化、仅注释、仅依赖版本变更、无新教训的行为保持性重构。

一个好的skill,应该会记录需要的信息并且记录下来
这个模块决定了一个skill是否有了自动进化的能力

7.1 Recording Threshold（2/3 录入标准）

不是所有发现都值得记录。录入前通过阈值过滤：

至少 2/3 通过才录入。

通过阈值的典型内容

• 框架生命周期坑（注册时序、挂载/卸载陷阱）
• 隐藏的路由依赖（注册顺序有影响）
• 非显而易见的同步或状态重置要求
• 跨层交互陷阱（对话框 + Tab + 嵌套服务）

不通过的典型内容

• 一次性变通方案（只和当前 bug 相关）
• 看代码就能明白的事情
• 轻微的风格偏好
• 官方文档已充分覆盖的内容

实战示例

Agent 完成任务：添加了一个新页面，用到 Recoil atom + 自定义 filter。 发现 1：Atom 命名约定（xxxAtom） 可重复？ 是 → 通过 代价高？ 否（命名不一致不会导致错误）→ 不通过 代码不可见？ 否（现有 atom 已经清晰展示了模式）→ 不通过 结果：1/3 → 不录入 发现 2：Filter 必须在 app init 之前注册 可重复？ 是 → 通过 代价高？ 是（首次渲染空白，30+ 分钟调试）→ 通过 代码不可见？ 是（时序依赖从代码中看不出来）→ 通过 结果：3/3 → 录入

7.2 Generalization Rule（泛化规则）

记录的内容必须脱离当前项目上下文也能看懂。

好坏对比

改写公式

具体发现 → 抽象为通用 pattern → 说明不遵守的后果

7.3 录入位置

录入格式选最轻的： 一句话 bullet → 一小段加到现有文件 → 新文件（通常不需要）。

7.4 激活优于存储

一个陷阱仅记录在 references/ 中是不够的。高代价陷阱必须同时：

• 存储在正确的文件中
• 激活在会触发它的任务路径上（workflow 检查项、SKILL.md 路由、或 rules 摘要）

Learn from Mistakes

Agent 犯错并被纠正后：

1. 先搜索 — 确认规则是否已存在
2. 分类根因：
   • 规则缺失 → 通过录入标准后新增
   • 规则过时 → 直接更新（无需门槛）
   • 规则废弃 → 走清退流程
   • 规则未被遵循 → 检查醒目度

Rule Deprecation

规则只增不减会导致文档膨胀。清退条件：

• 相关技术已移除 → 直接删除
• 正在迁移中 → 加作用域标注
• 不确定 → 加 <!-- DEPRECATED: reason, date --> 注释

评估式拆分

文件超标时回答三个问题：

1. 话题可分离？
2. 导航困难？
3. 拆后各部分能独立存在？

三个都 Yes → 拆。任何一个 No → 不拆。

评估式合并

碎片文件过多时：

1. 话题相关？
2. 合并后更好找？
3. 合并后不超标？

三个都 Yes → 合并。

不要陈述显而易见的事情

聚焦于项目特有的约定、与主流做法不同的地方、Agent 默认行为会出错的场景。通用编程知识不需要写进 Skill。

避免过度指令化

提供约束和上下文，不要把每一步都写死。

# 坏 — 过度指令化 添加按钮时使用 Tailwind class "bg-blue-500 hover:bg-blue-700..." # 好 — 约束 + 上下文 按钮使用项目的设计系统 token（见 `rules/frontend-rules.md`）。 交互元素必须有可见的 hover/focus 状态。

利用脚本和代码库

在 Skill 中提供辅助脚本。Agent 调用脚本比从头写样板代码可靠得多。

测试和迭代 Skill

Skill 也是代码，需要测试和迭代：

1. 写 Skill —— 触发条件和路由
2. 测试激活 —— Agent 在正确任务时能触发吗？
3. 测试路由 —— 每种任务类型读对了文件吗？
4. 观察失败 —— Agent 在哪里仍然出错？
5. 通过 AAR 更新 —— 用 Task Closure Protocol 改进 Skill

保持 Skill 聚焦

一个想做所有事的 Skill 什么都做不好。需要拆分的信号：

• Description 列了 10+ 个来自不同领域的触发短语
• Common Tasks 有 15+ 条覆盖不相关的工作
• Agent 经常为只涉及一个子领域的任务激活整个 Skill