更新多个技能文档，新增常见陷阱（Gotchas）部分，提供开发过程中需避免的错误及其解决方案，提升开发团队的规范性和效率。同时，更新描述以更清晰地指引使用场景，确保文档内容的准确性和实用性。

.cursor/docs/skill-writing-principles.md

@@ -0,0 +1,60 @@
+# 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 遇到新边界情况，再一点一点完善。不追求一步到位。