来自Anthropic官方的Skill编写经验总结：精简上下文、积累踩坑清单、脚本化稳定环节，让你的AI协作效率翻倍。
来自Anthropic官方的Skill编写经验总结：精简上下文、积累踩坑清单、脚本化稳定环节，让你的AI协作效率翻倍。
深入解析 Coding Agent 的六大核心模块：代码仓库上下文、提示词缓存、工具调用、上下文瘦身、会话记忆和任务委派，附开源 Mini Coding Agent 实践参考。
Anthropic 官方公开了他们内部使用 Claude Code 时积累的 Skill 编写经验。这些经验对任何使用 AI 编程助手的人都适用——无论你用的是 Claude Code、Codex 还是 Cursor，核心逻辑是通用的。
这篇文章把这些经验提炼成 7 条可以直接照做的操作清单，帮你避开"写了Skill但不好用"的常见坑。
大多数人把 Skill 理解成"教 AI 做事的说明书"，这个理解会导致写出冗长、低效的 Skill。
正确的认知是：Claude 本身已经很强，Skill 不是给它"补课"，而是给它纠偏 + 减少摸索。每次 Claude 执行任务，它都在做大量决策：用什么工具、什么顺序、什么标准。没有 Skill 时，它靠通用知识猜，大部分猜对，少数猜错——而 Skill 的价值就集中在那"少数猜错"的地方。
判断标准只有一个：不写这句，Claude 会做错或做慢吗？不会，就删掉。
Anthropic 的做法是：每次 Claude 在某个任务上失败，把失败原因沉淀成一条写回 Skill。比如"这个 API 的字段叫 user_id 不是 userId"、"这个库的文档是错的，实际行为是 X"。
为什么这是核心？流程 Claude 大体能自己推导，但坑是"经验"，经验只能靠积累，不能靠推理。一个用了三个月、攒了二十条坑的 Skill，和一个刚写的"完美"Skill，前者价值高得多。
操作方法： 在每个常用 Skill 的 SKILL.md 里固定加一节"已知的坑"。每次 Skill 跑出来的结果不对、你纠正了 AI，就顺口说一句"把这个写进 Skill 的坑里"。
官方建议的目录结构：
SKILL.md -- 核心流程，越短越好
references/ -- 细节文档，需要时才读
assets/ -- 模板、示例文件
scripts/ -- 可执行脚本为什么？因为 SKILL.md 触发时会整个塞进上下文。上下文里的废话不是免费的，它会让模型在真正关键的指令上"分神"。
自检标准： 打开你的 SKILL.md，问每一段"是不是每次执行都用得上？"不是，就挪出去，放到 references/ 目录下，在主文件里写一句"处理 X 情况时，读 references/x.md"。
Skill 的 description 决定它会不会被触发。关键是面向模型写，埋"用户实际会说的话"。
用户说"帮我看看这周报"，如果 description 只写"分析员工汇报文档"，匹配度就弱；写上"看周报""读日报""挤水分"这些原话，命中率立刻上去。
另外，description 还要写清什么时候不要触发。Skill 多了之后，互相误触发会成为新问题。加一句"仅当 X 时使用，Y 情况请用另一个 Skill"，比事后纠正省事。
新手最常犯的错：把 Skill 写成步骤 1-2-3-4-5 的硬流程。结果遇到一点变化，整个流程就僵住。
正确写法是区分两类内容：
坏的写法："第三步：给视频加进度条" 好的写法："视频需要章节进度条，除非素材短于 1 分钟"
前者描述动作，后者描述意图和边界。模型拿到意图才能应变。
AI 每次现写代码，结果有随机性；脚本每次执行，结果完全一致。
一个任务里，凡是"每次都一样的部分"——调 API、转格式、上传文件——应该固化成 scripts/ 里的脚本，让模型只负责"调用脚本 + 处理判断类工作"。
自检方法： 回看 Skill 的执行记录，凡是 AI 每次都写出几乎相同代码的地方，就是该沉淀成脚本的地方。脚本化的环节越多，跑得越快、越便宜、越稳。
做法很简单：Skill 文件夹里放一个 JSON 或日志文件，每次执行后写入本次的关键信息，下次执行先读它。
没有记忆，每次执行都是"第一次"。有了记忆，Skill 会越用越懂你。
最适合的场景：
Skill 攒到二十多个之后，真实情况一定是：3-5 个高频使用，一半几乎不碰。
把升级精力全砸在高频 Skill 上，这是性价比最高的路径。
| 序号 | 操作 | 核心理由 |
|---|---|---|
| 1 | 加"已知的坑"小节，持续累积 | Skill 价值来自经验沉淀 |
| 2 | SKILL.md 瘦身，细节挪 references/ | 上下文废话稀释注意力 |
| 3 | description 加排他说明 | 防止误触发 |
| 4 | 硬约束和默认偏好分开写 | 写意图不写死步骤 |
| 5 | 重复代码固化成脚本 | 脚本零随机性 |
| 6 | 加 history.json 记忆 | 越用越懂你 |
| 7 | 按使用频率分配迭代精力 | 高频 Skill 才值得全套升级 |
参考来源： Anthropic 官方博客 Lessons from Building Claude Code: How We Use Skills