jnMetaCode/superpowers-zh / skills/writing-skills
writing-skills
Verified当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
编写技能
概述
编写技能就是将测试驱动开发应用于流程文档。
个人技能存放在你所用运行环境的技能目录中(Claude Code 上是 ~/.claude/skills/)——其他运行环境的路径见 codex-tools.md 或 gemini-tools.md。Codex、Copilot CLI 和 Gemini CLI 也都认 ~/.agents/skills/,作为跨运行环境的别名。
你编写测试用例(带子智能体的压力场景),观察它们失败(基线行为),编写技能(文档),观察测试通过(智能体遵守规则),然后重构(堵住漏洞)。
核心原则: 如果你没有观察到智能体在没有该技能时失败,你就不知道这个技能是否教了正确的东西。
必需背景: 在使用此技能前,你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。
官方指南: Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。
什么是技能?
技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。
技能是: 可复用的技术、模式、工具、参考指南
技能不是: 关于你某次如何解决问题的叙事
TDD 映射到技能
| TDD 概念 | 技能创建 |
|---|---|
| 测试用例 | 带子智能体的压力场景 |
| 生产代码 | 技能文档(SKILL.md) |
| 测试失败(红) | 智能体在没有技能时违反规则(基线) |
| 测试通过(绿) | 智能体在有技能时遵守规则 |
| 重构 | 在保持合规的同时堵住漏洞 |
| 先写测试 | 在编写技能之前先运行基线场景 |
| 观察失败 | 记录智能体使用的确切合理化借口 |
| 最小代码 | 编写针对那些具体违规行为的技能 |
| 观察通过 | 验证智能体现在遵守规则 |
| 重构循环 | 发现新的合理化借口 → 堵住 → 重新验证 |
整个技能创建过程遵循红-绿-重构。
何时创建技能
创建条件:
- 技术对你来说不是直觉上显而易见的
- 你会在不同项目中反复引用
- 模式具有广泛适用性(非项目特定)
- 其他人也会受益
不要创建:
- 一次性解决方案
- 其他地方有充分文档的标准实践
- 项目特定的约定(放在 CLAUDE.md 中)
- 机械性约束(如果可以用正则/验证强制执行,就自动化——文档留给需要判断的场景)
技能类型
技术类
有具体步骤的方法(condition-based-waiting、root-cause-tracing)
模式类
思考问题的方式(flatten-with-flags、test-invariants)
参考类
API 文档、语法指南、工具文档(office docs)
目录结构
skills/
skill-name/
SKILL.md # 主参考文档(必需)
supporting-file.* # 仅在需要时
扁平命名空间 - 所有技能在一个可搜索的命名空间中
分离文件的情况:
- 大量参考内容(100+ 行)- API 文档、全面的语法说明
- 可复用工具 - 脚本、实用程序、模板
保持内联:
- 原则和概念
- 代码模式(< 50 行)
- 其他所有内容
SKILL.md 结构
执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。
技能发现优化(SDO)
执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。
流程图使用
执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。
代码示例
一个优秀的示例胜过多个平庸的
选择最相关的语言:
- 测试技术 → TypeScript/JavaScript
- 系统调试 → Shell/Python
- 数据处理 → Python
好的示例:
- 完整可运行
- 注释良好,解释为什么
- 来自真实场景
- 清晰展示模式
- 可以直接适配(不是通用模板)
不要:
- 用 5 种以上语言实现
- 创建填空模板
- 写人为构造的示例
你擅长语言移植——一个优秀的示例就够了。
文件组织
自包含技能
defense-in-depth/
SKILL.md # 所有内容内联
适用场景:所有内容都能放下,无需大量参考
带可复用工具的技能
condition-based-waiting/
SKILL.md # 概述 + 模式
example.ts # 可适配的工作代码
适用场景:工具是可复用的代码,不只是叙述
带大量参考的技能
pptx/
SKILL.md # 概述 + 工作流
pptxgenjs.md # 600 行 API 参考
ooxml.md # 500 行 XML 结构
scripts/ # 可执行工具
适用场景:参考资料太多无法内联
在正文里调用技能自带的脚本时,要通过解释器来调用(bash scripts/tool.sh、node scripts/tool.js),绝不用裸路径:有些运行环境的插件打包器会去掉可执行位,在那里裸写 scripts/tool.sh 会以 Permission denied 失败。
铁律(与 TDD 相同)
没有失败的测试就不写技能
这适用于新技能和对现有技能的编辑。
先写技能再测试?删掉它。重新开始。 编辑技能不测试?同样违规。
无例外:
- 不适用于"简单的添加"
- 不适用于"只是加一个章节"
- 不适用于"文档更新"
- 不要保留未测试的更改作为"参考"
- 不要在运行测试时"调整"
- 删除就是删除
必需背景: test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。
测试所有技能类型
不同类型的技能需要不同的测试方法:
纪律执行类技能(规则/要求)
例如: TDD、完成前验证、编码前设计
测试方式:
- 学术性问题:它们理解规则吗?
- 压力场景:它们在压力下遵守吗?
- 多重压力组合:时间 + 沉没成本 + 疲惫
- 识别合理化借口并添加明确的反驳
成功标准: 智能体在最大压力下遵循规则
技术类技能(操作指南)
例如: condition-based-waiting、root-cause-tracing、defensive-programming
测试方式:
- 应用场景:它们能正确应用技术吗?
- 变体场景:它们能处理边界情况吗?
- 缺失信息测试:说明是否有遗漏?
成功标准: 智能体成功将技术应用于新场景
模式类技能(心智模型)
例如: reducing-complexity、information-hiding 概念
测试方式:
- 识别场景:它们能识别模式何时适用吗?
- 应用场景:它们能使用心智模型吗?
- 反例:它们知道何时不应用吗?
成功标准: 智能体正确识别何时/如何应用模式
参考类技能(文档/API)
例如: API 文档、命令参考、库指南
测试方式:
- 检索场景:它们能找到正确的信息吗?
- 应用场景:它们能正确使用找到的内容吗?
- 覆盖测试:常见用例是否都涵盖了?
成功标准: 智能体找到并正确应用参考信息
跳过测试的常见合理化借口
| 借口 | 现实 |
|---|---|
| "技能显然很清晰" | 对你清晰 ≠ 对其他智能体清晰。测试它。 |
| "这只是参考资料" | 参考资料可能有遗漏、不清楚的地方。测试检索。 |
| "测试太过了" | 未测试的技能总有问题。15 分钟测试省下数小时。 |
| "有问题再测试" | 问题 = 智能体无法使用技能。在部署前测试。 |
| "测试太繁琐" | 测试比在生产中调试坏技能少繁琐得多。 |
| "我有信心它很好" | 过度自信保证出问题。无论如何都要测试。 |
| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测试" | 部署未测试的技能比后面修复浪费更多时间。 |
以上所有都意味着:部署前测试。无例外。
让形式匹配失败类型
在写指导内容之前,先给基线失败归类。能让某一类失败变得无懈可击的形式,用在另一类上会可测量地反噬。
| 基线失败 | 正确的形式 | 错误的形式 |
|---|---|---|
| 压力之下跳过/违反规则(明知故犯) | 禁令 + 合理化借口表 + 红线(见下方"让技能经受住合理化的考验") | 软性建议("优先……"、"考虑……") |
| 遵守了,但产出的形状不对(提示词臃肿、结论被埋、复述规格) | 正面配方或契约:直接说明产出是什么 —— 它由哪些部分组成、按什么顺序 | 禁令清单("不要复述"、"绝不旁白") |
| 在他们本来就会产出的东西里漏掉了必需元素 | 结构性手段:在他们要填的模板里放一个 REQUIRED 字段或占位槽 | 在模板附近写散文式提醒 |
| 行为应当取决于某个条件 | 挂在可观察谓词上的条件句("如果简报存在,就引用它") | 无条件规则 + 一堆例外条款 |
为什么禁令在"塑形"类问题上会反噬: 在存在竞争性激励时(比如"让提示词自包含"),智能体会跟"不要 X"讨价还价。在针对分派提示词指导做的同题措辞对照测试里,禁令组产出的不想要的内容明显多于配方组(两组分布完全分离),甚至比"完全不给指导"的对照组还差 —— 请对你自己的场景做微型测试,别想当然,但永远不要把禁令当默认选择。配方留不下可讨价还价的空间:产出要么符合所说的形状,要么不符合。
无论你选哪种形式,都适用的规则:
- 不要加"视情况"从句。 "不要 X,除非它很重要"会重新打开谈判 —— 在同一批措辞测试里,给一个胜出的配方追加一条"视情况"从句,就把它从稳定退化成了飘忽。真正的例外要表达成它自己的条件句,挂在可观察的谓词上。
- 豁免条款不会限定作用域。 "这条长度限制不适用于代码块",照样会压制代码块。如果产出里有一部分必须豁免,就重构结构让规则碰不到它,而不是写豁免。
让技能经受住合理化的考验
执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。
技能的红-绿-重构
遵循 TDD 循环:
红:编写失败的测试(基线)
在没有技能的情况下运行压力场景。逐字记录行为:
- 它们做了什么选择?
- 它们使用了什么合理化借口(原文)?
- 哪些压力触发了违规?
这就是"观察测试失败"——在编写技能之前你必须看到智能体自然会怎么做。
绿:编写最小技能
编写针对那些具体合理化借口的技能。不要为假设情况添加额外内容。
用技能运行相同的场景。智能体应该现在遵守。
重构:堵住漏洞
智能体找到了新的合理化借口?添加明确的反驳。重新测试直到无懈可击。
先做措辞微型测试,再跑完整场景
完整的压力场景是最后一道关卡,但它每轮迭代都又慢又贵。先用微型测试验证措辞本身:
- 每次调用一个全新上下文的样本 —— 一次裸 API 调用,或者没有 API 权限时用一个单发子智能体。system prompt 放这条指导实际会存在的真实上下文(完整的 skill 或提示词模板,不是把指导单独拎出来);user message 放一个会诱发该失败的任务。
- 永远带一个"不给指导"的对照组。 如果对照组根本没表现出那个失败,那就没什么可修的 —— 停下,别写这条指导。
- 每个变体至少 5 次重复。 单个样本会骗人。
- 每一条被标记的命中都要人工读一遍。 想用程序打分可以,但模板回声和被引用的反例会伪装成命中;只看自动计数会同时高估失败和成功。
- 方差本身就是一个指标。 指导真正生效时,多次重复会收敛到同一种形状。5 次重复出现 5 种不同解读,说明这个措辞没有约束力 —— 先收紧形式,别急着加字。
微型测试验证的是措辞;对纪律执行类技能,它不能替代压力场景。
测试方法论: 参见 @testing-skills-with-subagents.md 了解完整的测试方法:
- 如何编写压力场景
- 压力类型(时间、沉没成本、权威、疲惫)
- 系统地堵住漏洞
- 元测试技巧
反模式
叙事式示例
"在 2025-10-03 的会话中,我们发现空的 projectDir 导致了……" 为什么不好: 太具体,不可复用
多语言稀释
example-js.js、example-py.py、example-go.go 为什么不好: 质量平庸,维护负担重
流程图中的代码
step1 [label="import fs"];
step2 [label="read file"];
为什么不好: 无法复制粘贴,难以阅读
通用标签
helper1、helper2、step3、pattern4 为什么不好: 标签应有语义意义
停下:进入下一个技能之前
编写任何技能后,你必须停下来完成部署流程。
不要:
- 批量创建多个技能而不逐个测试
- 在当前技能验证前就进入下一个
- 因为"批量处理更高效"就跳过测试
下面的部署清单对每个技能都是强制性的。
部署未测试的技能 = 部署未测试的代码。这是对质量标准的违反。
技能创建清单(TDD 适配版)
重要:使用 TodoWrite 为下面的每个清单项创建待办。
红色阶段 - 编写失败的测试:
- 创建压力场景(纪律类技能需 3 个以上组合压力)
- 在没有技能的情况下运行场景 - 逐字记录基线行为
- 识别合理化借口中的模式
绿色阶段 - 编写最小技能:
- 名称只使用字母、数字、连字符(无括号/特殊字符)
- YAML frontmatter 包含必需的
name和description字段(最多 1024 字符;参见 spec) - 描述以"Use when..."开头并包含具体的触发条件/症状
- 描述用第三人称
- 全文包含搜索关键词(错误、症状、工具)
- 带有核心原则的清晰概述
- 解决红色阶段识别出的具体基线失败
- 代码内联或链接到独立文件
- 一个优秀的示例(非多语言)
- 用技能运行场景 - 验证智能体现在遵守
重构阶段 - 堵住漏洞:
- 从测试中识别新的合理化借口
- 添加明确的反驳(纪律类技能)
- 从所有测试迭代中构建合理化借口表
- 创建红线列表
- 重新测试直到无懈可击
质量检查:
- 仅在决策不明显时使用小流程图
- 快速参考表
- 常见错误章节
- 无叙事性故事
- 支持文件仅用于工具或大量参考
部署:
- 将技能提交到 git 并推送到你的 fork(如果已配置)
- 考虑通过 PR 贡献回去(如果具有广泛用途)
发现工作流
未来的 Claude 如何找到你的技能:
- 遇到问题("测试不稳定")
- 找到技能(描述匹配)
- 浏览概述(这相关吗?)
- 阅读模式(快速参考表)
- 加载示例(仅在实现时)
为此流程优化 - 把可搜索的术语放在前面和各处。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| discernment-nudgeanthropics/skillsAfter you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| internal-commsanthropics/skillsA set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.). | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |