Anthropic 官方公开了他们内部使用 Claude Code 时积累的 Skill 编写经验。这些经验对任何使用 AI 编程助手的人都适用——无论你用的是 Claude Code、Codex 还是 Cursor，核心逻辑是通用的。

这篇文章把这些经验提炼成 7 条可以直接照做的操作清单，帮你避开"写了Skill但不好用"的常见坑。

核心认知：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是目录，不是全文

官方建议的目录结构：

SKILL.md        -- 核心流程，越短越好
references/     -- 细节文档，需要时才读
assets/         -- 模板、示例文件
scripts/        -- 可执行脚本

为什么？因为 SKILL.md 触发时会整个塞进上下文。上下文里的废话不是免费的，它会让模型在真正关键的指令上"分神"。

自检标准： 打开你的 SKILL.md，问每一段"是不是每次执行都用得上？"不是，就挪出去，放到 references/ 目录下，在主文件里写一句"处理 X 情况时，读 references/x.md"。

第三条：description要埋"人话"

Skill 的 description 决定它会不会被触发。关键是面向模型写，埋"用户实际会说的话"。

用户说"帮我看看这周报"，如果 description 只写"分析员工汇报文档"，匹配度就弱；写上"看周报""读日报""挤水分"这些原话，命中率立刻上去。

另外，description 还要写清什么时候不要触发。Skill 多了之后，互相误触发会成为新问题。加一句"仅当 X 时使用，Y 情况请用另一个 Skill"，比事后纠正省事。

第四条：区分硬约束和默认偏好

新手最常犯的错：把 Skill 写成步骤 1-2-3-4-5 的硬流程。结果遇到一点变化，整个流程就僵住。

正确写法是区分两类内容：

• 硬约束（必须照做）：输出格式、品牌禁忌、安全红线。明确写"必须""不要"。
• 默认偏好（可被情况推翻）：写成"默认 X，如果遇到 Y 情况可以 Z"。

坏的写法："第三步：给视频加进度条" 好的写法："视频需要章节进度条，除非素材短于 1 分钟"

前者描述动作，后者描述意图和边界。模型拿到意图才能应变。

第五条：确定的事给代码，判断的事给模型

AI 每次现写代码，结果有随机性；脚本每次执行，结果完全一致。

一个任务里，凡是"每次都一样的部分"——调 API、转格式、上传文件——应该固化成 scripts/ 里的脚本，让模型只负责"调用脚本 + 处理判断类工作"。

自检方法： 回看 Skill 的执行记录，凡是 AI 每次都写出几乎相同代码的地方，就是该沉淀成脚本的地方。脚本化的环节越多，跑得越快、越便宜、越稳。

第六条：给Skill装记忆

做法很简单：Skill 文件夹里放一个 JSON 或日志文件，每次执行后写入本次的关键信息，下次执行先读它。

没有记忆，每次执行都是"第一次"。有了记忆，Skill 会越用越懂你。

最适合的场景：

• 需要跨周期对比的（如读周报的 Skill，记录本周关键数据和异常，下次自动对比）
• 需要去重的（如选题 Skill，记录已经做过的选题，避免重复）

第七条：按使用频率分配迭代精力

Skill 攒到二十多个之后，真实情况一定是：3-5 个高频使用，一半几乎不碰。

• 高频的：值得做全套升级——坑清单、记忆、脚本化
• 低频但触发过的：保持几行字的最简形态，别投入
• 从没触发的：要么 description 不像你说话的方式（改触发词），要么本来就是伪需求（删掉）

把升级精力全砸在高频 Skill 上，这是性价比最高的路径。

总结：一张操作清单

参考来源： Anthropic 官方博客 Lessons from Building Claude Code: How We Use Skills