1. 项目概述
在AI工程化领域,Superpowers框架重新定义了"技能"(Skill)的概念本质。不同于传统自由格式的文档,Superpowers将每个技能视为AI Agent与开发者之间的结构化契约。这种设计理念源于对当前LLM应用开发现状的深刻洞察——大多数AI技能系统存在三个关键缺陷:
- 发现机制低效:Agent难以准确判断何时应该调用哪个技能
- 执行不可控:技能内容容易被当作建议而非强制约束
- 资源浪费:无关内容占用宝贵上下文窗口
Superpowers通过严格的协议化设计解决了这些问题。一个典型的Superpowers技能包含三个逻辑层级:
- 发现层(Frontmatter):仅包含技能标识和触发条件描述
- 行为层(正文):详细的操作流程和质量标准
- 资源层(附件):可选的深度参考材料
这种分层结构确保了技能既容易被发现,又能精确控制Agent行为,同时保持上下文的高效利用。下面我们将深入解析这套机制的每个关键组件。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技能目录结构与命名规范
2.1 扁平化目录设计
Superpowers强制采用扁平目录结构,所有技能都直接存放在skills/目录下,禁止嵌套。这种设计带来几个显著优势:
code复制skills/
├── brainstorming/
│ └── SKILL.md
├── test-driven-development/
│ └── SKILL.md
└── systematic-debugging/
├── SKILL.md
└── debug-templates.js
- 扫描效率:Agent可以在O(1)时间内完成全量技能发现
- 引用明确:交叉引用时只需技能名称,无需处理复杂路径
- 维护简单:开发者无需考虑技能分类体系
2.2 命名约定与语义
技能名称采用kebab-case格式(如condition-based-waiting),必须满足:
- 仅包含小写字母、数字和连字符
- 长度控制在3-5个单词内
- 使用动词+名词结构描述核心行为
好的命名应该实现三重功能:
- 唯一标识符:在代码和配置中明确引用
- 搜索关键词:包含Agent可能使用的查询词
- 认知锚点:让人和AI都能从名称理解技能用途
反例:
data-processing(过于宽泛)nodejs_util(包含特殊字符且不明确)
正例:
transform-csv-data(明确动作和对象)handle-api-errors(描述具体场景)
3. Frontmatter元数据设计
3.1 精简的必需字段
每个SKILL.md必须以YAML格式的frontmatter开头,且只允许两个字段:
yaml复制***
name: systematic-debugging
description: Use when encountering any bug, test failure or unexpected behavior, before proposing fixes
***
| 字段 | 约束 | 技术原理 |
|---|---|---|
| name | 匹配目录名,kebab-case | 确保引用一致性 |
| description | 以"Use when"开头,<500字符 | 优化向量搜索效果 |
这种极简设计源于两个工程考量:
- 发现效率:轻量元数据减少每次技能扫描的开销
- 避免泄漏:防止Agent仅凭描述就跳过正文
3.2 Claude搜索优化(CSO)
description字段需要特殊优化以确保被正确发现:
核心原则:描述触发条件而非解决方案
对比示例:
yaml复制# 反例:描述解决方案
description: Use when you need to debug - first check logs, then isolate variables...
# 正例:描述触发条件
description: Use when encountering inconsistent behavior or deviation from expected results
CSO具体技巧包括:
- 使用症状术语而非技术术语(如"竞态条件"而非"setTimeout")
- 包含同义词扩大召回面
- 避免使用绝对化表述(如"always"、"never")
- 保持第三人称视角(与系统提示一致)
4. 技能正文架构
4.1 标准化章节结构
Superpowers推荐以下Markdown结构:
markdown复制# Overview
[核心概念的一句话定义]
# When to Use
- 场景1:...[具体症状]
- 场景2:...[特定错误类型]
- 避免场景:...[误用情况]
# Core Pattern
Before: [问题状态]
After: [解决状态]
[关键转变说明]
# Quick Reference
| 操作 | 命令/代码 |
|------|-----------|
| 检查点A | `validate(args)` |
| 恢复操作 | `rollback()` |
# Implementation
[简短示例]
[链接到详细脚本]
# Common Mistakes
- 错误1:[现象] → [修正方案]
- 错误2:[典型误判] → [验证方法]
4.2 认知负荷管理
针对不同内容类型采用差异化呈现策略:
| 内容类型 | 处理方式 | 示例 |
|---|---|---|
| 核心流程 | 内联详细说明 | 调试步骤的完整决策树 |
| 参考代码 | 链接到外部文件 | 参见scripts/validation.js |
| 复杂逻辑 | 嵌入Graphviz | dot digraph { ... } |
| 参数说明 | 表格呈现 | 参数 |
这种分层处理确保:
- 关键路径保持精简
- 深度信息可按需获取
- Token使用效率最大化
5. 技能间引用机制
5.1 语义化引用规范
Superpowers禁止直接文件引用,强制采用语义化语法:
markdown复制**PREREQUISITE:**
You must understand superpowers:isolation-testing
**RELATED:**
Consider superpowers:fault-injection
这种设计带来三个优势:
- 延迟加载:仅在需要时获取技能内容
- 明确关系:通过前缀区分依赖强度
- 位置透明:不受文件移动影响
5.2 Token成本控制
传统@导入方式的致命缺陷:
| 场景 | 传统方式 | Superpowers方式 |
|---|---|---|
| 引用5个技能 | 立即加载全部内容(5x成本) | 仅加载元数据(1x成本) |
| 实际使用2个 | 已浪费3个技能的Token | 按需加载2个技能 |
实测显示,在复杂技能网络中,这种优化可减少60-80%的上下文浪费。
6. 实战开发建议
6.1 技能类型判别方法
开发新技能时,首先确定其基本类型:
纪律型技能特征:
- 包含"MUST"/"REQUIRED"等强制表述
- 绑定到特定开发阶段
- 示例:
pre-commit-validation
工作流型技能特征:
- 描述任务结构特征
- 包含条件判断逻辑
- 示例:
parallel-task-dispatching
判别流程图:
dot复制digraph {
start [label="新技能"]
decision1 [label="是否绑定到特定阶段?"]
decision2 [label="是否描述任务结构?"]
type1 [label="纪律型",shape=box]
type2 [label="工作流型",shape=box]
type3 [label="混合型",shape=box]
start -> decision1
decision1 -> type1 [label="是"]
decision1 -> decision2 [label="否"]
decision2 -> type2 [label="是"]
decision2 -> type3 [label="否"]
}
6.2 内容拆分策略
根据信息密度决定组织方式:
| 内容体积 | 推荐模式 | 示例 |
|---|---|---|
| <50行代码 | 自包含 | SKILL.md内联所有内容 |
| 50-200行 | 可复用工具 | 主文档+utils/目录 |
200行 | 繁重参考 | 主文档+
reference-*.md
关键原则:
- 保持SKILL.md可快速浏览
- 将示例代码转化为可执行资产
- API文档单独存放
7. 性能优化技巧
7.1 Token预算分配
根据技能使用频率采用差异化的优化策略:
| 技能类型 | 允许长度 | 优化手段 |
|---|---|---|
| 会话启动 | <150字 | 删除所有示例代码 |
| 高频技能 | <200字 | 压缩描述,外链工具 |
| 普通技能 | <500字 | 保持核心流程完整 |
7.2 上下文压缩技术
- 术语标准化:全技能体系使用同一术语表
- 示例最小化:每个概念只保留一个典型示例
- 交叉引用:替代重复内容
- 工具提示:将详细说明移到
--help输出
实测案例:
- 原始技能:1200 tokens
- 优化后:480 tokens (减少60%)
- 效果:保持功能完整性的同时显著提升加载速度
8. 常见问题解决方案
8.1 技能未被调用
排查步骤:
- 检查description是否以"Use when"开头
- 验证触发条件是否使用症状描述而非方案描述
- 确保名称包含常见搜索词
- 测试向量搜索相似度
8.2 Agent跳过正文
解决方案:
- 删除description中的所有解决方案提示
- 在正文开头添加"DO NOT ATTEMPT without reading full spec"
- 将核心步骤分解为必须引用的子技能
8.3 上下文溢出
处理方案:
- 将长示例拆分为独立文件
- 用表格替代段落描述
- 删除历史变更记录等非必要内容
- 对参考文档进行分块(chunking)
9. 演进路线建议
随着技能库增长,建议采用以下演进策略:
| 阶段 | 重点 | 关键指标 |
|---|---|---|
| 0-10个技能 | 建立核心纪律 | 调用准确率 |
| 10-30个 | 优化发现机制 | 搜索响应时间 |
| 30+个 | 构建技能网络 | 交叉引用密度 |
| 50+个 | 自动化质量检查 | 静态分析覆盖率 |
进阶技巧:
- 建立技能依赖图
- 开发自动化测试工具
- 实施变更影响分析
- 监控Token使用效率
在开发过程中,我深刻体会到结构化契约与传统文档的关键区别在于约束力。好的Superpowers技能就像精心设计的API接口 - 它既提供明确的调用规范,又保留足够的实现灵活性。最难把握的是description字段的编写艺术:要在17个单词内准确描述触发条件,同时不泄露实现细节,这需要反复的测试和调优。
