[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6RVRJEMGF60JA6Z7XTZK5E2":3,"skill-same:01M6RVRJEMGF60JA6Z7XTZK5E2":94},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":32,"linkOnly":33,"markdownContent":34,"markdownBody":35,"frontMatter":36,"refName":42,"commitSha":43,"skillDirectory":44,"forksCount":45,"repositoryHtmlUrl":46,"repositoryHomepageUrl":47,"ownerHtmlUrl":48,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":49,"install":50,"resources":63},"01M6RVRJEMGF60JA6Z7XTZK5E2","writing-skills",null,"当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用","rzx007\u002FVykor","rzx007","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F22313722?v=4","01M6RVGB3GJ05PGEFHQ34TV6T0","Danovan","01M6RVGB7F20SDKPMEN9RS3N0N",3,"MIT","https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[29,30,31],"writing","writing skills","documentation","2026-11-10 10:12:30",false,"---\nname: writing-skills\ndescription: 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用\nversion: \"1.0.0\"\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [skills, documentation]\n---\n\n# 编写技能\n\n## 概述\n\n**编写技能就是将测试驱动开发应用于流程文档。**\n\n**个人技能存放在智能体特定的目录中（Claude Code 用 `~\u002F.claude\u002Fskills`，Codex 用 `~\u002F.agents\u002Fskills\u002F`）**\n\n你编写测试用例（带子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵守规则），然后重构（堵住漏洞）。\n\n**核心原则：** 如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。\n\n**必需背景：** 在使用此技能前，你必须理解 superpowers:test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。\n\n**官方指南：** Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。\n\n## 什么是技能？\n\n**技能**是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。\n\n**技能是：** 可复用的技术、模式、工具、参考指南\n\n**技能不是：** 关于你某次如何解决问题的叙事\n\n## TDD 映射到技能\n\n| TDD 概念 | 技能创建 |\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**不要创建：**\n- 一次性解决方案\n- 其他地方有充分文档的标准实践\n- 项目特定的约定（放在 CLAUDE.md 中）\n- 机械性约束（如果可以用正则\u002F验证强制执行，就自动化——文档留给需要判断的场景）\n\n## 技能类型\n\n### 技术类\n有具体步骤的方法（condition-based-waiting、root-cause-tracing）\n\n### 模式类\n思考问题的方式（flatten-with-flags、test-invariants）\n\n### 参考类\nAPI 文档、语法指南、工具文档（office docs）\n\n## 目录结构\n\n```\nskills\u002F\n  skill-name\u002F\n    SKILL.md              # 主参考文档（必需）\n    supporting-file.*     # 仅在需要时\n```\n\n**扁平命名空间** - 所有技能在一个可搜索的命名空间中\n\n**分离文件的情况：**\n1. **大量参考内容**（100+ 行）- API 文档、全面的语法说明\n2. **可复用工具** - 脚本、实用程序、模板\n\n**保持内联：**\n- 原则和概念\n- 代码模式（\u003C 50 行）\n- 其他所有内容\n\n## SKILL.md 结构\n\n**Frontmatter（YAML）：**\n- 两个必需字段：`name` 和 `description`（完整支持字段参见 [agentskills.io\u002Fspecification](https:\u002F\u002Fagentskills.io\u002Fspecification)）\n- 总计最多 1024 字符\n- `name`：只使用字母、数字和连字符（不要用括号、特殊字符）\n- `description`：第三人称，仅描述何时使用（不是做什么）\n  - 以\"Use when...\"开头，聚焦于触发条件\n  - 包含具体的症状、场景和上下文\n  - **绝不总结技能的流程或工作流**（参见 SDO 章节了解原因）\n  - 尽量控制在 500 字符以内\n\n```markdown\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## 核心模式（技术\u002F模式类）\n前后代码对比\n\n## 快速参考\n用于快速浏览常见操作的表格或要点\n\n## 实现\n简单模式内联代码\n大量参考或可复用工具链接到文件\n\n## 常见错误\n常见问题 + 修复方法\n\n## 实际效果（可选）\n具体结果\n```\n\n\n## 技能发现优化（SDO）\n\n**发现至关重要：** 未来的 Claude 需要找到你的技能\n\n### 1. 丰富的描述字段\n\n**目的：** Claude 读取描述来决定为当前任务加载哪些技能。让它能回答：\"我现在应该读这个技能吗？\"\n\n**格式：** 以\"Use when...\"开头，聚焦于触发条件\n\n**关键：描述 = 何时使用，不是技能做什么**\n\n描述应该只描述触发条件。不要在描述中总结技能的流程或工作流。\n\n**为什么这很重要：** 测试表明，当描述总结了技能的工作流时，Claude 可能会跟随描述而非阅读完整的技能内容。一个写着\"任务间进行代码审查\"的描述导致 Claude 只做了一次审查，尽管技能的流程图清楚地展示了两次审查（先规格合规再代码质量）。\n\n当描述改为仅\"在当前会话中执行包含独立任务的实现计划时使用\"（无工作流摘要）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。\n\n**陷阱：** 总结工作流的描述创建了 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。\n\n```yaml\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\n**内容：**\n- 使用具体的触发条件、症状和场景来表明此技能适用\n- 描述问题（竞态条件、行为不一致）而非语言特定的症状（setTimeout、sleep）\n- 保持触发条件技术无关，除非技能本身是技术特定的\n- 如果技能是技术特定的，在触发条件中明确说明\n- 用第三人称写（注入到系统提示中）\n- **绝不总结技能的流程或工作流**\n\n```yaml\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\u002Fsleep and are flaky\n\n# 正确：以\"Use when\"开头，描述问题，无工作流\ndescription: Use when tests have race conditions, timing dependencies, or pass\u002Ffail inconsistently\n\n# 正确：技术特定的技能带有明确的触发条件\ndescription: Use when using React Router and handling authentication redirects\n```\n\n### 2. 关键词覆盖\n\n使用 Claude 会搜索的词语：\n- 错误信息：\"Hook timed out\"、\"ENOTEMPTY\"、\"race condition\"\n- 症状：\"flaky\"、\"hanging\"、\"zombie\"、\"pollution\"\n- 同义词：\"timeout\u002Fhang\u002Ffreeze\"、\"cleanup\u002Fteardown\u002FafterEach\"\n- 工具：实际命令、库名称、文件类型\n\n### 3. 描述性命名\n\n**使用主动语态，动词优先：**\n- ✅ `creating-skills` 而非 `skill-creation`\n- ✅ `condition-based-waiting` 而非 `async-test-helpers`\n\n### 4. Token 效率（关键）\n\n**问题：** getting-started 和频繁引用的技能会加载到每个对话中。每个 token 都很重要。\n\n**目标字数：**\n- getting-started 工作流：每个 \u003C150 词\n- 频繁加载的技能：总计 \u003C200 词\n- 其他技能：\u003C500 词（仍要简洁）\n\n**技巧：**\n\n**将细节移到工具帮助中：**\n```bash\n# 错误：在 SKILL.md 中列出所有参数\nsearch-conversations supports --text, --both, --after DATE, --before DATE, --limit N\n\n# 正确：引用 --help\nsearch-conversations 支持多种模式和过滤器。运行 --help 查看详情。\n```\n\n**使用交叉引用：**\n```markdown\n# 错误：重复工作流细节\n搜索时，用模板分派子智能体……\n[20 行重复的说明]\n\n# 正确：引用其他技能\n始终使用子智能体（节省 50-100 倍上下文）。必需：使用 [other-skill-name] 工作流。\n```\n\n**压缩示例：**\n```markdown\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\n**消除冗余：**\n- 不要重复交叉引用的技能中已有的内容\n- 不要解释从命令中就能看出的东西\n- 不要为同一模式提供多个示例\n\n**验证：**\n```bash\nwc -w skills\u002Fpath\u002FSKILL.md\n# getting-started 工作流：目标 \u003C150 每个\n# 其他频繁加载的：目标总计 \u003C200\n```\n\n**用你做的事或核心洞察来命名：**\n- ✅ `condition-based-waiting` > `async-test-helpers`\n- ✅ `using-skills` 而非 `skill-usage`\n- ✅ `flatten-with-flags` > `data-structure-refactoring`\n- ✅ `root-cause-tracing` > `debugging-techniques`\n\n**动名词（-ing）适合描述流程：**\n- `creating-skills`、`testing-skills`、`debugging-with-logs`\n- 主动的，描述你正在进行的操作\n\n### 5. 交叉引用其他技能\n\n**编写引用其他技能的文档时：**\n\n仅使用技能名称，带有明确的必需标记：\n- ✅ 好的：`**必需子技能：** 使用 superpowers:test-driven-development`\n- ✅ 好的：`**必需背景：** 你必须理解 superpowers:systematic-debugging`\n- ❌ 差的：`参见 skills\u002Ftesting\u002Ftest-driven-development`（不清楚是否必需）\n- ❌ 差的：`@skills\u002Ftesting\u002Ftest-driven-development\u002FSKILL.md`（强制加载，浪费上下文）\n\n**为什么不用 @ 链接：** `@` 语法会立即强制加载文件，在你需要之前就消耗 200k+ 的上下文。\n\n## 流程图使用\n\n```dot\ndigraph 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**仅在以下情况使用流程图：**\n- 非显而易见的决策点\n- 你可能过早停止的流程循环\n- \"何时使用 A vs B\"的决策\n\n**绝不使用流程图用于：**\n- 参考资料 → 表格、列表\n- 代码示例 → Markdown 代码块\n- 线性指令 → 编号列表\n- 无语义意义的标签（step1、helper2）\n\n参见 @graphviz-conventions.dot 了解 graphviz 样式规则。\n\n**为你的搭档可视化：** 使用此目录中的 `render-graphs.js` 将技能的流程图渲染为 SVG：\n```bash\n.\u002Frender-graphs.js ..\u002Fsome-skill           # 每个图表分别渲染\n.\u002Frender-graphs.js ..\u002Fsome-skill --combine # 所有图表合并为一个 SVG\n```\n\n## 代码示例\n\n**一个优秀的示例胜过多个平庸的**\n\n选择最相关的语言：\n- 测试技术 → TypeScript\u002FJavaScript\n- 系统调试 → Shell\u002FPython\n- 数据处理 → Python\n\n**好的示例：**\n- 完整可运行\n- 注释良好，解释为什么\n- 来自真实场景\n- 清晰展示模式\n- 可以直接适配（不是通用模板）\n\n**不要：**\n- 用 5 种以上语言实现\n- 创建填空模板\n- 写人为构造的示例\n\n你擅长语言移植——一个优秀的示例就够了。\n\n## 文件组织\n\n### 自包含技能\n```\ndefense-in-depth\u002F\n  SKILL.md    # 所有内容内联\n```\n适用场景：所有内容都能放下，无需大量参考\n\n### 带可复用工具的技能\n```\ncondition-based-waiting\u002F\n  SKILL.md    # 概述 + 模式\n  example.ts  # 可适配的工作代码\n```\n适用场景：工具是可复用的代码，不只是叙述\n\n### 带大量参考的技能\n```\npptx\u002F\n  SKILL.md       # 概述 + 工作流\n  pptxgenjs.md   # 600 行 API 参考\n  ooxml.md       # 500 行 XML 结构\n  scripts\u002F       # 可执行工具\n```\n适用场景：参考资料太多无法内联\n\n## 铁律（与 TDD 相同）\n\n```\n没有失败的测试就不写技能\n```\n\n这适用于新技能和对现有技能的编辑。\n\n先写技能再测试？删掉它。重新开始。\n编辑技能不测试？同样违规。\n\n**无例外：**\n- 不适用于\"简单的添加\"\n- 不适用于\"只是加一个章节\"\n- 不适用于\"文档更新\"\n- 不要保留未测试的更改作为\"参考\"\n- 不要在运行测试时\"调整\"\n- 删除就是删除\n\n**必需背景：** superpowers:test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。\n\n## 测试所有技能类型\n\n不同类型的技能需要不同的测试方法：\n\n### 纪律执行类技能（规则\u002F要求）\n\n**例如：** TDD、完成前验证、编码前设计\n\n**测试方式：**\n- 学术性问题：它们理解规则吗？\n- 压力场景：它们在压力下遵守吗？\n- 多重压力组合：时间 + 沉没成本 + 疲惫\n- 识别合理化借口并添加明确的反驳\n\n**成功标准：** 智能体在最大压力下遵循规则\n\n### 技术类技能（操作指南）\n\n**例如：** condition-based-waiting、root-cause-tracing、defensive-programming\n\n**测试方式：**\n- 应用场景：它们能正确应用技术吗？\n- 变体场景：它们能处理边界情况吗？\n- 缺失信息测试：说明是否有遗漏？\n\n**成功标准：** 智能体成功将技术应用于新场景\n\n### 模式类技能（心智模型）\n\n**例如：** reducing-complexity、information-hiding 概念\n\n**测试方式：**\n- 识别场景：它们能识别模式何时适用吗？\n- 应用场景：它们能使用心智模型吗？\n- 反例：它们知道何时不应用吗？\n\n**成功标准：** 智能体正确识别何时\u002F如何应用模式\n\n### 参考类技能（文档\u002FAPI）\n\n**例如：** API 文档、命令参考、库指南\n\n**测试方式：**\n- 检索场景：它们能找到正确的信息吗？\n- 应用场景：它们能正确使用找到的内容吗？\n- 覆盖测试：常见用例是否都涵盖了？\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| 压力之下跳过\u002F违反规则（明知故犯） | 禁令 + 合理化借口表 + 红线（见下方\"让技能经受住合理化的考验\"） | 软性建议（\"优先……\"、\"考虑……\"） |\n| 遵守了，但产出的**形状**不对（提示词臃肿、结论被埋、复述规格） | 正面配方或契约：直接说明产出**是什么** —— 它由哪些部分组成、按什么顺序 | 禁令清单（\"不要复述\"、\"绝不旁白\"） |\n| 在他们**本来就会产出**的东西里漏掉了必需元素 | 结构性手段：在他们要填的模板里放一个 REQUIRED 字段或占位槽 | 在模板附近写散文式提醒 |\n| 行为**应当取决于某个条件** | 挂在可观察谓词上的条件句（\"如果简报存在，就引用它\"） | 无条件规则 + 一堆例外条款 |\n\n**为什么禁令在\"塑形\"类问题上会反噬：** 在存在竞争性激励时（比如\"让提示词自包含\"），智能体会**跟\"不要 X\"讨价还价**。在针对分派提示词指导做的同题措辞对照测试里，禁令组产出的不想要的内容明显**多于**配方组（两组分布完全分离），甚至比\"完全不给指导\"的对照组还差 —— 请对你自己的场景做微型测试，别想当然，但**永远不要把禁令当默认选择**。配方留不下可讨价还价的空间：产出要么符合所说的形状，要么不符合。\n\n**无论你选哪种形式，都适用的规则：**\n- **不要加\"视情况\"从句。** \"不要 X，除非它很重要\"会重新打开谈判 —— 在同一批措辞测试里，给一个胜出的配方追加**一条**\"视情况\"从句，就把它从稳定退化成了飘忽。真正的例外要表达成**它自己的**条件句，挂在可观察的谓词上。\n- **豁免条款不会限定作用域。** \"这条长度限制不适用于代码块\"，照样会压制代码块。如果产出里有一部分必须豁免，就**重构结构让规则碰不到它**，而不是写豁免。\n\n## 让技能经受住合理化的考验\n\n执行纪律的技能（如 TDD）需要抵抗合理化。智能体很聪明，在压力下会找到漏洞。\n\n**心理学说明：** 理解说服技巧为什么有效有助于你系统性地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025），涵盖权威、承诺、稀缺、社会认同和归属原则。\n\n### 明确堵住每个漏洞\n\n不要只是陈述规则——禁止具体的变通方法：\n\n\u003CBad>\n```markdown\n先写代码再写测试？删掉它。\n```\n\u003C\u002FBad>\n\n\u003CGood>\n```markdown\n先写代码再写测试？删掉它。重新开始。\n\n**无例外：**\n- 不要保留作为\"参考\"\n- 不要在写测试时\"调整\"它\n- 不要看它\n- 删除就是删除\n```\n\u003C\u002FGood>\n\n### 应对\"精神 vs 字面\"的辩论\n\n在前面加入基础原则：\n\n```markdown\n**违反规则的字面意思就是违反规则的精神。**\n```\n\n这切断了整类\"我遵循的是精神\"的合理化借口。\n\n### 构建合理化借口表\n\n从基线测试中捕获合理化借口（参见下方测试章节）。智能体使用的每个借口都进入表中：\n\n```markdown\n| 借口 | 现实 |\n|------|------|\n| \"太简单不值得测试\" | 简单的代码也会出错。测试只需 30 秒。 |\n| \"我后面再测试\" | 测试立即通过什么也证明不了。 |\n| \"后写测试效果一样\" | 后写测试 = \"这做了什么？\" 先写测试 = \"这应该做什么？\" |\n```\n\n### 创建红线列表\n\n让智能体容易自查是否在合理化：\n\n```markdown\n## 红线 - 停下来重新开始\n\n- 先写代码再写测试\n- \"我已经手动测试过了\"\n- \"后写测试效果一样\"\n- \"重要的是精神不是仪式\"\n- \"这个情况不同，因为……\"\n\n**以上所有都意味着：删除代码。用 TDD 重新开始。**\n```\n\n### 更新 SDO 以包含违规症状\n\n在描述中添加：你即将违反规则时的症状：\n\n```yaml\ndescription: use when implementing any feature or bugfix, before writing implementation code\n```\n\n## 技能的红-绿-重构\n\n遵循 TDD 循环：\n\n### 红：编写失败的测试（基线）\n\n在没有技能的情况下运行压力场景。逐字记录行为：\n- 它们做了什么选择？\n- 它们使用了什么合理化借口（原文）？\n- 哪些压力触发了违规？\n\n这就是\"观察测试失败\"——在编写技能之前你必须看到智能体自然会怎么做。\n\n### 绿：编写最小技能\n\n编写针对那些具体合理化借口的技能。不要为假设情况添加额外内容。\n\n用技能运行相同的场景。智能体应该现在遵守。\n\n### 重构：堵住漏洞\n\n智能体找到了新的合理化借口？添加明确的反驳。重新测试直到无懈可击。\n\n### 先做措辞微型测试，再跑完整场景\n\n完整的压力场景是最后一道关卡，但它每轮迭代都又慢又贵。先用**微型测试**验证措辞本身：\n\n1. **每次调用一个全新上下文的样本** —— 一次裸 API 调用，或者没有 API 权限时用一个单发子智能体。system prompt 放**这条指导实际会存在的真实上下文**（完整的 skill 或提示词模板，不是把指导单独拎出来）；user message 放一个会**诱发该失败**的任务。\n2. **永远带一个\"不给指导\"的对照组。** 如果对照组根本没表现出那个失败，那就没什么可修的 —— 停下，别写这条指导。\n3. **每个变体至少 5 次重复。** 单个样本会骗人。\n4. **每一条被标记的命中都要人工读一遍。** 想用程序打分可以，但模板回声和被引用的反例会**伪装成命中**；只看自动计数会同时高估失败和成功。\n5. **方差本身就是一个指标。** 指导真正生效时，多次重复会收敛到同一种形状。5 次重复出现 5 种不同解读，说明这个措辞**没有约束力** —— 先收紧形式，别急着加字。\n\n微型测试验证的是**措辞**；对纪律执行类技能，它**不能替代**压力场景。\n\n**测试方法论：** 参见 @testing-skills-with-subagents.md 了解完整的测试方法：\n- 如何编写压力场景\n- 压力类型（时间、沉没成本、权威、疲惫）\n- 系统地堵住漏洞\n- 元测试技巧\n\n## 反模式\n\n### 叙事式示例\n\"在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……\"\n**为什么不好：** 太具体，不可复用\n\n### 多语言稀释\nexample-js.js、example-py.py、example-go.go\n**为什么不好：** 质量平庸，维护负担重\n\n### 流程图中的代码\n```dot\nstep1 [label=\"import fs\"];\nstep2 [label=\"read file\"];\n```\n**为什么不好：** 无法复制粘贴，难以阅读\n\n### 通用标签\nhelper1、helper2、step3、pattern4\n**为什么不好：** 标签应有语义意义\n\n## 停下：进入下一个技能之前\n\n**编写任何技能后，你必须停下来完成部署流程。**\n\n**不要：**\n- 批量创建多个技能而不逐个测试\n- 在当前技能验证前就进入下一个\n- 因为\"批量处理更高效\"就跳过测试\n\n**下面的部署清单对每个技能都是强制性的。**\n\n部署未测试的技能 = 部署未测试的代码。这是对质量标准的违反。\n\n## 技能创建清单（TDD 适配版）\n\n**重要：使用 TodoWrite 为下面的每个清单项创建待办。**\n\n**红色阶段 - 编写失败的测试：**\n- [ ] 创建压力场景（纪律类技能需 3 个以上组合压力）\n- [ ] 在没有技能的情况下运行场景 - 逐字记录基线行为\n- [ ] 识别合理化借口中的模式\n\n**绿色阶段 - 编写最小技能：**\n- [ ] 名称只使用字母、数字、连字符（无括号\u002F特殊字符）\n- [ ] YAML frontmatter 包含必需的 `name` 和 `description` 字段（最多 1024 字符；参见 [spec](https:\u002F\u002Fagentskills.io\u002Fspecification)）\n- [ ] 描述以\"Use when...\"开头并包含具体的触发条件\u002F症状\n- [ ] 描述用第三人称\n- [ ] 全文包含搜索关键词（错误、症状、工具）\n- [ ] 带有核心原则的清晰概述\n- [ ] 解决红色阶段识别出的具体基线失败\n- [ ] 代码内联或链接到独立文件\n- [ ] 一个优秀的示例（非多语言）\n- [ ] 用技能运行场景 - 验证智能体现在遵守\n\n**重构阶段 - 堵住漏洞：**\n- [ ] 从测试中识别新的合理化借口\n- [ ] 添加明确的反驳（纪律类技能）\n- [ ] 从所有测试迭代中构建合理化借口表\n- [ ] 创建红线列表\n- [ ] 重新测试直到无懈可击\n\n**质量检查：**\n- [ ] 仅在决策不明显时使用小流程图\n- [ ] 快速参考表\n- [ ] 常见错误章节\n- [ ] 无叙事性故事\n- [ ] 支持文件仅用于工具或大量参考\n\n**部署：**\n- [ ] 将技能提交到 git 并推送到你的 fork（如果已配置）\n- [ ] 考虑通过 PR 贡献回去（如果具有广泛用途）\n\n## 发现工作流\n\n未来的 Claude 如何找到你的技能：\n\n1. **遇到问题**（\"测试不稳定\"）\n3. **找到技能**（描述匹配）\n4. **浏览概述**（这相关吗？）\n5. **阅读模式**（快速参考表）\n6. **加载示例**（仅在实现时）\n\n**为此流程优化** - 把可搜索的术语放在前面和各处。\n\n","# 编写技能\n\n## 概述\n\n**编写技能就是将测试驱动开发应用于流程文档。**\n\n**个人技能存放在智能体特定的目录中（Claude Code 用 `~\u002F.claude\u002Fskills`，Codex 用 `~\u002F.agents\u002Fskills\u002F`）**\n\n你编写测试用例（带子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵守规则），然后重构（堵住漏洞）。\n\n**核心原则：** 如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。\n\n**必需背景：** 在使用此技能前，你必须理解 superpowers:test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。\n\n**官方指南：** Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。\n\n## 什么是技能？\n\n**技能**是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。\n\n**技能是：** 可复用的技术、模式、工具、参考指南\n\n**技能不是：** 关于你某次如何解决问题的叙事\n\n## TDD 映射到技能\n\n| TDD 概念 | 技能创建 |\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**不要创建：**\n- 一次性解决方案\n- 其他地方有充分文档的标准实践\n- 项目特定的约定（放在 CLAUDE.md 中）\n- 机械性约束（如果可以用正则\u002F验证强制执行，就自动化——文档留给需要判断的场景）\n\n## 技能类型\n\n### 技术类\n有具体步骤的方法（condition-based-waiting、root-cause-tracing）\n\n### 模式类\n思考问题的方式（flatten-with-flags、test-invariants）\n\n### 参考类\nAPI 文档、语法指南、工具文档（office docs）\n\n## 目录结构\n\n```\nskills\u002F\n  skill-name\u002F\n    SKILL.md              # 主参考文档（必需）\n    supporting-file.*     # 仅在需要时\n```\n\n**扁平命名空间** - 所有技能在一个可搜索的命名空间中\n\n**分离文件的情况：**\n1. **大量参考内容**（100+ 行）- API 文档、全面的语法说明\n2. **可复用工具** - 脚本、实用程序、模板\n\n**保持内联：**\n- 原则和概念\n- 代码模式（\u003C 50 行）\n- 其他所有内容\n\n## SKILL.md 结构\n\n**Frontmatter（YAML）：**\n- 两个必需字段：`name` 和 `description`（完整支持字段参见 [agentskills.io\u002Fspecification](https:\u002F\u002Fagentskills.io\u002Fspecification)）\n- 总计最多 1024 字符\n- `name`：只使用字母、数字和连字符（不要用括号、特殊字符）\n- `description`：第三人称，仅描述何时使用（不是做什么）\n  - 以\"Use when...\"开头，聚焦于触发条件\n  - 包含具体的症状、场景和上下文\n  - **绝不总结技能的流程或工作流**（参见 SDO 章节了解原因）\n  - 尽量控制在 500 字符以内\n\n```markdown\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## 核心模式（技术\u002F模式类）\n前后代码对比\n\n## 快速参考\n用于快速浏览常见操作的表格或要点\n\n## 实现\n简单模式内联代码\n大量参考或可复用工具链接到文件\n\n## 常见错误\n常见问题 + 修复方法\n\n## 实际效果（可选）\n具体结果\n```\n\n\n## 技能发现优化（SDO）\n\n**发现至关重要：** 未来的 Claude 需要找到你的技能\n\n### 1. 丰富的描述字段\n\n**目的：** Claude 读取描述来决定为当前任务加载哪些技能。让它能回答：\"我现在应该读这个技能吗？\"\n\n**格式：** 以\"Use when...\"开头，聚焦于触发条件\n\n**关键：描述 = 何时使用，不是技能做什么**\n\n描述应该只描述触发条件。不要在描述中总结技能的流程或工作流。\n\n**为什么这很重要：** 测试表明，当描述总结了技能的工作流时，Claude 可能会跟随描述而非阅读完整的技能内容。一个写着\"任务间进行代码审查\"的描述导致 Claude 只做了一次审查，尽管技能的流程图清楚地展示了两次审查（先规格合规再代码质量）。\n\n当描述改为仅\"在当前会话中执行包含独立任务的实现计划时使用\"（无工作流摘要）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。\n\n**陷阱：** 总结工作流的描述创建了 Claude 会走的捷径。技能正文变成了 Claude 跳过的文档。\n\n```yaml\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\n**内容：**\n- 使用具体的触发条件、症状和场景来表明此技能适用\n- 描述问题（竞态条件、行为不一致）而非语言特定的症状（setTimeout、sleep）\n- 保持触发条件技术无关，除非技能本身是技术特定的\n- 如果技能是技术特定的，在触发条件中明确说明\n- 用第三人称写（注入到系统提示中）\n- **绝不总结技能的流程或工作流**\n\n```yaml\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\u002Fsleep and are flaky\n\n# 正确：以\"Use when\"开头，描述问题，无工作流\ndescription: Use when tests have race conditions, timing dependencies, or pass\u002Ffail inconsistently\n\n# 正确：技术特定的技能带有明确的触发条件\ndescription: Use when using React Router and handling authentication redirects\n```\n\n### 2. 关键词覆盖\n\n使用 Claude 会搜索的词语：\n- 错误信息：\"Hook timed out\"、\"ENOTEMPTY\"、\"race condition\"\n- 症状：\"flaky\"、\"hanging\"、\"zombie\"、\"pollution\"\n- 同义词：\"timeout\u002Fhang\u002Ffreeze\"、\"cleanup\u002Fteardown\u002FafterEach\"\n- 工具：实际命令、库名称、文件类型\n\n### 3. 描述性命名\n\n**使用主动语态，动词优先：**\n- ✅ `creating-skills` 而非 `skill-creation`\n- ✅ `condition-based-waiting` 而非 `async-test-helpers`\n\n### 4. Token 效率（关键）\n\n**问题：** getting-started 和频繁引用的技能会加载到每个对话中。每个 token 都很重要。\n\n**目标字数：**\n- getting-started 工作流：每个 \u003C150 词\n- 频繁加载的技能：总计 \u003C200 词\n- 其他技能：\u003C500 词（仍要简洁）\n\n**技巧：**\n\n**将细节移到工具帮助中：**\n```bash\n# 错误：在 SKILL.md 中列出所有参数\nsearch-conversations supports --text, --both, --after DATE, --before DATE, --limit N\n\n# 正确：引用 --help\nsearch-conversations 支持多种模式和过滤器。运行 --help 查看详情。\n```\n\n**使用交叉引用：**\n```markdown\n# 错误：重复工作流细节\n搜索时，用模板分派子智能体……\n[20 行重复的说明]\n\n# 正确：引用其他技能\n始终使用子智能体（节省 50-100 倍上下文）。必需：使用 [other-skill-name] 工作流。\n```\n\n**压缩示例：**\n```markdown\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\n**消除冗余：**\n- 不要重复交叉引用的技能中已有的内容\n- 不要解释从命令中就能看出的东西\n- 不要为同一模式提供多个示例\n\n**验证：**\n```bash\nwc -w skills\u002Fpath\u002FSKILL.md\n# getting-started 工作流：目标 \u003C150 每个\n# 其他频繁加载的：目标总计 \u003C200\n```\n\n**用你做的事或核心洞察来命名：**\n- ✅ `condition-based-waiting` > `async-test-helpers`\n- ✅ `using-skills` 而非 `skill-usage`\n- ✅ `flatten-with-flags` > `data-structure-refactoring`\n- ✅ `root-cause-tracing` > `debugging-techniques`\n\n**动名词（-ing）适合描述流程：**\n- `creating-skills`、`testing-skills`、`debugging-with-logs`\n- 主动的，描述你正在进行的操作\n\n### 5. 交叉引用其他技能\n\n**编写引用其他技能的文档时：**\n\n仅使用技能名称，带有明确的必需标记：\n- ✅ 好的：`**必需子技能：** 使用 superpowers:test-driven-development`\n- ✅ 好的：`**必需背景：** 你必须理解 superpowers:systematic-debugging`\n- ❌ 差的：`参见 skills\u002Ftesting\u002Ftest-driven-development`（不清楚是否必需）\n- ❌ 差的：`@skills\u002Ftesting\u002Ftest-driven-development\u002FSKILL.md`（强制加载，浪费上下文）\n\n**为什么不用 @ 链接：** `@` 语法会立即强制加载文件，在你需要之前就消耗 200k+ 的上下文。\n\n## 流程图使用\n\n```dot\ndigraph 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**仅在以下情况使用流程图：**\n- 非显而易见的决策点\n- 你可能过早停止的流程循环\n- \"何时使用 A vs B\"的决策\n\n**绝不使用流程图用于：**\n- 参考资料 → 表格、列表\n- 代码示例 → Markdown 代码块\n- 线性指令 → 编号列表\n- 无语义意义的标签（step1、helper2）\n\n参见 @graphviz-conventions.dot 了解 graphviz 样式规则。\n\n**为你的搭档可视化：** 使用此目录中的 `render-graphs.js` 将技能的流程图渲染为 SVG：\n```bash\n.\u002Frender-graphs.js ..\u002Fsome-skill           # 每个图表分别渲染\n.\u002Frender-graphs.js ..\u002Fsome-skill --combine # 所有图表合并为一个 SVG\n```\n\n## 代码示例\n\n**一个优秀的示例胜过多个平庸的**\n\n选择最相关的语言：\n- 测试技术 → TypeScript\u002FJavaScript\n- 系统调试 → Shell\u002FPython\n- 数据处理 → Python\n\n**好的示例：**\n- 完整可运行\n- 注释良好，解释为什么\n- 来自真实场景\n- 清晰展示模式\n- 可以直接适配（不是通用模板）\n\n**不要：**\n- 用 5 种以上语言实现\n- 创建填空模板\n- 写人为构造的示例\n\n你擅长语言移植——一个优秀的示例就够了。\n\n## 文件组织\n\n### 自包含技能\n```\ndefense-in-depth\u002F\n  SKILL.md    # 所有内容内联\n```\n适用场景：所有内容都能放下，无需大量参考\n\n### 带可复用工具的技能\n```\ncondition-based-waiting\u002F\n  SKILL.md    # 概述 + 模式\n  example.ts  # 可适配的工作代码\n```\n适用场景：工具是可复用的代码，不只是叙述\n\n### 带大量参考的技能\n```\npptx\u002F\n  SKILL.md       # 概述 + 工作流\n  pptxgenjs.md   # 600 行 API 参考\n  ooxml.md       # 500 行 XML 结构\n  scripts\u002F       # 可执行工具\n```\n适用场景：参考资料太多无法内联\n\n## 铁律（与 TDD 相同）\n\n```\n没有失败的测试就不写技能\n```\n\n这适用于新技能和对现有技能的编辑。\n\n先写技能再测试？删掉它。重新开始。\n编辑技能不测试？同样违规。\n\n**无例外：**\n- 不适用于\"简单的添加\"\n- 不适用于\"只是加一个章节\"\n- 不适用于\"文档更新\"\n- 不要保留未测试的更改作为\"参考\"\n- 不要在运行测试时\"调整\"\n- 删除就是删除\n\n**必需背景：** superpowers:test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。\n\n## 测试所有技能类型\n\n不同类型的技能需要不同的测试方法：\n\n### 纪律执行类技能（规则\u002F要求）\n\n**例如：** TDD、完成前验证、编码前设计\n\n**测试方式：**\n- 学术性问题：它们理解规则吗？\n- 压力场景：它们在压力下遵守吗？\n- 多重压力组合：时间 + 沉没成本 + 疲惫\n- 识别合理化借口并添加明确的反驳\n\n**成功标准：** 智能体在最大压力下遵循规则\n\n### 技术类技能（操作指南）\n\n**例如：** condition-based-waiting、root-cause-tracing、defensive-programming\n\n**测试方式：**\n- 应用场景：它们能正确应用技术吗？\n- 变体场景：它们能处理边界情况吗？\n- 缺失信息测试：说明是否有遗漏？\n\n**成功标准：** 智能体成功将技术应用于新场景\n\n### 模式类技能（心智模型）\n\n**例如：** reducing-complexity、information-hiding 概念\n\n**测试方式：**\n- 识别场景：它们能识别模式何时适用吗？\n- 应用场景：它们能使用心智模型吗？\n- 反例：它们知道何时不应用吗？\n\n**成功标准：** 智能体正确识别何时\u002F如何应用模式\n\n### 参考类技能（文档\u002FAPI）\n\n**例如：** API 文档、命令参考、库指南\n\n**测试方式：**\n- 检索场景：它们能找到正确的信息吗？\n- 应用场景：它们能正确使用找到的内容吗？\n- 覆盖测试：常见用例是否都涵盖了？\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| 压力之下跳过\u002F违反规则（明知故犯） | 禁令 + 合理化借口表 + 红线（见下方\"让技能经受住合理化的考验\"） | 软性建议（\"优先……\"、\"考虑……\"） |\n| 遵守了，但产出的**形状**不对（提示词臃肿、结论被埋、复述规格） | 正面配方或契约：直接说明产出**是什么** —— 它由哪些部分组成、按什么顺序 | 禁令清单（\"不要复述\"、\"绝不旁白\"） |\n| 在他们**本来就会产出**的东西里漏掉了必需元素 | 结构性手段：在他们要填的模板里放一个 REQUIRED 字段或占位槽 | 在模板附近写散文式提醒 |\n| 行为**应当取决于某个条件** | 挂在可观察谓词上的条件句（\"如果简报存在，就引用它\"） | 无条件规则 + 一堆例外条款 |\n\n**为什么禁令在\"塑形\"类问题上会反噬：** 在存在竞争性激励时（比如\"让提示词自包含\"），智能体会**跟\"不要 X\"讨价还价**。在针对分派提示词指导做的同题措辞对照测试里，禁令组产出的不想要的内容明显**多于**配方组（两组分布完全分离），甚至比\"完全不给指导\"的对照组还差 —— 请对你自己的场景做微型测试，别想当然，但**永远不要把禁令当默认选择**。配方留不下可讨价还价的空间：产出要么符合所说的形状，要么不符合。\n\n**无论你选哪种形式，都适用的规则：**\n- **不要加\"视情况\"从句。** \"不要 X，除非它很重要\"会重新打开谈判 —— 在同一批措辞测试里，给一个胜出的配方追加**一条**\"视情况\"从句，就把它从稳定退化成了飘忽。真正的例外要表达成**它自己的**条件句，挂在可观察的谓词上。\n- **豁免条款不会限定作用域。** \"这条长度限制不适用于代码块\"，照样会压制代码块。如果产出里有一部分必须豁免，就**重构结构让规则碰不到它**，而不是写豁免。\n\n## 让技能经受住合理化的考验\n\n执行纪律的技能（如 TDD）需要抵抗合理化。智能体很聪明，在压力下会找到漏洞。\n\n**心理学说明：** 理解说服技巧为什么有效有助于你系统性地应用它们。参见 persuasion-principles.md 了解研究基础（Cialdini, 2021; Meincke et al., 2025），涵盖权威、承诺、稀缺、社会认同和归属原则。\n\n### 明确堵住每个漏洞\n\n不要只是陈述规则——禁止具体的变通方法：\n\n\u003CBad>\n```markdown\n先写代码再写测试？删掉它。\n```\n\u003C\u002FBad>\n\n\u003CGood>\n```markdown\n先写代码再写测试？删掉它。重新开始。\n\n**无例外：**\n- 不要保留作为\"参考\"\n- 不要在写测试时\"调整\"它\n- 不要看它\n- 删除就是删除\n```\n\u003C\u002FGood>\n\n### 应对\"精神 vs 字面\"的辩论\n\n在前面加入基础原则：\n\n```markdown\n**违反规则的字面意思就是违反规则的精神。**\n```\n\n这切断了整类\"我遵循的是精神\"的合理化借口。\n\n### 构建合理化借口表\n\n从基线测试中捕获合理化借口（参见下方测试章节）。智能体使用的每个借口都进入表中：\n\n```markdown\n| 借口 | 现实 |\n|------|------|\n| \"太简单不值得测试\" | 简单的代码也会出错。测试只需 30 秒。 |\n| \"我后面再测试\" | 测试立即通过什么也证明不了。 |\n| \"后写测试效果一样\" | 后写测试 = \"这做了什么？\" 先写测试 = \"这应该做什么？\" |\n```\n\n### 创建红线列表\n\n让智能体容易自查是否在合理化：\n\n```markdown\n## 红线 - 停下来重新开始\n\n- 先写代码再写测试\n- \"我已经手动测试过了\"\n- \"后写测试效果一样\"\n- \"重要的是精神不是仪式\"\n- \"这个情况不同，因为……\"\n\n**以上所有都意味着：删除代码。用 TDD 重新开始。**\n```\n\n### 更新 SDO 以包含违规症状\n\n在描述中添加：你即将违反规则时的症状：\n\n```yaml\ndescription: use when implementing any feature or bugfix, before writing implementation code\n```\n\n## 技能的红-绿-重构\n\n遵循 TDD 循环：\n\n### 红：编写失败的测试（基线）\n\n在没有技能的情况下运行压力场景。逐字记录行为：\n- 它们做了什么选择？\n- 它们使用了什么合理化借口（原文）？\n- 哪些压力触发了违规？\n\n这就是\"观察测试失败\"——在编写技能之前你必须看到智能体自然会怎么做。\n\n### 绿：编写最小技能\n\n编写针对那些具体合理化借口的技能。不要为假设情况添加额外内容。\n\n用技能运行相同的场景。智能体应该现在遵守。\n\n### 重构：堵住漏洞\n\n智能体找到了新的合理化借口？添加明确的反驳。重新测试直到无懈可击。\n\n### 先做措辞微型测试，再跑完整场景\n\n完整的压力场景是最后一道关卡，但它每轮迭代都又慢又贵。先用**微型测试**验证措辞本身：\n\n1. **每次调用一个全新上下文的样本** —— 一次裸 API 调用，或者没有 API 权限时用一个单发子智能体。system prompt 放**这条指导实际会存在的真实上下文**（完整的 skill 或提示词模板，不是把指导单独拎出来）；user message 放一个会**诱发该失败**的任务。\n2. **永远带一个\"不给指导\"的对照组。** 如果对照组根本没表现出那个失败，那就没什么可修的 —— 停下，别写这条指导。\n3. **每个变体至少 5 次重复。** 单个样本会骗人。\n4. **每一条被标记的命中都要人工读一遍。** 想用程序打分可以，但模板回声和被引用的反例会**伪装成命中**；只看自动计数会同时高估失败和成功。\n5. **方差本身就是一个指标。** 指导真正生效时，多次重复会收敛到同一种形状。5 次重复出现 5 种不同解读，说明这个措辞**没有约束力** —— 先收紧形式，别急着加字。\n\n微型测试验证的是**措辞**；对纪律执行类技能，它**不能替代**压力场景。\n\n**测试方法论：** 参见 @testing-skills-with-subagents.md 了解完整的测试方法：\n- 如何编写压力场景\n- 压力类型（时间、沉没成本、权威、疲惫）\n- 系统地堵住漏洞\n- 元测试技巧\n\n## 反模式\n\n### 叙事式示例\n\"在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……\"\n**为什么不好：** 太具体，不可复用\n\n### 多语言稀释\nexample-js.js、example-py.py、example-go.go\n**为什么不好：** 质量平庸，维护负担重\n\n### 流程图中的代码\n```dot\nstep1 [label=\"import fs\"];\nstep2 [label=\"read file\"];\n```\n**为什么不好：** 无法复制粘贴，难以阅读\n\n### 通用标签\nhelper1、helper2、step3、pattern4\n**为什么不好：** 标签应有语义意义\n\n## 停下：进入下一个技能之前\n\n**编写任何技能后，你必须停下来完成部署流程。**\n\n**不要：**\n- 批量创建多个技能而不逐个测试\n- 在当前技能验证前就进入下一个\n- 因为\"批量处理更高效\"就跳过测试\n\n**下面的部署清单对每个技能都是强制性的。**\n\n部署未测试的技能 = 部署未测试的代码。这是对质量标准的违反。\n\n## 技能创建清单（TDD 适配版）\n\n**重要：使用 TodoWrite 为下面的每个清单项创建待办。**\n\n**红色阶段 - 编写失败的测试：**\n- [ ] 创建压力场景（纪律类技能需 3 个以上组合压力）\n- [ ] 在没有技能的情况下运行场景 - 逐字记录基线行为\n- [ ] 识别合理化借口中的模式\n\n**绿色阶段 - 编写最小技能：**\n- [ ] 名称只使用字母、数字、连字符（无括号\u002F特殊字符）\n- [ ] YAML frontmatter 包含必需的 `name` 和 `description` 字段（最多 1024 字符；参见 [spec](https:\u002F\u002Fagentskills.io\u002Fspecification)）\n- [ ] 描述以\"Use when...\"开头并包含具体的触发条件\u002F症状\n- [ ] 描述用第三人称\n- [ ] 全文包含搜索关键词（错误、症状、工具）\n- [ ] 带有核心原则的清晰概述\n- [ ] 解决红色阶段识别出的具体基线失败\n- [ ] 代码内联或链接到独立文件\n- [ ] 一个优秀的示例（非多语言）\n- [ ] 用技能运行场景 - 验证智能体现在遵守\n\n**重构阶段 - 堵住漏洞：**\n- [ ] 从测试中识别新的合理化借口\n- [ ] 添加明确的反驳（纪律类技能）\n- [ ] 从所有测试迭代中构建合理化借口表\n- [ ] 创建红线列表\n- [ ] 重新测试直到无懈可击\n\n**质量检查：**\n- [ ] 仅在决策不明显时使用小流程图\n- [ ] 快速参考表\n- [ ] 常见错误章节\n- [ ] 无叙事性故事\n- [ ] 支持文件仅用于工具或大量参考\n\n**部署：**\n- [ ] 将技能提交到 git 并推送到你的 fork（如果已配置）\n- [ ] 考虑通过 PR 贡献回去（如果具有广泛用途）\n\n## 发现工作流\n\n未来的 Claude 如何找到你的技能：\n\n1. **遇到问题**（\"测试不稳定\"）\n3. **找到技能**（描述匹配）\n4. **浏览概述**（这相关吗？）\n5. **阅读模式**（快速参考表）\n6. **加载示例**（仅在实现时）\n\n**为此流程优化** - 把可搜索的术语放在前面和各处。\n\n",{"name":5,"license":15,"version":37,"metadata":38,"description":7},"1.0.0",{"hermes":39},{"tags":40},[41,31],"skills","main","11fa3057bb1aff51d77b97648803dec2b2ea62d9",".agents\u002Fskills\u002Fwriting-skills",2,"https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor","https:\u002F\u002Frzx007.github.io\u002FVykor\u002F","https:\u002F\u002Fgithub.com\u002Frzx007","2026-11-13 23:57:39",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add rzx007\u002FVykor --skill writing-skills",{"tool":56,"command":57},"bunx","bunx skills add rzx007\u002FVykor --skill writing-skills",{"tool":59,"command":60},"pnpm","pnpm dlx skills add rzx007\u002FVykor --skill writing-skills","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002FSKILL.md",true,[64,70,74,80,84,90],{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"anthropic-best-practices.md","REFERENCE","参考文档",42446,"https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002Fanthropic-best-practices.md",{"path":71,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":72,"sourceHtmlUrl":73},"examples\u002FCLAUDE_MD_TESTING.md",5423,"https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002Fexamples\u002FCLAUDE_MD_TESTING.md",{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"graphviz-conventions.dot","OTHER","其他",5970,"https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002Fgraphviz-conventions.dot",{"path":81,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":82,"sourceHtmlUrl":83},"persuasion-principles.md",5387,"https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002Fpersuasion-principles.md",{"path":85,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":88,"sourceHtmlUrl":89},"render-graphs.js","SCRIPT","脚本",4857,"https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002Frender-graphs.js",{"path":91,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":92,"sourceHtmlUrl":93},"testing-skills-with-subagents.md",12401,"https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-skills\u002Ftesting-skills-with-subagents.md",[95,102,114,137,149,162],{"skillNo":96,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":101,"publishedAt":32},"01M6RVYYTPGG9WWWV4QAY0YEY3","https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[99,100],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[30,29,31],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":110,"publishedAt":32},"01M6RVYE486HE8NQ2M4G5DNG63","writing-plans","当你有规格说明或需求用于多步骤任务时使用，在动手写代码之前","https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fwriting-plans\u002FSKILL.md",[108,109],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[111,112,29,113,31],"plans","writing plans","planning",{"skillNo":115,"name":116,"nameZh":6,"description":117,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":118,"categories":119,"keywords":123,"publishedAt":32},"01M6RVY778PEDPWQ0DCM25QW3A","workflow-runner","在 Claude Code \u002F OpenClaw \u002F Cursor 中直接运行 agency-orchestrator YAML 工作流——无需 API key，使用当前会话的 LLM 作为执行引擎。当用户提供 .yaml 工作流文件或要求多角色协作完成任务时触发。","https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fworkflow-runner\u002FSKILL.md",[120],{"categoryNo":121,"categoryName":122,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[124,125,126,127,128,129,130,131,132,133,134,135,136],"workflow runner","runner","workflow","协作","文件","agency","orchestrator","cursor","api","execution","yaml","code","openclaw",{"skillNo":138,"name":139,"nameZh":6,"description":140,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":141,"categories":142,"keywords":143,"publishedAt":32},"01M6RVY4NR6RRPV174AB706A13","verification-before-completion","在宣称工作完成、已修复或测试通过之前使用，在提交或创建 PR 之前——必须运行验证命令并确认输出后才能声称成功；始终用证据支撑断言","https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fverification-before-completion\u002FSKILL.md",[],[144,145,146,147,148],"verification before completion","verification","quality","pr","testing",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":155,"publishedAt":32},"01M6RVY1ZQ6ADVCZGBS371HD88","using-superpowers","在开始任何对话时使用——确立如何查找和使用技能，要求在任何响应（包括澄清性问题）之前调用 Skill 工具","https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fusing-superpowers\u002FSKILL.md",[],[156,157,158,159,160,161],"superpowers","using superpowers","对话","Meta","工具","getting-started",{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":168,"publishedAt":32},"01M6RVXJFEQ00P7XBQ8FBEKKJ2","using-git-worktrees","当需要开始与当前工作区隔离的功能开发，或在执行实现计划之前使用——通过原生工具或 git worktree 回退机制确保隔离工作区存在","https:\u002F\u002Fgithub.com\u002Frzx007\u002FVykor\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fusing-git-worktrees\u002FSKILL.md",[],[169,170,171,172,173,126,174,175,160],"using git worktrees","git","git worktrees","worktrees","Using git","worktree","git worktree"]