什么是 Skill
Claude Skill 本质是一个文件夹，里面唯一必需的文件是 SKILL.md。文件开头是几行 YAML 元数据（名称和描述），后面是 markdown 正文的指令集。
Anthropic 自己的定义最到位：Skill 是给新员工的入职引导。Claude 会思考，但它猜不到你们的流程知识和隐性规则：你们怎么写 PRD，哪些指标在报告里默认省略。
Skill 规模变大时，可以在 SKILL.md 同级添加文件夹：
scripts/— Claude 可执行的代码references/— Claude 按需读取的参考文档，如数据 schema 或风格指南assets/— 最终输出会用到文件，如幻灯片模板或品牌字体
正文里通过文件名引用这些资源，Claude 在需要时才打开。按需加载是这个架构的核心——它决定了 Claude 能否在没人提醒的情况下自己想起这个技能。
渐进式披露：Skill 的 Scale 方式
Claude 不会一上来就读完整个 Skill。它分层加载，分三层：
- 启动时：Claude 只加载每个已安装 Skill 的名称和描述，约消耗 100 tokens。这是它判断"要不要用这个技能"的全部信息。
- 请求匹配时：Claude 读取完整
SKILL.md正文，Anthropic 建议保持在 5000 tokens 以内。 - 按需读取：正文引用了哪个 reference 文件或脚本，Claude 才打开那一层；脚本执行时只返回输出结果，源码从不进入对话。
实际影响是：你可以往 Skill 里塞海量参考资料，几乎不付出额外成本。一个有十几个 reference 文件的 Skill，每次任务只加载它真正需要的那个。其余的躺在磁盘上，零消耗。
这也解释了为什么 description 字段权重极高——而这恰恰是大多数 Skill 的败因。
为什么大多数 Skill 悄悄失败
失败一：描述模糊，技能永远不被触发
一个表现完美的 Skill，如果根本不被调用，价值为零。根源几乎总是描述写得太泛。
Anthropic 的要求很直接：
- 用第三人称写
- 说清楚技能做什么
- 说清楚触发条件
"Processes Excel files and generates reports" 优于 "Helps with documents"。后者无法让 Claude 在一百个技能中把它挑出来。
失败二：Skill 触发，但输出在实际使用中出错
典型场景：一个"PRD 评审"技能在你构建时用的示例上表现完美，上线后却漏掉了真正重要的问题，或者发明了一些不存在的缺陷。
这种问题靠读 Skill 是发现不了的，只有跑才能发现。几乎没人做这一步。
写好 Skill 的几条实用原则
保持正文简短。 Anthropic 的经验值是 500 行以内。上下文窗口是共享资源，Skill 里每多一句话，都在和对话本身竞争 Claude 的注意力。如果某段文字说的是 Claude 本身就知道的事，删掉——它在消耗成本但不产生回报。
任务越脆弱，指令越要精确。 开放任务（如代码评审）给宽泛方向让它自己找路；脆弱任务（如数据库迁移）一步错全盘皆输，给出精确命令并要求不偏离。这和"机器人走路径"的比喻一致：开阔草地给宽松指令，两侧悬崖的窄桥给护栏。
Reference 文件只引一层。 如果 SKILL.md 指向 forms.md，forms.md 又指向 details.md，Claude 会倾向于略读而非精读，信息实际传不过去。所有引用直接从主文件出发。超过 100 行的 reference 文件，在顶部加目录让 Claude 看清全貌，即使它只读一部分。
脚本要挣得自己的位置。 Anthropic 的原则是"解决，别踢皮球"：脚本要自己处理错误，不能失败后让 Claude 即兴发挥。所有配置值要有文档，不能出现没人能解释的神秘常量。对于高风险操作（如批量更新或破坏性变更），使用"计划—校验—执行"模式：先让 Claude 把计划写到文件里，跑一个检查脚本，校验通过才真正执行。
被大多数人跳过的一步：测试 Skill
Anthropic 自己的文档写得很清楚，但几乎没有任何教程跟进：先写评估，再写 Skill。
具体做法：
- 在没有 Skill 的情况下让 Claude 完成几个典型任务，记录它哪里做得不够
- 把这些差距转化为若干测试场景，定义清楚"好的回答长什么样"
- 建立基线（无 Skill 时的表现）
- 写最小必要指令来通过测试，迭代优化
以 PRD 评审 Skill 为例：收集三份你亲自审过的 PRD，列出好评审应该发现的问题，用 Skill 跑一遍。如果漏掉了你标出的两个问题，就知道该修什么——而且这是在 Skill 真正服务团队之前就知道了。
好消息是，3 月 Anthropic 更新了 skill-creator，可以自动跑这个循环：
- Executor：用你的测试 prompt 执行 Skill
- Grader：按你定义的标准评分输出
- Comparator：盲测两个版本或"有 Skill vs 无 Skill"，排除"感觉变好了"的幻觉
如果你想评审现有 Skill 而非重建，Anthropics/claude-code 里的 skill-reviewer agent 可以审计已有 Skill 并直接指出修复点。它还有 benchmark 模式跟踪通过率、耗时和 token 消耗，方便在新模型发布后验证 Skill 是否依然有效。
所有这些都跑在 Anthropic 的桌面应用 Cowork 里，不只是 Claude Code 和 claude.ai。
常见坑
- 描述模糊：永远不触发。修复：写出具体任务和用户真实会说的触发词。
- 贪多求全：一个叫"数据"的 Skill 做了五件不相关的事，触发不可预测。Skill 要窄。
- 正文塞满 Claude 本就知道的东西：删。
- 给五个选项让 Claude 选：它需要一个默认项，例外情况给逃生通道。
- Windows 反斜杠路径：不同机器上会炸。用正斜杠。
- 把时间敏感指令写死在正文里（如"八月前用旧 API"）：它们会腐坏。放到标注了日期的"旧模式"区域。
安全值得专门提一句。 SKILL.md 是纯文本，Claude 把它当指令执行，这让它成为隐藏攻击的天然载体。恶意 Skill 可以静默指示 Claude 把你的 API key 附加到某个 URL 上请求出去，常规代码扫描器因为 payload 是散文而非代码而检测不到。安装 Skill 要像安装软件一样谨慎：不信任的来源不装，不读的 Skill 不用。如果用了别人写的 Skill，claudelint 扫结构和危险命令，skill-lint 扫注入和凭证泄露——这些应该成为你工作流的一部分。
为什么现在值得学
去年 12 月，Anthropic 将 Skill 格式发布为开放标准，主要编程工具均已采纳——你今天写的 Skill 跑在 Codex、Cursor、GitHub 和 VS Code 上都能工作。在这个标准上投入学习的收益，不随底层工具迭代而折旧。
原文：How to Create Claude Skills That Work: A Field Guide for Product Managers by @nurijanian