# Skill 撰写原则（吸收 Anthropic 实践）

> 来源：Thariq Shihipar 分享的 Anthropic 内部 Skills 方法论。本文档供维护 `.cursor/skills/` 时参考。

## 1. 写 Claude 不知道的东西

Claude 对编程已很熟，有默认偏好。好的 Skill 应聚焦**能把 Claude 推出惯性思维**的信息：

- 团队独特规范（如 Soul 三端路由隔离、Toast 禁 alert）
- 行业或项目不成文惯例
- 过去踩过的坑、边界条件
- 与通用实践不同的决策（如为什么用 key 而非 appId）

**避免**：大段重复 Claude 已掌握的通用知识。

## 2. Gotchas 是 Skill 的灵魂

任何 Skill 里**信息密度最高**的就是踩坑清单。应从实际失败中积累，随使用不断更新。

- 格式：陷阱 → 后果 → 正确做法
- 信号强于「怎么做对」：告诉 AI「千万别这么做」更有效
- 每次 Claude 踩新坑，就往对应 Skill 的 Gotchas 表追加一行

## 3. 给指令留灵活空间

Skill 高度可复用，写得太死会令 AI 在稍不同情况下手足无措。

- 给**方向与原则**，而非死板步骤
- 提供必要信息，同时留出根据实际情况灵活应变的余地
- 检查清单、必守规则是好的；过度细化的「第一步第二步第三步」可酌情简化

## 4. 让 Skill 拥有记忆

通过内部存储实现记忆：

- 追加式日志（如 `sync-log.md`）：记录每次执行摘要，下次可对比增量
- 进化池（evolution）：经验按日期沉淀，形成团队知识库
- 理想：Skill 不只干活，还能「记得上次干了什么」

## 5. 给现成的代码与模板

AI 擅长组合与决策，不擅长记公司特有细节。最高效协作方式：

- 提供脚本（如 db-exec、一键-添加经验.bat）
- 提供模板（evolution 模板、会议纪要模板）
- 把精力留给 AI 做组合和决策，而不是从零写样板

## 6. Skill 是文件夹，不是单文件

一个 Skill 可包含：

- `SKILL.md`：入口，行为与触发条件
- `scripts/`：可执行脚本
- `references/`：参考文档、路径速查
- `assets/`：模板、配置
- 日志文件：记忆

## 7. 从简单开始，持续迭代

大多数 Skill 一开始只有几行文字加一条踩坑提醒。随 Claude 遇到新边界情况，再一点一点完善。不追求一步到位。