Superpowers 源码解读（二）：技能系统设计

Superpowers 源码解读（二）：技能系统设计

深入理解 SKILL.md 结构设计、CSO 优化策略、流程图规范

前言

在上一篇中，我们理解了 superpowers 的整体架构。本篇深入技能系统的核心设计，学习如何编写高质量的技能文档。

---

📁 本文学习目录

skills/writing-skills/              # 技能编写指南
├── SKILL.md                       # 核心：技能设计模式
├── graphviz-conventions.dot       # 流程图规范
├── testing-skills-with-subagents.md  # 技能测试方法
└── anthropic-best-practices.md    # Anthropic 最佳实践

skills/test-driven-development/    # 纪律强制型示例
└── SKILL.md

skills/systematic-debugging/       # 技术指南型示例
└── SKILL.md

---

一、SKILL.md 结构设计

1.1 YAML Frontmatter

只有两个字段，最大 1024 字符：

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions]
---

关键规则：

• name：只用字母、数字、连字符（无特殊字符）
• description：第三人称，只描述触发条件，不描述工作流

1.2 正文结构

# Skill Name

## Overview           # 核心原则 1-2 句话
## When to Use        # 何时使用（可选流程图）
## Core Pattern       # 模式/技术核心
## Quick Reference    # 快速参考表
## Implementation     # 实现代码或链接
## Common Mistakes    # 常见错误

---

二、三种技能类型

flowchart TD
    A[技能类型] --> B[纪律强制型<br/>Rigid]
    A --> C[技术指南型<br/>Technique]
    A --> D[参考文档型<br/>Reference]
    
    B --> B1[严格流程]
    B --> B2[禁止例外]
    B --> B3[需要 Red Flags 表]
    
    C --> C1[方法论指导]
    C --> C2[灵活应用]
    C --> C3[需要代码示例]
    
    D --> D1[API 文档]
    D --> D2[语法指南]
    D --> D3[需要清晰目录]

2.1 纪律强制型（Rigid）

特点：严格流程，无例外

示例：TDD、verification-before-completion

必需组件：

• Red Flags 表
• 理性化借口清单
• 明确的 "No exceptions" 条款

2.2 技术指南型（Technique）

特点：方法论指导，灵活应用

示例：condition-based-waiting、systematic-debugging

必需组件：

• 代码示例
• 应用场景说明
• 最佳实践

2.3 参考文档型（Reference）

特点：API 文档、语法指南

示例：pptx、office docs

必需组件：

• 清晰的目录结构
• 按需加载的文件组织

---

三、CSO（Claude Search Optimization）

这是技能系统最关键的设计之一。

3.1 核心原则

description 只描述触发条件，不描述工作流

3.2 为什么重要？

测试发现了一个关键问题：

flowchart LR
    A[description 包含工作流] --> B[Claude 只读 description]
    B --> C[跳过完整技能内容]
    C --> D[执行不完整]
    
    A2[description 只描述触发条件] --> B2[Claude 加载完整技能]
    B2 --> C2[读取所有内容]
    C2 --> D2[正确执行]

真实案例：

• description 写 "code review between tasks"
• 结果：Claude 只做一次审查
• 实际技能要求：两次审查（规范合规 + 代码质量）

3.3 正确写法对比

# ❌ 错误：包含工作流
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ 正确：只描述触发条件
description: Use when implementing any feature or bugfix, before writing implementation code

# ❌ 错误：包含流程细节
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ 正确：只描述何时使用
description: Use when executing implementation plans with independent tasks in the current session

3.4 CSO 优化技巧

技巧	说明
使用具体触发词	错误信息、症状、工具名
描述问题而非语言特性	"race conditions" 而非 "setTimeout"
第三人称	"Use when..." 而非 "I can help..."
关键词覆盖	同义词、错误信息、工具命令

---

四、流程图设计规范

流程图是技能文档中最重要的可视化工具，但很多人用不好。让我详细说明。

4.1 节点类型对比

flowchart TD
    subgraph 正确示例["✅ 正确示例"]
        A1["❓ Is test passing?"]:::diamond
        A2["📝 Write the test"]:::box
        A3["💻 npm test"]:::plaintext
        A4["🔵 Test is failing"]:::ellipse
        A5["🛑 STOP: Never skip tests"]:::octagon
        A6["⭕ Process starts"]:::doublecircle
    end
    
    subgraph 错误示例["❌ 错误示例"]
        B1["Check if test passes"]:::wrong
        B2["Do the thing"]:::wrong
        B3["Run command"]:::wrong
        B4["Something wrong"]:::wrong
    end
    
    classDef diamond fill:#fff,stroke:#666,stroke-width:2px
    classDef box fill:#e3f2fd,stroke:#1976d2
    classDef plaintext fill:#f5f5f5,stroke:#999
    classDef ellipse fill:#fff3e0,stroke:#f57c00
    classDef octagon fill:#ffebee,stroke:#d32f2f
    classDef doublecircle fill:#e8f5e9,stroke:#388e3c
    classDef wrong fill:#ffcdd2,stroke:#d32f2f,stroke-dasharray: 5 5

4.2 节点类型详解

形状	用途	正确示例	错误示例
diamond	问题/决策	Is test passing?	Check test status
box	动作	Write the test	The test writing
plaintext	命令	npm test	Run the test command
ellipse	状态	Test is failing	Something wrong
octagon	警告	STOP: Never skip tests	Be careful
doublecircle	入口/出口	Process starts	Begin

4.3 实际案例：TDD 流程图

下面是 test-driven-development 技能中的真实流程图：

flowchart LR
    red["🔴 RED<br/>Write failing test"]:::redbox
    verify_red{"✅ Verify fails<br/>correctly?"}:::diamond
    green["🟢 GREEN<br/>Minimal code"]:::greenbox
    verify_green{"✅ Verify passes<br/>All green?"}:::diamond
    refactor["🔵 REFACTOR<br/>Clean up"]:::bluebox
    next["➡️ Next"]:::ellipse

    red --> verify_red
    verify_red -->|yes| green
    verify_red -->|wrong failure| red
    green --> verify_green
    verify_green -->|yes| refactor
    verify_green -->|no| green
    refactor -->|stay green| verify_green
    verify_green --> next
    next --> red

    classDef redbox fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px
    classDef greenbox fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
    classDef bluebox fill:#bbdefb,stroke:#1976d2,stroke-width:2px
    classDef diamond fill:#fff,stroke:#666,stroke-width:2px
    classDef ellipse fill:#f3e5f5,stroke:#7b1fa2

设计要点：

• 决策点用 diamond，如 Verify fails correctly?
• 动作用 box，如 Write failing test
• 状态用 ellipse，如 Next
• 循环回路清晰可见（RED → GREEN → REFACTOR → RED）

4.4 何时使用流程图

flowchart TD
    A["需要展示信息?"] --> B{"决策点<br/>用户可能走错?"}
    B -->|是| C["使用流程图"]
    B -->|否| D{"是参考材料?"}
    D -->|是| E["使用表格/列表"]
    D -->|否| F{"是线性步骤?"}
    F -->|是| G["使用编号列表"]
    F -->|否| H["使用段落说明"]

流程图适用场景：

• 有循环/回退的流程（如 TDD 的 RED→GREEN→REFACTOR）
• 有决策分支（验证通过？继续：返回）
• 用户容易在某个点停下来或跳过

不适用场景：

# ❌ 错误：用流程图展示 API 参数
flowchart TD
    A["参数1: name"] --> B["参数2: age"]
    
# ✅ 正确：用表格
| 参数 | 类型 | 说明 |
|------|------|------|
| name | string | 用户名 |
| age | number | 年龄 |

# ❌ 错误：用流程图展示线性步骤
flowchart TD
    A["Step 1"] --> B["Step 2"] --> C["Step 3"]

# ✅ 正确：用编号列表
1. First, install the package
2. Then, configure the settings
3. Finally, run the application

---

五、技能创建的 TDD 流程

5.1 核心思想

创建技能就是 TDD 应用于过程文档

flowchart LR
    subgraph RED["RED 阶段"]
        A1[运行压力场景<br/>无技能] --> A2[记录失败行为]
    end
    
    subgraph GREEN["GREEN 阶段"]
        B1[写最小技能] --> B2[验证代理合规]
    end
    
    subgraph REFACTOR["REFACTOR 阶段"]
        C1[发现新漏洞] --> C2[堵塞漏洞]
        C2 --> C3[再验证]
    end
    
    RED --> GREEN --> REFACTOR
    REFACTOR --> RED

5.2 TDD 映射表

TDD 概念	技能创建
测试用例	用 subagent 的压力场景
生产代码	SKILL.md 文档
RED（失败）	没有技能时代理违反规则
GREEN（通过）	有技能时代理遵守规则
Refactor	堵塞漏洞，保持合规

5.3 铁律

NO SKILL WITHOUT A FAILING TEST FIRST

必须先运行压力场景（无技能），观察失败行为，再写技能。写技能前测试？删掉重写。

---

六、Token 效率优化

6.1 目标字数

技能类型	目标字数
入门工作流	< 150 词
频繁加载技能	< 200 词
其他技能	< 500 词

6.2 优化技巧

1. 细节移到 --help

# ❌ 列出所有参数
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ 引用帮助
search-conversations supports multiple modes and filters. Run --help for details.

2. 交叉引用而非重复

# ❌ 重复其他技能的内容
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ 引用其他技能
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

3. 一个优秀示例胜过多个平庸示例

# ❌ 5 种语言的平庸示例
example-js.js, example-py.py, example-go.go, example-rb.rb, example-java.java

# ✅ 一个优秀示例
一个完整、可运行、有注释的示例

---

七、文件组织策略

7.1 自包含技能

skill-name/
  SKILL.md    # 所有内容内联

适用于：内容紧凑，无重型参考

7.2 带工具的技能

skill-name/
  SKILL.md      # 概览 + 模式
  example.ts    # 可复用代码

适用于：有可复用的工具代码

7.3 带大量参考的技能

skill-name/
  SKILL.md       # 概览 + 工作流
  reference.md   # API 参考（600+ 行）
  scripts/       # 可执行工具

适用于：参考材料过大

---

八、防止理性化的设计

针对纪律强制型技能（如 TDD），需要防止 AI 找借口跳过流程。

8.1 明确堵塞每个漏洞

Write code before test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete

8.2 处理 "精神 vs 字面" 论点

**Violating the letter of the rules is violating the spirit of the rules.**

8.3 构建理性化表

Excuse	Reality
"Too simple to test"	Simple code breaks. Test takes 30 seconds.
"I'll test after"	Tests passing immediately prove nothing.
"Tests after achieve same goals"	Tests-after = "what does this do?" Tests-first = "what should this do?"
"Already manually tested"	Ad-hoc ≠ systematic. No record, can't re-run.
"Deleting X hours is wasteful"	Sunk cost fallacy. Keeping unverified code is technical debt.

8.4 创建 Red Flags 清单

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "Keep as reference" or "adapt existing code"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

---

九、总结

第二阶段学习，我掌握了技能系统的核心设计：

知识点	核心要点
SKILL.md 结构	简洁的 frontmatter + 清晰的正文层次
三种技能类型	纪律型、技术型、参考型，各有侧重
CSO 原则	description 只描述触发条件，不描述工作流
流程图设计	正确的节点形状 + 清晰的命名规范
TDD 创建流程	先测试（压力场景）再写技能
Token 效率	精简内容、交叉引用、一个优秀示例
防理性化设计	堵塞漏洞、理性化表、Red Flags

下一阶段，将深入学习核心工作流技能，包括 brainstorming、writing-plans、subagent-driven-development 等。

---

参考资料

• Superpowers 源码：github.com/obra/superp…
• 作者博客：blog.fsck.com/2025/10/09/…
• Discord 社区：discord.gg/Jd8Vphy9jq

---

本文是 Superpowers 源码学习系列的第二篇，后续会继续分享学习心得。欢迎关注！