文章目录Pre一、技能不是文档而是结构契约二、统一的技能目录结构与扁平命名空间三、Frontmatter发现层的两行 YAML 有多关键3.1 只有两个必需字段3.2 description 是全系统最重要的单一字段四、Claude 搜索优化CSO如何写出可被正确发现的描述4.1 首要原则描述触发条件而不是工作流4.2 CSO 的几条具体写作规则五、推荐的技能正文结构从 Overview 到 Common Mistakes5.1 推荐模板结构5.2 各章节的认知职责5.3 流程图只在决策复杂时使用六、真实技能的前置元数据模式纪律 vs 工作流6.1 典型技能与触发策略6.2 两种模式纪律类 vs 工作流类七、三种文件组织模式自包含、可复用工具与繁重参考7.1 自包含技能Self-contained Skill7.2 带可复用工具的技能Skill with Reusable Tools7.3 带繁重参考的技能Skill with Heavy Reference八、技能间的交叉引用为什么避免 语法8.1 标准写法语义引用而非文件导入8.2 避免 导入的原因Token 成本九、Token 预算与加载优先级不对称的现实约束9.1 SessionStart 钩子如何加载技能9.2 Token 压缩策略十、命名约定name 既是标识符也是搜索关键词10.1 命名规则10.2 名称的三重角色十一、 实战建议十二、总结description 不是文档而是索引PreSuperpowers - 01 让 AI 真正“懂工程”Superpowers 软件开发工作流深度解析Superpowers - 02 用 15 个技能给你的 AI 装上「工程大脑」Superpowers 快速开始深度解析Superpowers - 03 一文搞懂 Superpowers面向多平台 AI 编码助手的安装与实践指南Superpowers - 04 从“会写代码”到“会做工程”Superpowers 工作流引擎架构深度剖析Superpowers - 05 构建一个“会自己找插件用”的 Agent深入解析 Superpowers 的技能发现与激活机制在 Superpowers 框架里“技能Skill”不再是随意书写的说明文档而是 AI Agent 与技能作者之间的一份结构化契约。这份契约决定了一个技能是否会被发现、何时被激活、被加载后如何具体影响 Agent 的行为以及在不浪费 Token 的前提下如何提供足够的深度与工具支持。本文面向已经在实践 LLM 应用、Agent 框架或工具链建设的开发者与技术作者系统拆解 Superpowers 技能的内部结构、前置元数据Frontmatter设计与撰写规范并结合仓库中的真实技能示例讨论如何写出“可被正确发现、合理激活、且 Token 友好”的高质量技能。一、技能不是文档而是结构契约Superpowers 给技能下的第一个定义非常关键技能不是自由格式的说明书而是一份结构化协议这个协议在逻辑上拆分为三个层级发现元数据Discovery Metadata行为指导Behavioral Guidance辅助资源Auxiliary Resources这三个层级分别解决三个问题发现元数据技能要不要被加载Agent 在“发现阶段”只看这一小块信息来决定是否调用 Skill 工具并加载该技能如果这里写错了等于技能在系统中“隐身”。行为指导加载之后具体怎么做一旦技能被加载正文部分负责约束和引导 Agent 的行为用什么流程、遵循什么模式、避免哪些错误、如何做权衡等。辅助资源如何在不膨胀关键路径的前提下提供深度各种长参考、可复用脚本、模板、API 文档等被放在独立文件中避免在每次技能加载时把上下文“灌爆”但仍可按需引用。这种设计背后有几个非常工程化的考虑前置元数据如果泄露了工作流摘要Agent 就可能“抄近道”只按摘要执行而不去读技能正文。正文如果写成大而全的长文并且所在技能又被频繁或自动加载那么你会在每个会话无意义地燃烧大量 Token。参考资料如果被直接内联到技能正文中会让与当前任务无关的大块内容充斥上下文降低检索与推理效果。用一句话总结Superpowers 把“写技能”从写说明文档提升为设计一份在 Agent 运行时具有真实约束力的协议对象。二、统一的技能目录结构与扁平命名空间Superpowers 中所有技能统一放在skills/目录下的扁平命名空间中每个技能一个子目录至少包含一个SKILL.md文件其他文件则为可选的辅助资源。典型结构如下skills/ skill-name/ SKILL.md supporting-file.* # 仅在需要时添加这里有两个关键选择扁平命名空间无嵌套技能目录系统刻意禁止在技能目录中再嵌套技能目录这样 Skill 工具在发现阶段可以通过一次扫描完成全局技能列表避免出现“某些技能藏在别的技能下面”的情况。一个技能 一个子目录 一个 SKILL.md目录层级直接映射到技能标识符和交叉引用形式降低 Agent 侧搜索和加载的复杂度。对开发者而言这意味着你在添加新技能时不需要纠结“放在哪个主题目录下”只要遵循约定的目录结构和命名规范Skill 工具就能在一次扫描中把它纳入候选集合。三、Frontmatter发现层的两行 YAML 有多关键每个技能文件SKILL.md必须以一段由---包裹的 YAML 前置元数据Frontmatter开头这就是 Agent 在发现阶段唯一可见的文本内容。示例结构如下***name:skill-name-with-hyphensdescription:Use when[specific triggering conditions and symptoms]***3.1 只有两个必需字段虽然 agentskills.io 规范允许更多字段但 Superpowers 只强制这两个字段字段约束用途name仅限字母、数字、连字符不允许括号和特殊字符作为唯一标识用于superpowers:name交叉引用和路径名description必须用第三人称、以 “Use when…” 开头、不能总结技能工作流推荐不超过 500 字符硬上限 1024 字符Agent 依据它判断是否为当前任务加载该技能注意这里的一个设计细节整个前置元数据块的字符数硬性限制为 1024这是为了确保“发现层”足够轻量避免在每次技能扫描时浪费过多上下文。3.2 description 是全系统最重要的单一字段Superpowers 明确指出description是技能系统中最关键的字段因为在调用 Skill 工具之前Agent 只会看到这一小段文本。如果它写得过于模糊Agent 可能永远不会选择这个技能。如果它写成了“流程摘要”Agent 可能直接按摘要执行而不调用技能导致你在正文里写的所有流程、模式和限制形同虚设。因此在 Superpowers 的实践中围绕description发展出了一套专门的写作规范Claude 搜索优化Claude Search Optimization, CSO。四、Claude 搜索优化CSO如何写出可被正确发现的描述CSO 是围绕description字段形成的一套写作纪律目标是最大化技能被正确发现与加载的概率同时避免描述本身替代技能正文。4.1 首要原则描述触发条件而不是工作流经验表明如果你在description中详细写了“这个技能将如何执行步骤 A、B、C”Claude 往往会把它当成“完整指令”直接按这几句话执行而不会去加载和遵循完整的技能正文。对比示例非常典型# ❌ 错误总结了工作流 —— Claude 可能会抄近道跳过技能正文description:Use when executing plans-dispatches subagent per task with code review between tasks# ✅ 正确仅包含触发条件 —— 迫使 Claude 阅读完整技能description:Use when executing implementation plans with independent tasks in the current session第二种写法只描述“当前任务何时适用该技能”而不暴露具体的执行步骤从而迫使 Agent 调用 Skill 工具加载全文。4.2 CSO 的几条具体写作规则在不泄露工作流的前提下CSO 还强调几类实践始终以 “Use when…” 开头这是一个显式的触发条件锚点也利于模型在搜索时对齐模式。描述的是问题和症状而非某种语言的表象如使用“竞态条件、时序依赖”等概念而不是“setTimeout、sleep”等具体 API 名称除非技能本身是特定技术栈技能。包含 Agent 可能用来搜索的关键词如典型错误信息、症状、同义词、相关工具名称让技能在向量或关键词召回时有更大命中概率。使用第三人称表述因为 description 会被注入系统提示通常以“Assistant 应该…”这样的语境呈现用第三人称更自然。长度控制在 500 字符内总上限 1024给未来可能新增的元字段留出空间同时避免发现层过胖。实操建议把description当作“技能的搜索索引条目”而不是“技能正文摘要”。写完后问自己如果 Agent 仅看这段文本它是否能正确判断“何时需要这个技能”但又不会误以为这里就是全部步骤五、推荐的技能正文结构从 Overview 到 Common MistakesFrontmatter 之后就是真正承载行为逻辑的技能正文。Superpowers 为技能正文设计了一套推荐的章节模板虽然没有强制 schema 校验但在仓库中被广泛遵循。5.1 推荐模板结构文档给出如下 Markdown 模板# Skill Name # Overview What is this? Core principle in 1-2 sentences. # When to Use [Small inline flowchart IF decision non-obvious] Bullet list with symptoms and use cases When NOT to use # Core Pattern (for techniques/patterns) Before/after code comparison # Quick Reference Table or bullets for scanning common operations # Implementation Inline code for simple patterns Link to file for heavy reference or reusable tools # Common Mistakes What goes wrong fixes # Real-World Impact (optional) Concrete results5.2 各章节的认知职责每个章节都有清晰的“认知角色”Overview用 1–2 句给出技能的核心原则让 Agent 快速建立概念锚点。When to Use给出具体触发条件和症状对于复杂决策可以配 Graphviz 流程图帮助 Agent 决定是否继续执行技能。Core Pattern对技术型/模式型技能用“Before/After”的对比方式突出行为上的变化而非只列出步骤。Quick Reference以表格或要点形式列出常见操作方便 Agent 快速扫描而不必每次阅读全文。Implementation给出简短的内联代码示例或者链接到外部脚本/模板避免把大量参考代码塞进正文。Common Mistakes总结技能旨在预防的典型失败模式并给出修正建议这对减少错误路径非常重要。Real-World Impact可选用具体结果或案例强化技能的重要性让 Agent 更有“使用这个技能的动机”。5.3 流程图只在决策复杂时使用当技能的“使用时机”或内部流程存在非线性决策点时推荐在 “When to Use” 中嵌入 Graphviz DOT 语法的流程图。不过文档强调流程图只用于以下情况决策点本身不直观流程存在可能过早终止的循环存在“用 A 还是用 B”的分支逻辑。而线性步骤、普通参考和代码示例仍然用标准 Markdown 书写避免流程图滥用带来的阅读负担。六、真实技能的前置元数据模式纪律 vs 工作流仓库中多个核心技能的description展现了两类典型模式纪律类技能与工作流类技能。6.1 典型技能与触发策略若干技能以及其截断的描述与触发策略技能描述截断示例触发策略brainstorming“You MUST use this before any creative work…”强制语气 穷举使用场景test-driven-development“Use when implementing any feature or bugfix, before writing implementation code”时间条件写实现代码前systematic-debugging“Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes”时间条件 症状枚举receiving-code-review“Use when receiving code review feedback, before implementing suggestions…”时间条件 边缘情况约束verification-before-completion“Use when about to claim work is complete… before committing or creating PRs”时间条件 动作枚举dispatching-parallel-agents“Use when facing 2 independent tasks that can be worked on without shared state…”结构条件任务独立性subagent-driven-development“Use when executing implementation plans with independent tasks in the current session”结构条件 时间条件6.2 两种模式纪律类 vs 工作流类从这些示例可以归纳出两种核心模式纪律类技能Discipline Skills如 TDD、系统化调试、完成前验证等强调的是“在做某件事情之前你必须先做这套流程”。常用时间触发器before writing code / before proposing fixes / before claiming work is complete。常配合强制语气MUST use减少 Agent 主观跳过的空间。工作流类技能Workflow Skills如并行子 Agent 分派、Subagent 驱动开发等更关注当前任务结构是否满足一定条件。常用结构条件独立任务、多步骤实现、特定依赖关系指明适用场景。时间条件常作为辅助手段在执行某类计划时等。对技能作者的启发是如果你的技能是“流程纪律”请突出时间触发布局让 Agent 在关键节点“想起”它。如果你的技能是“工作流模式”就从任务结构特征出发描述触发条件。七、三种文件组织模式自包含、可复用工具与繁重参考虽然前置元数据与正文结构是所有技能共享的“硬契约”但技能目录内具体如何组织文件可以根据内容重量采用三种模式。7.1 自包含技能Self-contained Skilldefense-in-depth/ SKILL.md # 所有内容内联所有概念、流程、示例代码等都在SKILL.md中完成。适用于原则性技能、长度有限例如代码不超过约 50 行的模式、检查清单与简单流程。这是最常见、也是默认的组织方式。7.2 带可复用工具的技能Skill with Reusable Toolscondition-based-waiting/ SKILL.md # 概述 模式说明 example.ts # 可直接复制/调整的辅助代码特征是目录下存在可直接操作的脚本或模板文件这些文件可被开发者复制、修改并直接运行。SKILL.md负责讲清模式、使用方式和注意事项。辅助文件则提供“可落地”的代码实现。与“繁重参考”的区别在于这里内容是可执行/可操作的而非纯信息性文档。7.3 带繁重参考的技能Skill with Heavy Referencepptx/ SKILL.md # 概述 工作流 pptxgenjs.md # ~600 行 API 参考 ooxml.md # ~500 行 XML 结构说明 scripts/ # 可执行工具可选当技能涉及大量 API 文档、协议细节、复杂语法说明时这些“重参考”被拆分为独立 Markdown 文件由SKILL.md以链接形式索引SKILL.md扮演索引页与工作流指南的角色。参考文件充当“书架”在需要时按需读取。这种结构既保持主技能文档可浏览、可加载又支持深度查阅避免在每次技能加载时把几百行参考文档硬塞进上下文。八、技能间的交叉引用为什么避免语法在复杂项目中一个技能引用另一个技能是常态。Superpowers 为此设计了专门的交叉引用语法而刻意避免了file方式。8.1 标准写法语义引用而非文件导入推荐写法示例**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development **REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging这里有三个关键点使用superpowers:name这种语义引用而不是path/to/SKILL.md。用清晰的级别标记REQUIRED SUB-SKILL、REQUIRED BACKGROUND而不是软性提示see also。在需要时Agent 会基于name使用 Skill 工具加载对应技能而不是在解析文本时就硬性展开引用文件。8.2 避免导入的原因Token 成本导入机制的一个典型问题是只要引用存在对应文件就会立刻被加载进上下文即使当前任务并不会真正用到它。在大型技能体系中这可能意味着仅仅因为一个技能引用了几个子技能你就在每次加载时自动拖带数十甚至上百 KB 的上下文。Token 成本呈指数叠加对长会话与多轮交互尤为致命。相比之下语义交叉引用 Skill 工具按需加载的组合使 Agent 能够先知道“这里存在一个相关技能”但仅在需要时才实际加载其正文从而显著节约上下文预算。九、Token 预算与加载优先级不对称的现实约束在实际系统中技能加载具有明显的频次差异有的技能在每个会话一开始就被注入有的则只在少数任务下按需加载。文档因此定义了一个 Token 预算层级和目标字数技能类别目标字数理由会话启动工作流using-superpowers 150 字通过 SessionStart 钩子注入到每一个对话高频加载技能brainstorming, TDD 等 200 字被多种任务类型频繁引用加载概率高其他技能 500 字按需加载但仍建议保持简洁减少不必要消耗9.1 SessionStart 钩子如何加载技能在 SessionStart Hook 中系统会读取using-superpowers/SKILL.md对内容进行 JSON 转义然后作为additionalContext注入到钩子输出使其在任何用户消息到达前就出现在 Agent 上下文中。这意味着using-superpowers是所有对话的“基础规则集”必须极度精简。任何被 SessionStart 或其它高频 Hook 注入的技能其每增加一行文字都会乘以整个系统的所有会话数放大成本。9.2 Token 压缩策略为了在保证表达力的前提下控制成本Superpowers 建议的一些压缩手段包括将详细参数说明移入可执行脚本或工具的--help输出而不是全部写在 SKILL.md 中。使用交叉引用代替复制粘贴别的技能内容让 Agent 在需要时再加载那个技能。在代码示例上选择一个高质量代表性例子而不是堆叠很多类似示例。Token 预算是真实且不对称的特别是会话启动技能其总体开销往往比按需加载技能高出多个数量级。十、命名约定name 既是标识符也是搜索关键词最后还有一个经常被忽略但在 Superpowers 中被反复强调的细节技能名称本身就承担着标识符、搜索目标与认知锚点三重角色。10.1 命名规则使用小写 kebab-case如condition-based-waiting、subagent-driven-development。只允许字母、数字与连字符不允许括号和其它特殊字符由前置元数据规范强制限制。流程型技能优先使用以动词开头的动名词如creating-skills、testing-skills、debugging-with-logs。用动作或核心洞察命名而不是模糊类别用flatten-with-flags而不是data-structure-refactoring。用root-cause-tracing而不是debugging-techniques。10.2 名称的三重角色一个好的技能名能够同时完成三件事唯一标识符被用于目录路径和superpowers:name类型的交叉引用。搜索关键词当 Agent 在技能空间中检索时技能名本身就参与相似度与关键词匹配。认知锚点让人类读者和 Agent 看到名称就能大致理解技能的核心意图与适用场景。因此可以把为技能命名视为 CSO 的一部分如果你用的是人类和 Agent 都自然会搜索的词汇技能被找到的机会就会显著提高。十一、 实战建议结合整篇文档的设计理念如果你计划在 Superpowers 或类似框架中编写自己的技能可以从以下几个方向着手实践先想清楚这是纪律还是工作流纪律技能突出“在某个关键时间点之前必须执行”工作流技能突出“当任务结构满足某些条件时适用”。把description当作搜索条目而不是宣传文案明确“Use when…”后面要回答的是在什么症状或条件下我应该想到这个技能避免把任何流程细节写进这段描述。为技能正文设计“认知路径”从 Overview 迅速建立核心概念在 When to Use 做清晰决策树必要时用流程图在 Core Pattern 中强调行为变化而不是堆叠步骤在 Common Mistakes 中写下你希望 Agent 不再犯的典型错误。根据内容重量选择文件组织模式简单模式和原则自包含在一个 SKILL.md 中即可涉及可复用脚本把脚本拆出去、在正文中链接有长文档和 API 细节抽成单独 Markdown 参考并让 SKILL.md 只做索引和工作流说明。时刻记住 Token 预算与加载频次是不对称的任何有可能被自动加载如 SessionStart 注入的技能必须被压缩到骨感把“可选的深度”移到辅助文件中保证发现层和主体的“关键路径”足够瘦。十二、总结description 不是文档而是索引description 字段不是文档而是一条搜索索引条目。技能编写中最常见的失败模式就是写出了一段“准确但摘要化”的描述结果 Claude 完全跳过技能正文仅按描述行事。Token 预算是真实且不对称。一个 500 字且加载到每个会话的技能其累计上下文消耗远远超过一个按需加载的 500 字技能。在为了“看起来完整”而添加内容前先问自己它的激活频率有多高值不值得这份开销理解“技能剖析与 Frontmatter”中这套结构契约 是从“写提示词”进化为“设计可组合技能体系”的关键一步。