大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



文章目录

• Pre
• 概述
• 一、为什么需要「Claude 搜索优化」？
• 二、从发现漏斗开始：技能是如何被"看见"的？
• 三、原则一：把 description 当路由器，而不是摘要
• • 3.1 典型的描述写法陷阱
  • 3.2 描述的格式规范
• 四、原则二：用关键词覆盖真实使用场景
• • 4.1 错误信息与堆栈
  • 4.2 症状与通俗说法
  • 4.3 同义词与工具名
• 五、原则三：name 也是发现表面的重要一半
• • 5.1 命名风格：动词优先 + 动名词
  • 5.2 约束与注意事项
• 六、原则四：Token 效率与渐进式披露
• • 6.1 不同技能类别的字数预算
  • 6.2 Token 压缩的三个实用技巧
• 七、原则五：面向"快速扫描"的内容架构
• • 7.1 推荐的章节布局
  • 7.2 控制引用深度与大文件导航
• 八、执行纪律问题：构建"反合理化层"
• • 8.1 几种实用的反合理化技巧
• 九、从 TDD 视角看 CSO：一份实践向检查清单
• 十、实战建议与落地路线图
• 结语：让技能从"文档"变成"生产级组件"

Superpowers - 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 系统化调试：用一套"四阶段流程"终结瞎猜式修 Bug

Superpowers - 14 从「尽早审查、频繁审查」到系统化流水线：Superpowers 代码审查工作流深度解析

Superpowers - 15 用 Git Worktrees 打造"无尘室"开发环境：从 Superpowers 实践谈起

Superpowers - 16 用好「finishing-a-development-branch 」这最后一步：从混乱收尾到可复用的工程化流程

Superpowers - 17 把「写技能」当成工程实践：面向 Claude 的自定义技能编写完整指南

---

面向对象：为 Claude / Agent 系统编写技能（skills）的开发者、研究者，以及希望系统化提升 Agent 工程质量的技术人员。本文默认你对 LLM 调用工具、技能路由等概念已有基本了解。

Claude 如何查找技能

在现实项目里，很多人都遇到过类似的尴尬场景：

• 花了几天写了一套非常精细的技能（SKILL.md + 工具 + 流程图），上线后几乎从未被调用。
• 明明已经为某类错误写了专门的排障技能，模型却还是在主对话里"现想一套流程"。
• 技能被调用了，但模型只照着 one-liner 描述"即兴发挥"，完全无视长篇的流程设计与安全约束。

表面看，是"模型不听话"；本质上，是技能发现系统没被当作工程问题认真对待。

它解决的是三类关键问题：

1. 技能能不能被查到？
   描述写错一个词，整套技能就等于"从世界上消失"。
   
   
2. 查到了会不会被加载正文？
   如果 description 写成"概览 + 步骤总结"，模型往往直接按这几句话执行，不再打开 SKILL.md 正文。
   
   
3. 加载之后会不会被绕过？
   对于"必须遵守的规范型技能"，需要额外防御模型的"合理化"和"偷懒"倾向。
   
   

理解 CSO 的第一步，是搞清楚：Claude 到底是怎么"看见"一个技能的。

---

在一次新会话里，Claude 发现技能的流程可以抽象成一个漏斗模型：

1. 会话启动（Session Start）
   只预加载当前命名空间下所有技能的 YAML frontmatter，而且只看两个字段：name 和 description。
   
   
2. 用户消息到达
   Claude 基于这两个字段，对每个技能做一次"相关性判断"。
   
   
3. 匹配失败 → 技能不可见
   如果 description 与当前任务不匹配，模型甚至不会去读技能正文，SKILL.md 对这次会话来说是完全不可见的。
   
   
4. 匹配成功 → 加载正文
   Claude 调用对应的 Skill tool，加载整个 SKILL.md，并根据内容继续判断：
   • 是否有 checklist / 流程图？
   • 是否需要创建 Todo / 执行计划？
   • 具体步骤如何落地？
   
   
   

这个漏斗给了一个非常关键的启示：

在"技能能不能被发现"这件事上，正文几乎没有任何话语权 ，真正决定生死的是 frontmatter 中的 description。

它不是摘要，而是路由器。

如果你一直把 description 当"文档摘要"来写，那基本是在拿技能可见性做赌注。

---

在实际项目里，一个高频失败模式是这样的：

技能设计了一套完整流程（比如两阶段代码审查），正文里有详尽的流程图和 checklist。

但 description 写成：
Use when executing plans - dispatches subagent per task with code review between tasks

结果：Claude 只执行"一次代码审查"，完全跳过了正文里的两阶段流程。

从大量测试中，可以抽象出几个常见坑位：

因此，有一条非常硬的规则：

description 只回答一个问题："在当前任务下，我现在应不应该加载这个技能？"

其他一切内容（流程、步骤、注意事项），都必须放到正文里。

为了让这一"路由器"在系统里稳定工作，描述需要遵守一套严格格式：

• 必须以 Use when ... 开头，使其语义明确为"触发条件"。
• 必须使用 第三人称 表述，因为它会被注入系统提示，多视角混用会干扰发现逻辑。
• 描述的是 问题本身，而不是某种实现细节（如"某个库的某个函数出 bug"）。
• 除非技能本身是技术特定的，否则要尽量 技术无关，多用通用概念。
• frontmatter 整体不要超过 1024 字符，其中 description 控制在 500 字符内，避免上下文被元数据吃掉太多。

修改已有技能描述时，还需要重新跑一遍原有测试场景，因为轻微的描述改动可能会极大改变技能被发现的概率和条件。

---

Claude 的发现过程本质上就是一个"关键词驱动的匹配器"，因此 description 和正文开头必须覆盖：用户在真实问题场景中自然会说出的那些词。

可以从三个维度来设计关键词集合：

来自真实失败的原始错误字符串应当直接出现在元数据中：

• "Hook timed out"
• "ENOTEMPTY"
• 具体的异常消息、数据库错误码、HTTP 状态信息等。

原因很直白：

用户往往会原样复制错误日志到对话框里，如果技能里出现了这些精确字符串，匹配就非常自然。

大部分用户在不知道专业术语之前，只会说出"感觉上的问题"：

• "不稳定"、"有时候过，有时候不过"（对应 flaky tests）
• "卡死"、"挂住了"、"一直转圈"（对应 hang / deadlock）
• "像僵尸一样的进程"、"跑完还占着资源"等。

技能需要明确包含这些"口语化标签"，否则就只能等用户刚好用到工程师爱说的行话，才有机会触发。

再往外扩一层，是各种 同义词 和 相关工具 / 产物：

• 概念同义词：timeout/hang/freeze、cleanup/teardown/afterEach 等。
• 具体工具、库、文件类型：grep、pdfplumber、.xlsx、git worktree 等。

这些词一方面增强召回率，另一方面也帮助模型更准确判断技能和当前上下文是否真的相关。

当你在写一个技能时，建议显式列出一个"关键词视角"的 checklist：

• 用户可能会贴什么日志？
• 用户在抱怨问题时会怎么说？
• 与这个问题相关的常见工具、命令、文件后缀有哪些？

确认这些都在 description 或正文开头出现过一次。

---

很多人会把 name 当纯粹的"内部 ID"随便起，结果是在第一关就亏掉了一半信号。实际上：
Claude 在评估技能相关性时，会把 name 和 description 作为一个整体来解析。

实践中比较推荐的命名风格是：

• 使用 主动语态、动词优先 的结构，例如：
  • skill-creation
  • async-test-helpers
  • debugging-techniques
• 对于"过程型技能"，优先用 动名词（-ing 形式） ：
  • creating-skills
  • condition-based-waiting
  • root-cause-tracing

这样的名字比 skill-helper、test-utils 更能向模型传达"这个技能解决的是哪一类动作/流程"。

name 字段本身也有硬约束：

• 最长 64 字符。
• 只能包含字母、数字和连字符（-）。
• 不能出现括号或其它特殊字符，否则容易引发解析问题。

因此，在给技能命名时，可以遵循一个简单套路：

先用一句英文动词短语描述这项技能的"核心动作"，

再把空格替换为连字符，视情况加上少量限定词。

例如：

"tracing root causes of flaky tests" → root-cause-tracing

---

CSO 关注的不只是"能不能被发现"，还要考虑长远的上下文成本。

有一些技能（尤其是"快速入门工作流""高频通用技能"）会被注入到每一场对话中，它们每多一个 token，都会永久挤占上下文窗口------这对大型代码库和复杂对话来说，是非常真实的成本。

可以按类别给出一个大致目标区间：

这不是硬性上下限，而是一种"预算思维"：

凡是会"常驻上下文"的东西，都要用最少的 token 传达最关键的信息。

1. 把细节挪到工具自身的帮助信息中
   • 比如一个搜索对话的工具，可以在技能里写： "支持多种模式和过滤器------运行 --help 查看详情。"
   • 而不是逐一列出 --text、--both、--after DATE 等所有参数。
2. 用交叉引用代替复制粘贴流程
   • 当技能 A 依赖技能 B 的完整工作流时，推荐写： "REQUIRED: Use superpowers:test-driven-development for workflow."
   • 切记不要用 @ 链接语法直接引用，因为这会强制立即加载目标文件，在需要之前就消耗大量上下文。
3. 示例写到"最小可行演示"
   • 示例的目标是传达"交互模式"，而不是重现一整段对话。
   • 保留角色、动作和关键转折即可，去掉冗长的寒暄与重复确认。

这样做的总体原则是：

正文更像是"导航层"而不是"百科全书"。

真正的细节，按需拆到专门的参考文件中，在执行时再逐步加载。

---

当某个技能终于被加载时，Claude 不会从第一行开始逐字阅读，而是更像一个工程师在快速浏览文档：

1. 先扫标题与小节结构。
2. 再扫表格、列表这样的"信息密度高"的区域。
3. 只在真正需要执行实现时，才深入阅读局部内容。

因此，一个高可用的 SKILL.md，需要刻意按照"易扫描"的方式编排结构。

一个经过优化的 SKILL.md 通常包括这些部分：

1. 概述（Overview）
   • 用 1--2 句话说明这个技能的核心原则，回答 "这对当前任务有用吗？"。
2. 何时使用 / 何时不要用（When to use / when not to use）
   • 列出典型症状和反模式，帮助模型快速排除不相关场景。
3. 核心模式（Core patterns）
   • 对于技巧型技能，展示"修改前 / 修改后"的代码对比或流程对比。
4. 快速参考（Quick Reference）
   • 用表格或项目符号列出常见操作、参数、注意事项，方便一眼扫过。
5. 实现（Implementation）
   • 内联代码片段，或链接到更大的参考文件。
6. 常见错误（Common pitfalls / errors）
   • 指出容易踩坑的点以及修复策略。

对于行数较多的技能与参考文件，还需要注意两个点：

• 如果某个技能本身超过 ~500 行，正文中引用的其它文件建议只做到一级链接深度 ：
  • SKILL.md → advanced.md 是 ok 的；
  • SKILL.md → advanced.md → details.md 这种多级嵌套就容易导致局部读取不完整。
• 对任何超过 100 行的参考文件，建议在开头加一个目录（TOC）块 。
  因为模型在局部读取时，如果一开始就能看到"完整结构索引"，会更容易跳到正确小节。
  
  

---

对于某些技能，仅仅"能被发现"还不够------它们是用来约束行为、保障安全或强制规范的，如果模型可以轻易说服自己"这次就先不完全照做"，那整个系统的可靠性就会崩盘。

在这类场景中，需要为技能额外添加一层 "反合理化"结构，借鉴了说服心理学的一些结论：

这些内容应该被放在技能正文的前部，而不是隐藏在"附录 / 常见错误"小节中，因为模型是自上而下阅读，而合理化往往发生在完整读完之前。

---

在一个面向技能的 TDD 周期中，可以把 CSO 放在 GREEN 阶段：

当一个技能初步实现并通过了"功能正确性"的基线测试后，再用 CSO 清单去审视"它是否能被可靠发现，并且不易被绕过"。

一个典型的 CSO 检查流程可以长这样：

1. 技能已完成初稿（功能正确）。
2. 检查描述是否只包含触发条件，是否符合 "Use when…"、第三人称等格式。
3. 确认关键词覆盖了错误字符串、症状描述、同义词与相关工具。
4. 确认 name 使用动词优先、动名词、连字符命名，且长度在限制内。
5. 检查正文字数是否在预算范围内，是否有可以抽出的细节。
6. 检查引用深度是否只到一级，避免嵌套层级导致部分文件永远读不到头。
7. 对执行纪律类技能，确认反合理化表格与红旗列表已经放在前部。
8. 如果正文超过一定长度，确认目录齐全、结构适合快速扫描。

只有同时通过 CSO 与对抗性压力测试，技能才算"既可被发现，又难被绕过"。

• 只通过 CSO、不做压力测试：技能"很好找，但很容易被偷工减料"。
• 只通过压力测试、不做 CSO：技能"很坚固，但基本没人能顺利找到它"。

---

站在工程实践视角，如果你准备在团队内部大规模引入 Claude 技能体系，可以按以下路线推进：

1. 为现有技能补齐 CSO 元数据
   • 统一梳理每个技能的 name 和 description。
   • 把所有"流程总结型描述"重写为"触发条件型描述"。
   • 按"错误 / 症状 / 工具"三类补充关键词。
2. 重构关键技能的 SKILL.md 结构
   • 先挑选"高价值 / 高风险"的核心技能（如重构、危险操作、合规相关）。
   • 按"概述 → 何时使用 → 核心模式 → 快速参考 → 实现 → 常见错误"重排结构。
   • 对大文件添加目录，控制引用深度。
3. 为执行纪律类技能加上反合理化层
   • 在实际使用中记录模型常见偷懒借口，整理成合理化表格。
   • 编制红旗列表和绝对化语言段落，在技能开头声明。
4. 建立团队级 CSO Review 规范
   • 在 Code Review / Skill Review 阶段，引入 CSO 检查项：
     • 描述是否合规？
     • 关键词是否覆盖真实语料？
     • Token 是否在预算内？
   • 将其纳入 CI 或质量门禁，避免新技能默默拖垮整体"可发现性"。
5. 结合对抗性测试闭环验证
   • 使用 Subagent 或测试 harness，构造贴近真实对话的压力场景。
   • 验证在各种表述方式下，目标技能能否被正确触发，并且流程不会被捷径替代。

---

在传统软件工程中，没有人会期望"写在 Wiki 里的操作手册"自动变成可靠系统的一部分。

但在 LLM 驱动的系统里，"一份结构合理的 SKILL.md"确实有机会成为系统行为的主要决定因素。

前提是：

• 你把 name 与 description 当成严肃的"API 表面"，而不是随手写的注释。
• 你用关键词和结构设计，尊重模型真实的扫描和匹配方式。
• 你接受"模型会合理化偷懒"这一事实，并用反合理化层去正面应对。

Claude 搜索优化关注的不是"写出更漂亮的文档"，

而是把技能当作一等公民，用工程化手段保证它们在对话中真正被看见、被信任、被严格执行。

在这个意义上，CSO 不是附加装饰，而是构建可靠 Agent 系统的基础设施之一。

如果你已经在实践 Agent 工程，不妨从下一次写 SKILL.md 开始，就把这些原则当作第一优先级来考虑。