03 技能系统：可发现的过程模块¶

一、一个 Skill 不是一篇教程¶

skills/ 下的每个目录通常包含一个 SKILL.md，必要时再放 references、examples 或 scripts。它更接近“可被 Agent 调用的过程协议”，而不是面向人类从头读到尾的教程。

一个成熟 Skill 至少回答四个问题：

何时触发？ frontmatter 的 description 给出条件。
必须遵守什么？ 正文给出铁律、步骤和停止条件。
如何执行？ 正文提供命令、模板、工具映射或示例。
如何证明完成？ 正文要求测试输出、用户批准、review 报告或 Git 状态等证据。

以 skills/test-driven-development/SKILL.md 为例，frontmatter 是：

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

描述没有把整个流程塞进 description，而是只提供触发条件；真正的红—绿—重构在正文中展开。这种分工提高了发现精度，也减少了技能索引本身的上下文负担。

二、目录结构：按复用边界组织¶

源码中可以观察到三种 Skill 目录：

skills/
├── brainstorming/
│   ├── SKILL.md
│   ├── visual-companion.md
│   ├── spec-document-reviewer-prompt.md
│   └── scripts/
├── subagent-driven-development/
│   ├── SKILL.md
│   ├── implementer-prompt.md
│   ├── task-reviewer-prompt.md
│   └── scripts/
└── test-driven-development/
    ├── SKILL.md
    └── writing-good-tests.md

可以把它理解为一套“按需加载”的文档包：

SKILL.md 是入口和规范，应该让 Agent 知道何时用、如何开始。
references/、examples/ 负责深度细节，避免入口变成百科全书。
scripts/ 把重复、易错、依赖环境的动作变成可执行工具。
prompt 模板是编排层的接口，供主 Agent 派发子 Agent 时填充上下文。

三、`using-superpowers` 是元技能¶

using-superpowers/SKILL.md 的 description 是“Use when starting any conversation”。它不是普通领域技能，而是技能系统的元协议：

如果某个技能有 1% 的可能适用，就必须先调用；
在计划模式前，若还没 brainstorm，先调用 brainstorming；
用户说明和项目规则优先于技能，但技能优先于默认行为；
不同宿主的工具名通过平台 reference 文件映射。

因此 Skill 系统有一层递归结构：

session-start
  └── using-superpowers
        ├── brainstorming
        ├── writing-plans
        ├── test-driven-development
        └── ...其他技能

这个元技能解决的不是“模型不知道有技能”，而是“模型倾向于直接行动”。它把“先检查适用技能”提升为会话级不变量。

四、Skill discovery：描述字段为什么要写得像触发器¶

skills/writing-skills/SKILL.md 专门讨论 Skill Discovery Optimization（SDO）。它给出的关键原则是：description 应该覆盖触发词和问题类型，但不要在 description 里复述整个工作流。

写法	结果
“This skill implements a full red-green-refactor process...”	Agent 可能只看摘要，误以为不必加载正文
“Use when implementing any feature or bugfix...”	Agent 能判断现在是否适用，再读取完整协议

一个好的 description 更像函数签名，而不是函数实现：

description = triggering conditions + problem signal + technology scope
body        = constraints + steps + examples + verification

这也是为什么仓库里有些 description 很短，而正文很长。短 description 不是信息不足，而是把索引和实现分层。

五、技能之间如何组合而不互相覆盖¶

Superpowers 通过“职责边界 + 交叉链接”组合 Skill：

Skill	负责	不负责
brainstorming	把想法变成已确认设计	不实现代码
writing-plans	把设计拆成可执行任务	不替代实现者
executing-plans	按已有计划执行	不重新发明设计流程
TDD	验证行为实现顺序	不找未知根因
systematic-debugging	找到根因再修复	不把所有问题都写成测试优先
SDD	编排 implementer/reviewer	不替代任务级 TDD 和 review
verification	完成前检查新鲜证据	不凭感觉宣布成功

职责边界让组合成为串联而不是嵌套复制。例如 SDD 的 task loop 会调用 reviewer；reviewer 发现测试缺失时，仍要遵守 TDD 的证据规则，而不是由 SDD 重新定义测试方法。

六、正文的“压力测试”结构¶

很多 Skill 在流程后专门列出 Common Rationalizations、Red Flags 或 When to Stop and Ask for Help。这不是文学装饰，而是对 Agent 失败模式的定向防御。

以 verification-before-completion 为例，它把“没有新鲜命令输出就声称完成”定义为违反铁律；test-driven-development 则把“先写实现再补测试”定义为必须停下并重来。这些文字的共同机制是：

先命名模型最可能采用的借口；
说明为什么该借口不成立；
给出回到流程的下一步；
把“完成”与可观察证据绑定。

七、何时 Skill 应该附带脚本¶

脚本适合处理三类事情：

要求精确 JSON/进程协议的 transport，例如 hooks/session-start；
重复且容易漏步骤的 workspace 操作，例如 SDD 的 task workspace 工具；
需要在多个测试场景反复运行的自动化，例如 tests/explicit-skill-requests。

如果一段逻辑只是解释判断，不适合过早写成脚本；Skill 的价值正在于把判断标准呈现给模型和用户。源码中的 writing-skills 也强调，Skill 应该是可复用技巧，而不是把一次性解决方案包装成文档。

八、写一个新 Skill 的最小模板¶

---
name: narrow-skill-name
description: Use when [specific trigger] and [recognizable problem]
---

# Skill Name

## Overview
一句话说明这个技能解决的决策问题。

## When to Use
列出触发条件和不适用条件。

## The Rule
写一条不能被“这次很简单”绕过的核心规则。

## Process
按可观察步骤写，包含命令、输入和输出证据。

## Common Rationalizations
列出最可能的绕过方式和回退动作。

关键不是模板本身，而是让每个技能都有可发现的边界、可执行的正文和可验证的出口。

小结¶

Superpowers 的技能系统同时面向三个消费者：模型需要触发器和规则，主 Agent 需要编排边界，维护者需要可测试的文档包。frontmatter、正文、references 和 scripts 的分层，让“丰富的能力库”不会变成每次会话都加载的巨大系统提示词。