文章目录Pre一、从提示词到技能为什么要「工程化地写技能」1.1 自定义技能是什么1.2 核心理念把技能当作「流程文档上的 TDD」二、什么时候应该写成技能三种类型与决策框架2.1 三种技能类型2.2 写还是不写创建决策框架三、目录结构与渐进式披露让技能可维护、可加载3.1 扁平命名空间与最小文件集3.2 渐进式披露避免深层嵌套与全文强制加载四、SKILL.md 解剖从 Frontmatter 到正文骨架4.1 YAML 前置元数据最重要的一行4.2 推荐正文结构从 Overview 到 Common Mistakes五、Claude 搜索优化CSO让技能「被搜到」5.1 关键词覆盖策略5.2 Token 预算与长度控制5.3 交叉引用的正确姿势避免滥用 六、纪律性技能如何对抗 Agent 的「合理化借口」6.1 纪律性技能的特殊难度6.2 七大说服原则在技能中的应用6.3 「堵住每一个漏洞」四个具体对策七、使用子 Agent 测试技能RED-GREEN-REFACTOR 实战7.1 不可协商的测试循环7.2 不同类型技能的测试策略7.3 如何设计有效的「压力场景」八、自由度光谱与内容模式写多细由「任务脆弱性」决定8.1 自由度光谱8.2 三种常见内容模式九、流程图与视觉约定什么时候值得画图9.1 什么时候应该画流程图9.2 Graphviz 形状约定十、避免「反模式」这些写法越多技能越难用十一、「完整创建清单」像上线代码一样「上线技能」十二、对实践者的启示从「提示词工程」到「技能工程」PreSuperpowers - 01 让 AI 真正“懂工程”Superpowers 软件开发工作流深度解析Superpowers - 02 用 15 个技能给你的 AI 装上「工程大脑」Superpowers 快速开始深度解析Superpowers - 03 一文搞懂 Superpowers面向多平台 AI 编码助手的安装与实践指南Superpowers - 04 从“会写代码”到“会做工程”Superpowers 工作流引擎架构深度剖析Superpowers - 05 构建一个“会自己找插件用”的 Agent深入解析 Superpowers 的技能发现与激活机制Superpowers - 06 从文档到“结构契约”Superpowers 技能剖析与 Frontmatter 深度解读Superpowers - 07 从 SessionStart Hook 看 Superpowers把「技能库」变成「行为操作系统」Superpowers - 08 在 AI 时代重写「需求评审会」深入解读 Superpowers 的头脑风暴与设计规范机制Superpowers - 09 从构思到落地如何用「计划编写与任务粒度」驾驭 AI 时代的软件开发Superpowers - 10 用 Subagent 驱动开发把「AI 写代码」变成一条严谨的生产流水线Superpowers - 11 从计划到落地深入解析 Superpowers 的「内联执行计划」工作流Superpowers - 12 没有失败测试就没有生产代码从 Superpowers 看“铁律级”测试驱动开发Superpowers - 13 系统化调试用一套“四阶段流程”终结瞎猜式修 BugSuperpowers - 14 从「尽早审查、频繁审查」到系统化流水线Superpowers 代码审查工作流深度解析Superpowers - 15 用 Git Worktrees 打造“无尘室”开发环境从 Superpowers 实践谈起Superpowers - 16 用好「finishing-a-development-branch 」这最后一步从混乱收尾到可复用的工程化流程面向读者AI 应用开发者、提示词工程/Agent 工程从业者、技术负责人以及希望用 LLM 标准化团队流程的开发者。在很多团队里「技能skill」这个词还停留在比较模糊的层面要么是几行提示词要么是一段散落在 Wiki 或 README 里的经验总结。 但在 Anthropic 超能力superpowers体系里「自定义技能」被提升到了与代码同等级别的工程工件它们要可发现、可复用、可测试甚至要遵守测试驱动开发TDD的铁律。这篇文章基于 Anthropic 官方的「Writing Skills」技能以及相关最佳实践文档系统拆解如何把「写技能」当成一项严肃的软件工程活动来做。 如果你正在为 Claude、其他 LLM 或自研 Agent 系统设计技能体系这篇文章可以作为端到端的实践指南。一、从提示词到技能为什么要「工程化地写技能」1.1 自定义技能是什么在超能力系统里自定义技能是这样的东西它不是一次性提示而是封装了技巧、思维模型、参考文档的「知识工件」它被存放在skills/目录下以SKILL.md为核心入口可以附带脚本、长文档等支持文件它的直接用户不是人而是未来的 Claude 实例Claude 需要通过搜索、匹配、读取这些技能来指导自己的行为。换句话说一个好的技能应该能做到当 Claude 遇到某类问题时能主动「想到」这份技能读完技能后行为发生明显改善且可复现新的 Agent / 新的对话会话中仍能被发现并正确应用。1.2 核心理念把技能当作「流程文档上的 TDD」「编写技能就是将测试驱动开发TDD应用于流程文档。」在代码世界里TDD 的循环是先写失败的测试RED→ 写最少的代码让测试通过GREEN→ 重构并加固REFACTOR。在技能世界里一模一样RED在「没有这个技能」的前提下让 Agent 在高压场景里任务失败观察其错误和借口GREEN基于这些失败写一份「最小化技能」只解决观察到的问题REFACTOR继续在更高压力下测试收集新的借口并在技能中逐条封堵。最终达到「无懈可击」。这里有两个非常重要的含义如果你没看见 Agent 在没有技能时是如何失败的你根本不知道这项技能是否真正起作用。「先写技能再测试」和「修改技能后不重测」都被视为违背 TDD 的工程纪律。二、什么时候应该写成技能三种类型与决策框架2.1 三种技能类型类型目的示例测试方法技巧具有步骤的具体方法condition-based-waiting、root-cause-tracing应用 变体场景模式用于解决问题的思维模型flatten-with-flags、test-invariants识别 反例场景参考API/语法/工具文档、长参考资料office 文档技能、库参考文档检索 缺口测试场景**技巧techniques**更像是「可操作的食谱」例如调试某类问题的步骤。**模式patterns**是抽象的思维框架例如如何用不变式思考系统测试。**参考reference**则是「字典」比如 PPTX 操作 API 的集中说明。2.2 写还是不写创建决策框架不是所有洞察都值得升格为技能 一个明确的 heuristics应该写成技能的场景这个技巧/模式对你来说并非直觉你也希望未来的自己或其他 Agent 能重复使用它会在跨项目被反复引用它的适用范围足够广不局限于某个项目或业务其他 Agent 或团队成员也能从同一份指导中受益。不应该写成技能的场景只是某次事故/调试的「故事」已有权威文档可用例如标准语言/框架文档不需要再复制一份项目特定约定更适合写在项目的CLAUDE.md或 README 中完全机械、可由自动化/校验工具来保证的约束如固定格式的 Lint 规则。此时应写工具/脚本而不是写技能。这背后是一个关键原则技能要服务于「需要判断力和推理」的场景而不是替代自动化或复读已有文档。三、目录结构与渐进式披露让技能可维护、可加载3.1 扁平命名空间与最小文件集超能力仓库中所有技能都放在skills/目录下采用扁平的命名空间每个技能至少包含一个SKILL.mdskill-name/SKILL.md必需作为主要参考入口skill-name/supporting-file.*仅在需要时存在如可复用脚本、超过 100 行的长参考材料。根据内容规模和形式组织模式大致有三种自包含技能所有内容都写在 SKILL.md例如defense-in-depth/带可复用工具的技能SKILL.md 一个或多个支持工具脚本例如condition-based-waiting/带繁重参考的技能SKILL.md 长篇 API 文档或脚本例如pptx/。3.2 渐进式披露避免深层嵌套与全文强制加载这里的关键设计思想是渐进式披露progressive disclosure。Claude 在判断某个技能是否相关时优先只加载SKILL.md只有在明确需要时才会进一步读取支持文件如果引用层级太深SKILL.md → advanced.md → details.mdClaude 会倾向于用head -100之类的「部分读取」导致关键信息被截断。这意味着尽量让重要语义集中在SKILL.md支持文件层级最多一层避免多级嵌套引用支持文件时要假设它们可能不会被完整读完——关键逻辑不要藏在第 200 行以后。四、SKILL.md 解剖从 Frontmatter 到正文骨架4.1 YAML 前置元数据最重要的一行每个SKILL.md顶部有一段 YAML frontmatter至少包含两个字段字段规则目的name仅限字母、数字、连字符不允许括号或特殊字符标识与交叉引用description必须以 “Use when…” 开头使用第三人称建议 500 字符被 Claude 用来判定是否加载技能总长度包括 name 和 description限制在 1024 字符以内。这里尤其要强调description是整个技能中最重要的一行它只回答一个问题——「Claude 现在应该阅读这份技能吗」几个对比示例❌description: Use when executing plans - dispatches subagent per task with code review between tasks→ 太抽象没有明确触发条件还提前暴露工作流细节。✅description: For async testing✅description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently经验结论是当 description 企图总结整个 workflow 时Claude 会「只看这一行就凭想象执行」从而跳过完整正文。所以 description 应重点描述「触发条件when」而不是「怎么做how」。4.2 推荐正文结构从 Overview 到 Common Mistakes一套推荐的 SKILL.md 模板结构*** name: Skill-Name-With-Hyphens description: Use when [specific triggering conditions and symptoms] *** # Skill Name # Overview 用 1-2 句话说明这是什么、解决什么问题。 # When to Use - 何时使用可以在这里用小型内联流程图表示决策 - 典型症状和用例 - 何时不该使用 # Core Pattern (for techniques/patterns) - 修改前/修改后的代码对比或者核心操作步骤 # Quick Reference - 适合快速浏览的表格或要点列表 # Implementation - 简单场景用内联代码/示例 - 复杂逻辑指向支持文件 # Common Mistakes - 容易犯错的地方及修复方法 # Real-World Impact (optional) - 真实场景中的收益、效果其设计目标很明确服务于 Claude 的「快速发现 → 快速扫描 → 精准执行」流程通过 description 判断是否应该加载技能略读 Overview 看是否匹配当前问题在 Quick Reference 里快速找到相关模式或步骤真正执行时再读 Implementation 和示例。从人的视角来看这也非常符合技术文档写作的好习惯先说明「是什么」「何时用」再给「怎么做」「容易错」。五、Claude 搜索优化CSO让技能「被搜到」传统 SEO 是面向搜索引擎用户CSOClaude Search Optimization则是面向未来的 Claude 实例让技能在真实对话中更容易被搜索到、被判定为相关。5.1 关键词覆盖策略Claude 会用用户对话中的语言去搜索技能因此技能文本里需要有策略地埋入可搜索关键词。建议从四类关键词入手关键词类别示例推荐位置错误信息Hook timed out,ENOTEMPTY,race condition描述、概述症状flaky,hanging,zombie,pollutionWhen to Use、描述同义词timeout/hang/freeze,cleanup/teardown/afterEach正文各处工具实际命令、库名、文件类型Implementation 部分实践含义是写技能时不要只写抽象术语要把开发者真实会说出口的报错、症状、口语化描述放进去。5.2 Token 预算与长度控制上下文窗口是稀缺资源技能中的每个 token 都在和对话历史、其他技能元数据竞争。技能类别目标字数理由入门工作流每个 150几乎每次对话都需要加载高频引用技能总计 200高频加载上下文成本更高其他技能 500在可读性和成本间平衡配套的优化策略包括细节说明挪到工具的--help或脚本注释里通过交叉引用其他技能来避免复制同样的工作流描述精简示例数量优先留下质量最高的一两个示例使用wc -w skills/path/SKILL.md等命令主动检查篇幅。5.3 交叉引用的正确姿势避免滥用很多人会习惯在 Markdown 里直接用path/to/file来做引用但这里强烈不推荐这么做skills/.../SKILL.md会强制立即加载那个文件可能瞬间占掉20 万个 token的上下文。更好的做法是只提及技能名称再用显式「必需子技能」的形式提示例如**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development。六、纪律性技能如何对抗 Agent 的「合理化借口」6.1 纪律性技能的特殊难度有一类技能非常特殊它们专门用于强制某种行为规则例如 TDD、完成前验证verification-before-completion等。对于这类技能仅仅写清楚「流程」是不够的因为Agent 具有一定的自主推理能力会在时间压力、上级指令、沉没成本等因素下为「不遵守规则」寻找看似合理的借口如果技能没有预判并封堵这些借口最终的执行效果会非常差。为此Anthropic 引入了 Cialdini 的七大说服原则并在 2025 年、28000 次对话实验中验证了其对 LLM 合规率的影响——从 33% 提升到 72%。6.2 七大说服原则在技能中的应用原则在技能中的机制典型场景权威使用强制性语言“YOU MUST”、“Never”、“No exceptions”TDD、验证类硬性规则承诺要求显式声明「我正在使用 [技能名]」用 Todo 跟踪多步流程、可审计场景稀缺时间/顺序约束“在继续之前必须…”“立即在 X 之后执行”防止拖延或「以后再做」社会认同强调普遍性“每一次…”“没有 Y 的 X 失败”记录行业/团队通行做法统一使用「我们」的语言“我们的代码库”、“我们是同事”团队文化、协作规范互惠明确收益“这能节省你的时间”可能被认为「麻烦」的技巧喜好积极 framing、共同目标强化但非核心执行机制在实践中这意味着写纪律性技能要更「强硬」用明确的命令式语气、零容忍例外且经常以 checklist 和红旗Red Flags形式出现。6.3 「堵住每一个漏洞」四个具体对策为了系统对抗合理化四个加固动作显式禁止各种变通方式示例对比非常直观脆弱版本Write code before test? Delete it.加固版本Write code before test? Delete it. Start over. **No exceptions:** - Dont keep it as reference - Dont adapt it while writing tests - Dont look at it - Delete means delete逐条点名常见借口保留作参考、边写测试边改、只看不改等。一条原则切断「字面 vs 实质」争论在 TDD、完成前验证等技能里增加一条基础原则「违反规则的字面意义就是违反规则的实质精神。」这直接堵住了「我虽然没按步骤做但精神上是遵守的」这类辩解。构建「借口 vs 现实」对照表把在 RED 阶段观察到的每个借口都写进表格并给出直截了当的反驳例如借口现实“Too simple to test”简单代码一样会出错测试只要 30 秒。“I’ll test after”测试后置无法保证正确行为只是事后解释。“Tests after achieve same goals”测试后置 「这段代码是干什么的」测试前置 「这段代码应该干什么」Red Flags一看到就要「停下重来」的信号使用类似这样的片段# Red Flags - STOP and Start Over - Code before test - I already manually tested it - Tests after achieve the same purpose - This is different because... **All of these mean: Delete code. Start over with TDD.**让 Agent 在高压状态下仍然有一个极其简单的「自查触发器」。七、使用子 Agent 测试技能RED-GREEN-REFACTOR 实战7.1 不可协商的测试循环「测试不是可选项而是技能架构的基础。」对每个技能都必须经历RED在没有技能的情况下运行压力场景记录失败模式和借口GREEN写最小技能解决这些明确失败再带技能重跑场景REFACTOR加入更多压力组合捕获新的合理化方式将其写进技能规则、借口表、红旗列表、keywords 等并再次重测直至「无懈可击」。7.2 不同类型技能的测试策略根据技能类型的不同测试重点有所区别技能类型压力级别场景类型成功标准纪律强制高学术性问题 压力场景 多重压力组合在最大压力下仍遵守规则技巧中应用场景 变体场景 缺失信息测试能在新场景中正确应用这个技巧模式中/低识别场景 应用场景 反例场景知道何时用/不用以及如何应用该模式参考低检索场景 应用场景 缺口测试能查到正确信息并在需要时发现文档缺失7.3 如何设计有效的「压力场景」好的压力场景至少要同时包含几个真实约束时间压力紧急上线、部署窗口即将关闭沉没成本已经写了大量代码回头重来意味着「浪费」权威压力资深同事/上级要求「先上线再说」经济/职业压力项目失败可能影响公司生死或个人晋升疲劳已是加班深夜只想赶紧收工社交压力坚持流程看起来很「教条」实用主义自我辩解「现实一点不要教条」。设计原则包括强迫具体选择A/B/C不要问太抽象的「你觉得应该怎么办」使用实际路径/项目名而不是泛泛的「某个项目」让 Agent 真正做出行动决策而不仅仅是「说明正确答案」。所有在 RED 阶段出现的合理化借口必须在 REFACTOR 阶段被处理——要么写进规则要么写进借口表/Red Flags要么作为 CSO 关键词出现。绝不允许有一个借口「悬空」。八、自由度光谱与内容模式写多细由「任务脆弱性」决定8.1 自由度光谱Anthropic 官方文档提出了一个非常实用的概念自由度degree of freedom。自由度级别何时使用内容格式示例高自由度存在多种有效路径、高度依赖上下文文字启发式、原则性指导代码审查流程、高层设计讨论中自由度有推荐模式但允许一定变体带参数的伪代码、结构化步骤报告生成器、复合工作流低自由度操作脆弱、一致性极其重要错一步就可能灾难精确脚本、不可修改步骤数据库迁移、生产环境变更一个形象比喻两侧是悬崖的窄桥 → 需要坚固护栏低自由度广阔平地 → 给大致方向即可高自由度。换到技能设计里越脆弱的任务技能越要写得「死」越开放的问题技能越要保留判断空间。8.2 三种常见内容模式在具体写作层面可以组合使用三种内容模式模板模式templates适合输出格式报告、邮件、PR 描述等根据自由度设置严格程度有的字段强制要求有的可以选填。示例模式examples对质量敏感的输出最好给一个「完整、真实、可运行」的示例一个高质量、贴近真实的单语言例子远比多个平庸、多语言示例有用。条件工作流模式conditional workflows当存在决策分支时用清晰的条件引导 Agent类似「如果 A则走路径 X否则如果 B则走路径 Y」。针对代码示例有一个非常重要的经验不要为了「覆盖更多语言」而牺牲质量。 Claude 自身具备相当的语言迁移能力你只要选一个领域最相关的语言写好例子即可比如测试技巧 → TypeScript系统调试 → Shell/Python数据处理 → Python。九、流程图与视觉约定什么时候值得画图流程图是把双刃剑一方面可以清晰呈现决策路径另一方面消耗大量 token且维护成本高。9.1 什么时候应该画流程图只在以下场景使用流程图存在非显而易见的决策点且容易出错存在可能「提前退出」的流程循环需要明确何时继续、何时停止需要在 A/B/C 方案间作选择且条件复杂。不要在以下场景使用流程图纯参考性信息用表格/列表即可代码示例用 Markdown 代码块更易复制与阅读简单线性流程用有序列表即可标签没有语义仅是step1、helper2等。9.2 Graphviz 形状约定为了更容易理解流程图还可以定义一套 Graphviz 形状语义约定菱形diamond问题或条件判断方框box操作椭圆ellipse状态或开始/结束纯文本节点命令或简单说明八边形红色填充警告节点双圆圈入口/出口点。这种统一的视觉语言能显著降低理解成本也利于在多个技能之间复用相似的流程图风格。十、避免「反模式」这些写法越多技能越难用「反模式清单」这些做法会积极损害技能质量反模式示例问题所在叙事性示例「在 2025-10-03 的某次会话中我们发现……」过于具体难以复用增加噪音多语言稀释example-js.js、example-py.py、example-go.go各语言都平庸维护负担巨大在流程图中写代码step1 [labelimport fs]无法复制粘贴难以阅读浪费 token泛泛的标签helper1、step3无语义信息理解困难把工作流塞进 descriptiondescription: dispatches subagent per task...Claude 会直接按描述执行而跳过正文深度嵌套引用SKILL.md → advanced.md → details.md促使 Agent 部分读取丢失关键信息写时效性信息「在 2025 年 8 月前使用旧 API」快速过期污染技能术语不一致URL/API route/path/endpoint 混用概念模糊降低理解和执行精度十一、「完整创建清单」像上线代码一样「上线技能」从 RED → GREEN → REFACTOR 到最终部署大致需要确认以下事项节选已针对目标场景设计压力场景纪律性技能至少包含 3 种以上压力组合已在无技能情况下运行场景并逐字记录失败和借口YAML 前置元数据已配置好符合命名规则、description以Use when...开头且不包含工作流摘要技能正文中已埋入关键搜索关键词错误信息、症状、同义词、工具至少有一个高质量示例而非多个平庸、多语言示例已在带技能的情况下重跑场景并验证合规性已构建合理化借口表和 Red Flags 列表并将其纳入技能正文有 Quick Reference 表和 Common Mistakes 部分无叙事性故事无时效性信息术语统一仅在确有必要时使用流程图且遵循 Graphviz 约定所有测试通过后才提交到 Git 并推送。部署未经测试的技能 部署未经测试的代码。十二、对实践者的启示从「提示词工程」到「技能工程」将整个「编写自定义技能」的实践串起来可以看到一个非常清晰的转变技能不是一次性提示而是长生命周期的工程工件需要命名规范、目录结构、测试和版本控制写技能的过程本身就是 TDD一定要先看见失败再写技能最后用压力测试证明它真的起作用真正难的是对抗「合理化借口」你要像防御性编程那样预判每一种规避、偷懒、打折执行的路径并用规则、表格、红旗逐一封堵技能需要强 CSO 意识写的时候就要想到「未来的 Claude 会用什么词来搜到我」从而在语料中埋下合适的错误信息、症状和同义词自由度设计直接决定可用性有些场景必须「写死」有些场景则要留给 Agent 自主发挥关键是根据任务脆弱性选择合适的粒度。如果你正在构建基于 Claude 或其他大模型的工程化工作流可以尝试从一个具体场景出发例如「后端服务的 TDD 规范」、「生产变更流程」按照本文的思路设计一个完整技能用 RED-GREEN-REFACTOR 观察 Agent 如何在没有技能时失败在skills/下创建一个带有高质量SKILL.md的技能目录按推荐模板写 Overview/When to Use/Core Pattern/…用子 Agent 压力测试把所有借口塞进借口表与 Red Flags对照「完整创建清单」逐项勾选最后再部署到团队的技能库中。当你第一次看到「有技能」与「无技能」两个 Agent 在同一压力场景下表现的巨大差异时你大概率会认同写技能确实值得像写一段关键业务代码那样严肃对待。