编写技能就是将测试驱动开发应用于流程文档。
\n个人技能存放在智能体特定的目录中（Claude Code 用 ~/.claude/skills，Codex 用 ~/.agents/skills/）
你编写测试用例（带子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵守规则），然后重构（堵住漏洞）。
\n核心原则： 如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。
\n必需背景： 在使用此技能前，你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。
\n官方指南： Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。
\n技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。
\n技能是： 可复用的技术、模式、工具、参考指南
\n技能不是： 关于你某次如何解决问题的叙事
\n| TDD 概念 | \n技能创建 | \n
|---|---|
| 测试用例 | \n带子智能体的压力场景 | \n
| 生产代码 | \n技能文档（SKILL.md） | \n
| 测试失败（红） | \n智能体在没有技能时违反规则（基线） | \n
| 测试通过（绿） | \n智能体在有技能时遵守规则 | \n
| 重构 | \n在保持合规的同时堵住漏洞 | \n
| 先写测试 | \n在编写技能之前先运行基线场景 | \n
| 观察失败 | \n记录智能体使用的确切合理化借口 | \n
| 最小代码 | \n编写针对那些具体违规行为的技能 | \n
| 观察通过 | \n验证智能体现在遵守规则 | \n
| 重构循环 | \n发现新的合理化借口 → 堵住 → 重新验证 | \n
整个技能创建过程遵循红-绿-重构。
\n创建条件：
\n不要创建：
\n有具体步骤的方法（condition-based-waiting、root-cause-tracing）
\n思考问题的方式（flatten-with-flags、test-invariants）
\nAPI 文档、语法指南、工具文档（office docs）
\nskills/\n skill-name/\n SKILL.md # 主参考文档（必需）\n supporting-file.* # 仅在需要时\n扁平命名空间 - 所有技能在一个可搜索的命名空间中
\n分离文件的情况：
\n保持内联：
\nFrontmatter（YAML）：
\nname 和 description（完整支持字段参见 agentskills.io/specification）name：只使用字母、数字和连字符（不要用括号、特殊字符）description：第三人称，仅描述何时使用（不是做什么）\n---\nname: Skill-Name-With-Hyphens\ndescription: Use when [具体的触发条件和症状]\n---\n\n# 技能名称\n\n## 概述\n这是什么？用 1-2 句话说明核心原则。\n\n## 何时使用\n[如果决策不明显，使用小型内联流程图]\n\n症状和用例的要点列表\n不适用的场景\n\n## 核心模式（技术/模式类）\n前后代码对比\n\n## 快速参考\n用于快速浏览常见操作的表格或要点\n\n## 实现\n简单模式内联代码\n大量参考或可复用工具链接到文件\n\n## 常见错误\n常见问题 + 修复方法\n\n## 实际效果（可选）\n具体结果\n发现至关重要： 未来的 Claude 需要找到你的技能
\n目的： Claude 读取描述来决定为当前任务加载哪些技能。让它能回答：\"我现在应该读这个技能吗？\"
\n格式： 以\"Use when...\"开头，聚焦于触发条件
\n关键：描述 = 何时使用，不是技能做什么
\n描述应该只描述触发条件。不要在描述中总结技能的流程或工作流。
\n为什么这很重要： 测试表明，当描述总结了技能的工作流时，Claude 可能会跟随描述而非阅读完整的技能内容。一个写着\"任务间进行代码审查\"的描述导致 Claude 只做了一次审查，尽管技能的流程图清楚地展示了两次审查（先规格合规再代码质量）。
\n当描述改为仅\"在当前会话中执行包含独立任务的实现计划时使用\"（无工作流摘要）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。
\n陷阱： 总结工作流的描述创建了 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。
\n# 错误：总结了工作流 - Claude 可能会跟随描述而非阅读技能\ndescription: Use when executing plans - dispatches subagent per task with code review between tasks\n\n# 错误：流程细节太多\ndescription: Use for TDD - write test first, watch it fail, write minimal code, refactor\n\n# 正确：只有触发条件，无工作流摘要\ndescription: Use when executing implementation plans with independent tasks in the current session\n\n# 正确：仅触发条件\ndescription: Use when implementing any feature or bugfix, before writing implementation code\n内容：
\n# 错误：太抽象、模糊，未包含何时使用\ndescription: For async testing\n\n# 错误：第一人称\ndescription: I can help you with async tests when they're flaky\n\n# 错误：提到了技术但技能并非该技术特定的\ndescription: Use when tests use setTimeout/sleep and are flaky\n\n# 正确：以\"Use when\"开头，描述问题，无工作流\ndescription: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently\n\n# 正确：技术特定的技能带有明确的触发条件\ndescription: Use when using React Router and handling authentication redirects\n使用 Claude 会搜索的词语：
\n使用主动语态，动词优先：
\ncreating-skills 而非 skill-creationcondition-based-waiting 而非 async-test-helpers问题： getting-started 和频繁引用的技能会加载到每个对话中。每个 token 都很重要。
\n目标字数：
\n技巧：
\n将细节移到工具帮助中：
\n# 错误：在 SKILL.md 中列出所有参数\nsearch-conversations supports --text, --both, --after DATE, --before DATE, --limit N\n\n# 正确：引用 --help\nsearch-conversations 支持多种模式和过滤器。运行 --help 查看详情。\n使用交叉引用：
\n# 错误：重复工作流细节\n搜索时，用模板分派子智能体……\n[20 行重复的说明]\n\n# 正确：引用其他技能\n始终使用子智能体（节省 50-100 倍上下文）。必需：使用 [other-skill-name] 工作流。\n压缩示例：
\n# 错误：冗长的示例（42 词）\n你的搭档：\"我们之前是怎么处理 React Router 中的认证错误的？\"\n你：我来搜索过去对话中的 React Router 认证模式。\n[用搜索查询分派子智能体：\"React Router authentication error handling 401\"]\n\n# 正确：精简的示例（20 词）\n搭档：\"我们之前是怎么处理 React Router 中的认证错误的？\"\n你：正在搜索……\n[分派子智能体 → 整合]\n消除冗余：
\n验证：
\nwc -w skills/path/SKILL.md\n# getting-started 工作流：目标 <150 每个\n# 其他频繁加载的：目标总计 <200\n用你做的事或核心洞察来命名：
\ncondition-based-waiting > async-test-helpersusing-skills 而非 skill-usageflatten-with-flags > data-structure-refactoringroot-cause-tracing > debugging-techniques动名词（-ing）适合描述流程：
\ncreating-skills、testing-skills、debugging-with-logs编写引用其他技能的文档时：
\n仅使用技能名称，带有明确的必需标记：
\n**必需子技能：** 使用 test-driven-development**必需背景：** 你必须理解 systematic-debugging参见 skills/testing/test-driven-development（不清楚是否必需）@skills/testing/test-driven-development/SKILL.md（强制加载，浪费上下文）为什么不用 @ 链接： @ 语法会立即强制加载文件，在你需要之前就消耗 200k+ 的上下文。
digraph when_flowchart {\n \"需要展示信息?\" [shape=diamond];\n \"我可能在决策中犯错?\" [shape=diamond];\n \"使用 markdown\" [shape=box];\n \"小型内联流程图\" [shape=box];\n\n \"需要展示信息?\" -> \"我可能在决策中犯错?\" [label=\"是\"];\n \"我可能在决策中犯错?\" -> \"小型内联流程图\" [label=\"是\"];\n \"我可能在决策中犯错?\" -> \"使用 markdown\" [label=\"否\"];\n}\n仅在以下情况使用流程图：
\n绝不使用流程图用于：
\n参见 @graphviz-conventions.dot 了解 graphviz 样式规则。
\n为你的搭档可视化： 使用此目录中的 render-graphs.js 将技能的流程图渲染为 SVG：
./render-graphs.js ../some-skill # 每个图表分别渲染\n./render-graphs.js ../some-skill --combine # 所有图表合并为一个 SVG\n一个优秀的示例胜过多个平庸的
\n选择最相关的语言：
\n好的示例：
\n不要：
\n你擅长语言移植——一个优秀的示例就够了。
\ndefense-in-depth/\n SKILL.md # 所有内容内联\n适用场景：所有内容都能放下，无需大量参考
\ncondition-based-waiting/\n SKILL.md # 概述 + 模式\n example.ts # 可适配的工作代码\n适用场景：工具是可复用的代码，不只是叙述
\npptx/\n SKILL.md # 概述 + 工作流\n pptxgenjs.md # 600 行 API 参考\n ooxml.md # 500 行 XML 结构\n scripts/ # 可执行工具\n适用场景：参考资料太多无法内联
\n没有失败的测试就不写技能\n这适用于新技能和对现有技能的编辑。
\n先写技能再测试？删掉它。重新开始。\n编辑技能不测试？同样违规。
\n无例外：
\n必需背景： test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。
\n不同类型的技能需要不同的测试方法：
\n例如： TDD、完成前验证、编码前设计
\n测试方式：
\n成功标准： 智能体在最大压力下遵循规则
\n例如： condition-based-waiting、root-cause-tracing、defensive-programming
\n测试方式：
\n成功标准： 智能体成功将技术应用于新场景
\n例如： reducing-complexity、information-hiding 概念
\n测试方式：
\n成功标准： 智能体正确识别何时/如何应用模式
\n例如： API 文档、命令参考、库指南
\n测试方式：
\n成功标准： 智能体找到并正确应用参考信息
\n| 借口 | \n现实 | \n
|---|---|
| \"技能显然很清晰\" | \n对你清晰 ≠ 对其他智能体清晰。测试它。 | \n
| \"这只是参考资料\" | \n参考资料可能有遗漏、不清楚的地方。测试检索。 | \n
| \"测试太过了\" | \n未测试的技能总有问题。15 分钟测试省下数小时。 | \n
| \"有问题再测试\" | \n问题 = 智能体无法使用技能。在部署前测试。 | \n
| \"测试太繁琐\" | \n测试比在生产中调试坏技能少繁琐得多。 | \n
| \"我有信心它很好\" | \n过度自信保证出问题。无论如何都要测试。 | \n
| \"学术审查就够了\" | \n阅读 ≠ 使用。测试应用场景。 | \n
| \"没时间测试\" | \n部署未测试的技能比后面修复浪费更多时间。 | \n
以上所有都意味着：部署前测试。无例外。
\n在写指导内容之前，先给基线失败归类。能让某一类失败变得无懈可击的形式，用在另一类上会可测量地反噬。
\n| 基线失败 | \n正确的形式 | \n错误的形式 | \n
|---|---|---|
| 压力之下跳过/违反规则（明知故犯） | \n禁令 + 合理化借口表 + 红线（见下方\"让技能经受住合理化的考验\"） | \n软性建议（\"优先……\"、\"考虑……\"） | \n
| 遵守了，但产出的形状不对（提示词臃肿、结论被埋、复述规格） | \n正面配方或契约：直接说明产出是什么 —— 它由哪些部分组成、按什么顺序 | \n禁令清单（\"不要复述\"、\"绝不旁白\"） | \n
| 在他们本来就会产出的东西里漏掉了必需元素 | \n结构性手段：在他们要填的模板里放一个 REQUIRED 字段或占位槽 | \n在模板附近写散文式提醒 | \n
| 行为应当取决于某个条件 | \n挂在可观察谓词上的条件句（\"如果简报存在，就引用它\"） | \n无条件规则 + 一堆例外条款 | \n
为什么禁令在\"塑形\"类问题上会反噬： 在存在竞争性激励时（比如\"让提示词自包含\"），智能体会跟\"不要 X\"讨价还价。在针对分派提示词指导做的同题措辞对照测试里，禁令组产出的不想要的内容明显多于配方组（两组分布完全分离），甚至比\"完全不给指导\"的对照组还差 —— 请对你自己的场景做微型测试，别想当然，但永远不要把禁令当默认选择。配方留不下可讨价还价的空间：产出要么符合所说的形状，要么不符合。
\n无论你选哪种形式，都适用的规则：
\n执行纪律的技能（如 TDD）需要抵抗合理化。智能体很聪明，在压力下会找到漏洞。
\n心理学说明： 理解说服技巧为什么有效有助于你系统性地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025），涵盖权威、承诺、稀缺、社会认同和归属原则。
\n不要只是陈述规则——禁止具体的变通方法：
\n\n","files":[{"path":"anthropic-best-practices.md","sizeBytes":42446,"isText":true},{"path":"examples/CLAUDE_MD_TESTING.md","sizeBytes":5423,"isText":true},{"path":"graphviz-conventions.dot","sizeBytes":5970,"isText":false},{"path":"persuasion-principles.md","sizeBytes":5387,"isText":true},{"path":"render-graphs.js","sizeBytes":5633,"isText":true},{"path":"SKILL.md","sizeBytes":25011,"isText":true},{"path":"testing-skills-with-subagents.md","sizeBytes":12389,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-07T18:39:02.900406Z","sha256":"08F9CC9D732DC337BC2034B0F79F34C6B056F18231E6FFF6A0A0E9306F9ABB4D","sizeBytes":42920},"review":null,"source":{"repositoryUrl":"https://github.com/jnMetaCode/superpowers-zh","path":"skills/writing-skills","license":"MIT","commit":"78cb4f68d691d516eb7216897053ea574212cdf6","subtreeSha":"A5E866DA3FAFF6B23D85CCA910D9702EFE4E6B54A967DBF8312A59BC669CE8AE","lastSyncedAt":"2026-09-25T06:49:13.086723Z"},"reviewedAt":"2026-09-07T18:40:03.153977Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/jnMetaCode/superpowers-zh/tree/main/skills/writing-skills"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jnmetacode-superpowers-zh@llmmart"},{"target":"git","command":"git clone https://github.com/jnMetaCode/superpowers-zh.git"}]}