Superpowers的SKILL规范的实用使用教程
百度首页
请帮我写一篇关于"Superpowers的SKILL规范"的完整技术文章，严格按照以下结构直接输出：
Superpowers的SKILL规范完整指南
一、引言
（简要介绍Superpowers的SKILL规范的重要性和应用场景）
二、基础概念
（详细解释Superpowers的SKILL规范的核心概念和基本用法，配合代码示例）
三、实战应用
（通过具体示例演示Superpowers的SKILL规范的实际应用，每个示例都要有完整的代码和详细说明）
四、常见问题与解决方案
（列出使用Superpowers的SKILL规范时可能遇到的问题及解决方案）
五、总结
（总结文章要点）
重要要求：
- 直接输出文章，不要任何思考过程、搜索过程、学习建议或额外说明
- 每个章节都要有详细的代码示例和说明
- 使用Markdown格式
- 文章要结构完整、内容详实
- 不要添加"学习建议"、"AI生成"等标记
DS-V4 Pro
共参考30篇资料
调用工具
全球搜
搜索全球29篇资料
How to Write Custom Superpowers Skills | BSWEN-docs.bswen.com
GitHub - obra/superpowers: An agentic skills framework & software development methodology that works. · GitHub-GitHub
GitHub - netosw/superpowers: An agentic skills framework & software development methodology that works. · GitHub-GitHub
Super Robot Wars/BX/Skill Parts - Akurasu Wiki-akurasu.net
superpowers-usage-guide-CSDN博客
第三章:Skill 机制与 using-superpowers-博客园
superpowers skill是干什么-爱企查
34k Star!Claude skills项目superpowers开源,让智能体写出工程规范级代码-智猩猩
Superpowers 技能体系完全指南:用工程化方法论驾驭 AI 编程-CSDN博客
Superpowers 完全指南:从安装到自定义技能,看 6 如何让 AI 自己优化自己-CSDN博客-CSDN博客
11.
Superpowers 官方全技能详解 + 场景化组合使用指南-腾讯云
12.
Superpowers Skills 上手清单 + 完整指南-CSDN博客
13.
Superpowers 高级技能详解:每个技能配真实示例,让 Claude 成为工程级开发伙伴-腾讯云
14.
前面拷打需求两小时,后面执行只花 10 分钟:Superpowers 的真实体验-腾讯云
15.
Superpowers 核心原理与高阶使用技巧-腾讯云
16.
Superpowers 原理解析:它如何把“会写代码的模型”变成“可交付的软件工程流程”-developer.cloud.tencent.com
17.
给Claude Code 装上“超能力“:Superpowers 插件完整介绍与上手教程-CSDN博客
18.
Superpowers-CSDN博客
19.
【高级】Superpowers 高级技巧:如何自定义你的专属 Skill-CSDN博客
20.
【Skill】Superpowers 常用命令与使用场景-CSDN博客
21.
Superpowers使用方法-布鲁艾斯
22.
superpowers 插件使用指南-CSDN博客
23.
Superpowers 技能使用简介_superpowerskills使用教程-CSDN博客-CSDN博客
24.
Superpowers 使用指南-CSDN博客
25.
Superpowers 让 Claude Code 成为你的专家级助手-稀土掘金
26.
skill-Superpowers_superpowers skill是干嘛的-CSDN博客-CSDN博客
27.
Superpowers Skill - 让 Claude Code 和 Codex 按工程流程做开发-沐风
28.
CodeBuddy 生态 MCP、Skill、OpenSpec、Superpowers 全梳理博客文稿-CSDN博客
29.
开源AI编程工具对决:Superpowers技能库与OpenSpec规范驱动,谁更胜一筹?-全世界
Superpowers的SKILL规范完整指南
一、引言
在AI辅助编程日益普及的今天，开发者面临一个核心挑战：如何让AI助手不仅“会写代码”，更能“像一个资深工程师一样思考”？Superpowers项目正是为解决这一问题而生。它是一套结构化开发工作流的技能集合，通过向AI编程助手注入一系列遵循严格规范的SKILL文件，强制其遵循专业开发流程。
SKILL规范是Superpowers的核心灵魂。它定义了如何将人类工程师数十年沉淀的方法论——测试驱动开发、系统化调试、先规划后执行——转化为机器可读的Markdown文件。这些文件不是简单的提示词，而是一套完整的“方法论即代码”体系。掌握SKILL规范，意味着你能够将任意开发流程固化为可复用的AI行为准则，让AI助手从“智能补全”蜕变为“工程伙伴”。
二、基础概念
2.1 SKILL的定义与边界
在Superpowers体系中，一个SKILL是一个参考指南，用于描述经过验证的技术、模式或工具。理解SKILL“是什么”和“不是什么”至关重要：
SKILL是：
可复用的技术
思维模式
参考指南
工具文档
SKILL不是：
关于你如何解决某个问题的叙事
项目特定的约定（这些应放在CLAUDE.md中）
可以用正则表达式或验证自动化的事物
这个边界定义确保了SKILL专注于可迁移的方法论，而非一次性的经验记录。
2.2 SKILL文件的基本结构
每个SKILL文件遵循特定的结构规范，核心组成部分包括：
markdown
description: 触发条件描述
技能名称
Iron Law（铁律）
不可违反的核心原则，通常以大写字母标注。
Red Flags（红旗清单）
触发该技能时必须警惕的常见问题模式。
执行流程
阶段一：准备阶段
具体步骤说明…
阶段二：执行阶段
具体步骤说明…
成功标准
明确完成该技能应达到的标准。
2.3 YAML Frontmatter元数据
SKILL文件的头部使用YAML frontmatter定义元数据，其中description字段最为关键——它不是简单的说明文字，而是一段“触发指令”：
yaml
description: “当用户提出新功能需求、需要头脑风暴或设计方案时使用。触发关键词：新功能、设计方案、头脑风暴、需求分析”
当AI助手扫描所有可用技能时，会匹配当前任务上下文与description字段。一旦命中，该技能将被强制激活且不可绕过。
2.4 Iron Law与Red Flags的设计模式
这是SKILL规范中最具特色的设计模式。以调试技能为例：
markdown
Iron Law
找到根因之前，不允许提修复方案。
Red Flags
- 看到错误信息就立即猜测原因
- 跳过复现步骤直接修改代码
- 同时尝试多个修复方案
- 不检查最近的代码变更
Iron Law是绝对不可违反的底线，Red Flags则帮助AI识别常见的错误倾向。这种设计将“纪律”注入AI的行为模式。
2.5 渐进式披露机制
SKILL规范采用渐进式披露设计，避免上下文窗口被无关内容污染：
markdown
Session-Start Hook 示例
在会话启动时，系统注入一个极小的Hook（<2000 tokens）：
“请优先读取 getting-started/SKILL.md 文件，
该文件将告知你何时调用哪个技能。”
getting-started/SKILL.md 内容片段
何时使用各技能
- 当用户提出新功能需求时 → 调用 /brainstorming
- 当设计方案已批准时 → 调用 /writing-plans
- 当遇到Bug时 → 调用 /systematic-debugging
Hook本身不包含完整的方法论指令，而是一个“书签”，指向具体的技能文件。这种设计使得AI只在需要时才加载详细内容。
三、实战应用
3.1 示例一：创建头脑风暴技能
以下是一个完整的头脑风暴技能实现，展示SKILL规范的核心要素：
markdown
description: “当用户提出新功能需求、需要设计方案或开始任何新需求时使用。触发关键词：新功能、设计方案、头脑风暴、需求分析、功能规划”
Brainstorming（头脑风暴）
Iron Law
在用户批准设计方案之前，绝对不能写任何代码。
Red Flags
- 听到需求就立即开始写代码
- 跳过需求澄清直接设计方案
- 只提供一个方案，不给用户选择空间
- 设计方案未经用户确认就开始实施
执行流程
阶段一：了解现状
- 读取项目相关文件，了解当前架构
- 检查现有文档和最近提交记录
- 识别可能受影响的模块
执行指令：
请先阅读以下文件以了解项目现状：
README.md
docs/architecture.md
最近10次git提交记录
text
阶段二：需求澄清
逐个提问澄清需求，一次只问一个问题：
示例提问序列：
- “这个功能的核心目标是什么？请用一句话描述。”
- “主要面向哪些用户群体？”
- “是否有性能或兼容性方面的特殊要求？”
- “预期完成时间是否有约束？”
阶段三：方案设计
提出2-3种方案，每种方案包含：
- 技术路线说明
- 优缺点分析
- 预估工作量
- 潜在风险
方案对比模板：
## 方案A：[方案名称] - 技术路线：[简要说明] - 优点：[列出2-3个核心优势] - 缺点：[列出2-3个主要劣势] - 工作量预估：[人天] - 风险点：[关键风险] ## 方案B：[方案名称] （同上结构） 阶段四：方案确认 呈现设计方案并获取用户批准 将验证后的设计文档保存到 docs/superpowers/specs/ 完成后自动调用 /writing-plans 成功标准 用户明确批准了某个设计方案 设计文档已保存到指定路径 所有澄清问题都得到了明确回答 text ### 3.2 示例二：实现测试驱动开发技能 测试驱动开发是Superpowers中最具纪律性的技能之一： ```markdown --- description: "当需要编写任何生产代码时使用。触发关键词：写代码、实现功能、开发、编写函数、创建模块" --- # Test-Driven Development（测试驱动开发） ## Iron Law ‌**没有先写失败测试，就不能写生产代码。**‌ ## Red Flags - 先写实现代码再补测试 - 跳过"验证测试确实失败"这一步 - 测试覆盖不完整就认为功能完成 - 重构时不同步更新测试 ## 执行流程：红-绿-重构循环 ### RED阶段：编写失败测试 ```python # 示例：为待实现的用户验证函数编写测试 import pytest def test_validate_email_valid(): """测试有效的邮箱地址""" result = validate_email("user@example.com") assert result == True def test_validate_email_invalid(): """测试无效的邮箱地址""" result = validate_email("invalid-email") assert result == False def test_validate_email_empty(): """测试空字符串""" result = validate_email("") assert result == False # 此时运行测试应该失败，因为validate_email函数尚未实现 验证测试确实失败： bash $ pytest test_email.py FAILED test_validate_email_valid - NameError: name 'validate_email' is not defined FAILED test_validate_email_invalid - NameError: name 'validate_email' is not defined FAILED test_validate_email_empty - NameError: name 'validate_email' is not defined GREEN阶段：最简实现 python import re def validate_email(email): """验证邮箱地址格式""" if not email: return False pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' return bool(re.match(pattern, email)) 验证测试通过： bash $ pytest test_email.py ... 3 passed in 0.05s REFACTOR阶段：优化代码 python import re from typing import Pattern class EmailValidator: """邮箱验证器，支持自定义验证规则""" EMAIL_PATTERN: Pattern = re.compile( r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' @classmethod def validate(cls, email: str) -> bool: """验证邮箱地址格式""" if not email: return False return bool(cls.EMAIL_PATTERN.match(email)) # 保持向后兼容的函数接口 def validate_email(email: str) -> bool: return EmailValidator.validate(email) 重构后重新运行测试确保仍然通过： bash $ pytest test_email.py ... 3 passed in 0.05s 成功标准 所有测试用例通过 代码覆盖率满足项目要求 重构后测试仍然全部通过 text ### 3.3 示例三：系统化调试技能 这是Superpowers中最能体现“方法论即代码”理念的技能： ```markdown --- description: "当遇到任何bug、测试失败或意外行为时使用。触发关键词：bug、报错、异常、不工作、出问题、测试失败、错误" --- # Systematic Debugging（系统化调试） ## Iron Law ‌**找到根因之前，不允许提修复方案。**‌ ## Red Flags - 看到错误信息就立即猜测原因 - 跳过复现步骤直接修改代码 - 同时尝试多个修复方案 - 不检查最近的代码变更 ## 执行流程 ### 阶段一：根因调查 1. 完整读取错误信息和堆栈跟踪 2. 稳定复现问题（至少3次） 3. 检查最近的代码变更 ```bash # 查看最近变更 git log --oneline -10 # 查看特定文件的变更历史 git log -p -- path/to/suspicious/file.py # 使用git bisect定位引入问题的提交 git bisect start git bisect bad HEAD git bisect good <已知正常的提交> 追踪数据流，确定问题发生的完整路径 python # 添加调试日志追踪数据流 import logging logging.basicConfig(level=logging.DEBUG) def process_order(order_data): logging.debug(f"输入数据: {order_data}") validated = validate_order(order_data) logging.debug(f"验证后数据: {validated}") total = calculate_total(validated) logging.debug(f"计算结果: {total}") return total 阶段二：模式分析 找到代码库中类似的工作示例 对比差异，确定不同之处 python # 对比正常工作的代码 def calculate_discount_normal(price, user_level): """正常工作的折扣计算""" if user_level == "vip": return price * 0.8 elif user_level == "regular": return price * 0.95 return price # 有问题的代码 def calculate_discount_buggy(price, user_level): """有Bug的折扣计算""" if user_level == "vip": return price * 0.8 elif user_level == "regular": return price * 0.95 # 缺少默认返回值，当user_level为None时返回None 阶段三：假设与验证 提出单一假设 最小化验证 python # 假设：user_level为None时函数返回None导致后续计算错误 # 最小化验证 def test_hypothesis(): result = calculate_discount_buggy(100, None) print(f"当user_level为None时的返回值: {result}") # 输出: None - 假设得到验证 test_hypothesis() 阶段四：修复实现 先写失败测试 python def test_calculate_discount_with_none_level(): """测试user_level为None的情况""" result = calculate_discount(100, None) assert result == 100 # 期望原价返回 def test_calculate_discount_with_empty_string(): """测试user_level为空字符串的情况""" result = calculate_discount(100, "") assert result == 100 修复代码 python def calculate_discount(price, user_level): """计算折扣价格""" if not user_level: # 处理None和空字符串 return price if user_level == "vip": return price * 0.8 elif user_level == "regular": return price * 0.95 return price 验证修复 bash $ pytest test_discount.py -v test_calculate_discount_with_none_level PASSED test_calculate_discount_with_empty_string PASSED test_calculate_discount_vip PASSED test_calculate_discount_regular PASSED 成功标准 根因已明确识别并记录 修复方案已通过测试验证 所有相关测试用例通过 问题不再复现 text ## 四、常见问题与解决方案 ### 4.1 技能未被自动触发 ‌**问题描述**‌：AI助手没有按照预期自动激活某个技能。 ‌**原因分析**‌：description字段的触发关键词不够精确，或与当前上下文匹配度不足。 ‌**解决方案**‌： ```yaml # 不够精确的description description: "用于调试" # 改进后的description description: "当遇到任何bug、测试失败、运行时错误或意外行为时使用。触发关键词：bug、报错、异常、不工作、出问题、测试失败、错误、崩溃、闪退" 验证方法：在会话开始时显式调用技能，观察AI是否能够正确识别后续的触发场景。 bash # 显式调用以确保技能加载 /using-superpowers 4.2 Iron Law被绕过 问题描述：AI在某些情况下绕过了Iron Law的约束。 原因分析：Iron Law的表述不够绝对，或缺少Red Flags的辅助约束。 解决方案：强化Iron Law的表述，并补充对应的Red Flags。 markdown # 弱约束版本 ## Iron Law 应该先写测试再写代码。 # 强化版本 ## Iron Law ‌**没有先写失败测试，就不能写生产代码。此规则在任何情况下都不可违反。**‌ ## Red Flags - 产生"这个功能很简单，不需要测试"的想法 - 以"先快速验证思路"为由跳过测试 - 在测试失败前就开始编写实现代码 - 认为"稍后补测试"是可以接受的 4.3 技能文件过于冗长导致上下文溢出 问题描述：技能文件内容过多，消耗了大量上下文窗口。 原因分析：将过多细节和示例直接写入技能文件，未使用渐进式披露。 解决方案：采用分层设计，技能文件只保留核心流程，详细示例放在独立文档中。 markdown # 技能文件中的引用方式 ## 详细示例 完整的代码示例请参考： - `skills/brainstorming/examples/feature-request.md` - `skills/brainstorming/examples/bug-fix.md` 当前技能文件只保留核心流程和关键约束。 4.4 多个技能的执行顺序混乱 问题描述：AI在应该执行技能A时跳到了技能C，导致流程混乱。 原因分析：技能之间的转换条件不够明确。 解决方案：在每个技能的结尾明确指定下一步动作。 markdown # 在brainstorming技能末尾 ## 完成后的下一步 设计方案经用户批准后，‌**必须**‌立即调用 `/writing-plans` 技能， 不得跳过此步骤直接开始编码。 调用方式： /writing-plans text # 在writing-plans技能末尾 ## 完成后的下一步 计划编写完成后，向用户提供两种执行方式选择： 1. Subagent-Driven（推荐）：调用 `/subagent-driven-development` 2. Inline Execution：调用 `/executing-plans` 等待用户选择后再继续。 4.5 测试覆盖不足 问题描述：按照TDD技能执行后，测试覆盖率仍然不足。 原因分析：技能中的测试要求不够具体，缺少边界情况的指导。 解决方案：在技能中明确测试用例的类型要求。 markdown ## 测试用例完整性检查清单 每个功能的测试必须覆盖以下类型： - [ ] 正常情况（Happy Path） - [ ] 边界值（Boundary Values） - [ ] 异常输入（Invalid Input） - [ ] 空值处理（Null/Empty Handling） - [ ] 并发场景（如果适用） 示例： ```python # 字符串处理函数的完整测试 def test_reverse_string(): # 正常情况 assert reverse_string("hello") == "olleh" # 边界值 assert reverse_string("a") == "a" assert reverse_string("ab") == "ba" # 异常输入 with pytest.raises(TypeError): reverse_string(None) # 空值处理 assert reverse_string("") == "" text ## 五、总结 Superpowers的SKILL规范代表了一种全新的AI辅助编程范式——将软件工程方法论以结构化、可执行的方式注入AI助手。通过本文的深入探讨，我们可以总结出以下核心要点： ‌**第一，SKILL是“纪律”而非“能力”**‌。AI助手本身已经具备规划、调试、重构等能力，SKILL规范的价值在于将这些能力组织成有序的、可预测的、不可跳过的工作流。Iron Law和Red Flags的设计模式是实现这一目标的关键机制。 ‌**第二，渐进式披露是高效上下文管理的基础**‌。通过将技能文件设计为分层结构，Hook只包含指向性信息，详细内容按需加载，SKILL规范在保证功能完整性的同时，最大限度地节约了上下文窗口。 ‌**第三，测试驱动开发是SKILL规范的核心实践**‌。“没有先写失败测试，就不能写生产代码”这一铁律，将质量保障从“事后检查”转变为“事前约束”，从根本上改变了AI的代码生成行为。 ‌**第四，系统化调试体现了“方法论即代码”的理念**‌。通过将调试过程分解为根因调查、模式分析、假设验证、修复实现四个阶段，并严格规定“找到根因之前不允许提修复方案”，SKILL规范将人类专家的调试思维固化为机器可执行的流程。 ‌**第五，SKILL规范具有良好的可扩展性**‌。任何团队都可以基于这套规范，将自己独特的开发流程、最佳实践和质量标准封装为自定义技能，实现团队工程文化的标准化和自动化。 掌握SKILL规范，意味着你不再只是“使用AI写代码”，而是“教会AI如何像一个资深工程师一样工作”。这不仅提升了开发效率，更重要的是，它确保了代码质量、流程纪律和团队协作的一致性。随着AI编程工具的持续演进，SKILL规范所代表的“方法论即代码”理念，将成为AI辅助软件开发的基础设施。 请直接输出完整的文章正文内容，不要生成目录或大纲格式。用完整的段落、代码示例和详细说明来展开每个章节。 DS-V4 Pro 为你解答 Superpowers的SKILL规范完整指南 一、引言 在AI辅助编程工具日益普及的今天，开发者们面临着一个共同的困境：AI助手确实能快速生成代码，但这些代码往往缺乏工程纪律性。它们会跳过测试直接写实现，会凭直觉猜测Bug的原因而不去系统化排查，会在需求尚不明确时就急于动手编码。这些问题本质上不是AI能力的缺失，而是工作流程的缺失。 Superpowers项目正是为解决这一根本性问题而诞生的。它是一套开源的结构化开发工作流技能集合，通过向AI编程助手注入一系列遵循严格规范的SKILL文件，强制其遵循专业开发流程。SKILL规范是Superpowers的核心灵魂，它定义了一套将人类工程师数十年沉淀的方法论——测试驱动开发、系统化调试、先规划后执行——转化为机器可读的Markdown文件的标准。 这套规范的设计哲学可以概括为“方法论即代码”。传统的提示词工程试图通过自然语言描述来引导AI行为，但这种方式存在两个致命缺陷：一是约束力不足，AI可以轻易绕过模糊的指令；二是不可复用，每次对话都需要重新描述相同的流程。SKILL规范通过结构化的文件格式、强制性的Iron Law机制和渐进式的上下文加载策略，彻底解决了这些问题。掌握SKILL规范，意味着你能够将任意开发流程固化为可复用的AI行为准则，让AI助手从“智能补全工具”蜕变为真正的“工程伙伴”。 二、基础概念 理解SKILL规范的核心在于把握三个关键概念：SKILL的边界定义、文件的结构设计，以及渐进式披露机制。这三个概念共同构成了SKILL规范的理论基础。 首先是SKILL的边界定义。在Superpowers体系中，一个SKILL被明确定义为“描述经过验证的技术、模式或工具的参考指南”。这个定义看似简单，却蕴含着重要的边界意识。SKILL必须是可复用的技术，而不是一次性的经验记录；它描述的是思维模式，而不是具体的项目约定；它提供的是参考指南，而不是可以自动化的验证规则。举例来说，“如何使用Git进行版本控制”是一个合格的SKILL，因为它描述的是可复用的技术；“上周修复登录Bug的过程记录”则不是，因为它只是特定项目的叙事。这种边界定义确保了每个SKILL都具有跨项目、跨场景的迁移价值。 其次是SKILL文件的结构设计。每个SKILL文件遵循一套固定的结构规范，核心组成部分包括YAML frontmatter元数据、Iron Law铁律、Red Flags红旗清单、分阶段执行流程和成功标准。YAML frontmatter中的description字段尤为关键，它不是简单的说明文字，而是一段“触发指令”。当AI助手扫描所有可用技能时，会匹配当前任务上下文与description字段，一旦命中，该技能将被强制激活且不可绕过。例如，一个调试技能的description可能写为：“当遇到任何bug、测试失败或意外行为时使用。触发关键词：bug、报错、异常、不工作、出问题。”这种设计使得技能的触发不再依赖用户的显式调用，而是由上下文自动驱动。 Iron Law和Red Flags是SKILL规范中最具特色的设计模式。Iron Law是技能执行过程中绝对不可违反的核心原则，通常以大写字母标注以增强视觉权重。Red Flags则是一组需要警惕的常见问题模式，帮助AI识别错误的倾向。以测试驱动开发技能为例，其Iron Law是“没有先写失败测试，就不能写生产代码”，对应的Red Flags包括“产生‘这个功能很简单，不需要测试’的想法”、“以‘先快速验证思路’为由跳过测试”等。这种设计将工程纪律以结构化的方式注入AI的行为模式，使得约束不再是模糊的建议，而是明确的规则。 最后是渐进式披露机制。这是SKILL规范解决上下文窗口限制问题的关键设计。在会话启动时，系统只注入一个极小的Hook文件，通常不超过2000个token。这个Hook不包含完整的方法论指令，而是一个“书签”，告知AI在何种情况下应该读取哪个具体的技能文件。例如，Hook可能包含这样的指令：“当用户提出新功能需求时，请读取/brainstorming技能文件”。只有当触发条件满足时，AI才会加载完整的技能内容。这种设计使得AI在不需要时不会消耗上下文窗口，而在需要时又能获得完整的指导。 下面是一个完整的SKILL文件结构示例，展示了这些概念如何组合在一起： markdown --- description: "当用户提出新功能需求、需要头脑风暴或设计方案时使用。触发关键词：新功能、设计方案、头脑风暴、需求分析" --- # Brainstorming（头脑风暴） ## Iron Law ‌**在用户批准设计方案之前，绝对不能写任何代码。**‌ ## Red Flags - 听到需求就立即开始写代码 - 跳过需求澄清直接设计方案 - 只提供一个方案，不给用户选择空间 - 设计方案未经用户确认就开始实施 ## 执行流程 ### 阶段一：了解现状 1. 读取项目相关文件，了解当前架构 2. 检查现有文档和最近提交记录 3. 识别可能受影响的模块 执行指令： 请先阅读以下文件以了解项目现状： README.md docs/architecture.md 最近10次git提交记录 text ### 阶段二：需求澄清 逐个提问澄清需求，一次只问一个问题： 示例提问序列： 1. "这个功能的核心目标是什么？请用一句话描述。" 2. "主要面向哪些用户群体？" 3. "是否有性能或兼容性方面的特殊要求？" 4. "预期完成时间是否有约束？" ### 阶段三：方案设计 提出2-3种方案，每种方案包含： - 技术路线说明 - 优缺点分析 - 预估工作量 - 潜在风险 方案对比模板： ```markdown ## 方案A：[方案名称] - 技术路线：[简要说明] - 优点：[列出2-3个核心优势] - 缺点：[列出2-3个主要劣势] - 工作量预估：[人天] - 风险点：[关键风险] 阶段四：方案确认 呈现设计方案并获取用户批准 将验证后的设计文档保存到 docs/superpowers/specs/ 完成后自动调用 /writing-plans 成功标准 用户明确批准了某个设计方案 设计文档已保存到指定路径 所有澄清问题都得到了明确回答 text 这个示例展示了SKILL规范的完整结构：frontmatter定义触发条件，Iron Law设定不可逾越的底线，Red Flags列出需要警惕的行为模式，分阶段的执行流程提供具体的操作指导，成功标准则定义了技能完成的判定依据。 ## 三、实战应用 理论的价值在于指导实践。本节通过三个完整的实战示例，展示SKILL规范在不同开发场景中的具体应用。每个示例都包含完整的技能文件内容和详细的执行说明。 ### 3.1 头脑风暴技能的完整实现 头脑风暴是开发流程的起点，也是最容易出问题的环节。开发者常常在需求尚不明确时就急于动手编码，导致返工和方向性错误。以下是一个完整的头脑风暴技能实现： ```markdown --- description: "当用户提出新功能需求、需要设计方案或开始任何新需求时使用。触发关键词：新功能、设计方案、头脑风暴、需求分析、功能规划" --- # Brainstorming（头脑风暴） ## Iron Law ‌**在用户批准设计方案之前，绝对不能写任何代码。**‌ ## Red Flags - 听到需求就立即开始写代码 - 跳过需求澄清直接设计方案 - 只提供一个方案，不给用户选择空间 - 设计方案未经用户确认就开始实施 ## 执行流程 ### 阶段一：了解现状 在开始任何设计工作之前，必须充分了解项目的当前状态。这包括读取项目的核心文档、了解架构设计、检查最近的代码变更。 1. 读取项目相关文件，了解当前架构 2. 检查现有文档和最近提交记录 3. 识别可能受影响的模块 执行指令： 请先阅读以下文件以了解项目现状： README.md docs/architecture.md 最近10次git提交记录 text ### 阶段二：需求澄清 采用逐个提问的方式澄清需求，每次只问一个问题，避免信息过载。这种渐进式的提问策略能够帮助用户更清晰地表达需求。 示例提问序列： 1. "这个功能的核心目标是什么？请用一句话描述。" 2. "主要面向哪些用户群体？" 3. "是否有性能或兼容性方面的特殊要求？" 4. "预期完成时间是否有约束？" ### 阶段三：方案设计 基于澄清后的需求，提出2-3种技术方案。每种方案都需要包含完整的技术路线说明、优缺点分析、工作量预估和潜在风险。这种多方案对比的方式能够帮助用户做出更明智的决策。 方案对比模板： ```markdown ## 方案A：[方案名称] - 技术路线：[简要说明] - 优点：[列出2-3个核心优势] - 缺点：[列出2-3个主要劣势] - 工作量预估：[人天] - 风险点：[关键风险] ## 方案B：[方案名称] （同上结构） 阶段四：方案确认 设计方案必须经过用户的明确批准才能进入实施阶段。批准后的设计文档需要保存到指定路径，作为后续开发的依据。 呈现设计方案并获取用户批准 将验证后的设计文档保存到 docs/superpowers/specs/ 完成后自动调用 /writing-plans 成功标准 用户明确批准了某个设计方案 设计文档已保存到指定路径 所有澄清问题都得到了明确回答 text 这个技能的核心价值在于强制建立了“先思考后行动”的纪律。Iron Law“在用户批准设计方案之前，绝对不能写任何代码”看似简单，但在实际执行中，AI助手往往会因为用户的模糊描述就急于生成代码。通过将这个原则写入技能文件并设置为不可违反的铁律，AI的行为模式发生了根本性的改变。 ### 3.2 测试驱动开发技能的完整实现 测试驱动开发是Superpowers中最具纪律性的技能，也是最能体现“方法论即代码”理念的实践。以下是一个完整的TDD技能实现： ```markdown --- description: "当需要编写任何生产代码时使用。触发关键词：写代码、实现功能、开发、编写函数、创建模块" --- # Test-Driven Development（测试驱动开发） ## Iron Law ‌**没有先写失败测试，就不能写生产代码。**‌ ## Red Flags - 先写实现代码再补测试 - 跳过"验证测试确实失败"这一步 - 测试覆盖不完整就认为功能完成 - 重构时不同步更新测试 ## 执行流程：红-绿-重构循环 ### RED阶段：编写失败测试 在编写任何生产代码之前，必须先编写测试用例。这些测试用例在当前阶段必须失败，因为它们测试的功能尚未实现。 ```python # 示例：为待实现的用户验证函数编写测试 import pytest def test_validate_email_valid(): """测试有效的邮箱地址""" result = validate_email("user@example.com") assert result == True def test_validate_email_invalid(): """测试无效的邮箱地址""" result = validate_email("invalid-email") assert result == False def test_validate_email_empty(): """测试空字符串""" result = validate_email("") assert result == False # 此时运行测试应该失败，因为validate_email函数尚未实现 验证测试确实失败： bash $ pytest test_email.py FAILED test_validate_email_valid - NameError: name 'validate_email' is not defined FAILED test_validate_email_invalid - NameError: name 'validate_email' is not defined FAILED test_validate_email_empty - NameError: name 'validate_email' is not defined GREEN阶段：最简实现 编写刚好能让测试通过的最简代码。这个阶段的代码不需要考虑优化和重构，唯一的目标是让所有测试变绿。 python import re def validate_email(email): """验证邮箱地址格式""" if not email: return False pattern = r'a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' return bool(re.match(pattern, email)) 验证测试通过： bash $ pytest test_email.py ... 3 passed in 0.05s REFACTOR阶段：优化代码 在测试全部通过的保护下，对代码进行重构优化。重构的目标是改善代码结构、提升可维护性，但不改变外部行为。 python import re from typing import Pattern class EmailValidator: """邮箱验证器，支持自定义验证规则""" EMAIL_PATTERN: Pattern = re.compile( r'a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' @classmethod def validate(cls, email: str) -> bool: """验证邮箱地址格式""" if not email: return False return bool(cls.EMAIL_PATTERN.match(email)) # 保持向后兼容的函数接口 def validate_email(email: str) -> bool: return EmailValidator.validate(email) 重构后重新运行测试确保仍然通过： bash $ pytest test_email.py ... 3 passed in 0.05s 成功标准 所有测试用例通过 代码覆盖率满足项目要求 重构后测试仍然全部通过 text 这个技能的核心价值在于将质量保障从“事后检查”转变为“事前约束”。传统的开发流程中，测试往往是最后一步，甚至被省略。TDD技能通过Iron Law“没有先写失败测试，就不能写生产代码”强制改变了这个顺序，使得测试成为开发的前置条件而非后置任务。 ### 3.3 系统化调试技能的完整实现 调试是开发过程中最考验思维严谨性的环节。面对Bug，开发者常常凭直觉猜测原因，东试一下西改一下，最终可能碰巧解决了问题，却没有真正理解根因。系统化调试技能通过结构化的流程设计，将调试从“猜测游戏”转变为“科学实验”。 ```markdown --- description: "当遇到任何bug、测试失败或意外行为时使用。触发关键词：bug、报错、异常、不工作、出问题、测试失败、错误" --- # Systematic Debugging（系统化调试） ## Iron Law ‌**找到根因之前，不允许提修复方案。**‌ ## Red Flags - 看到错误信息就立即猜测原因 - 跳过复现步骤直接修改代码 - 同时尝试多个修复方案 - 不检查最近的代码变更 ## 执行流程 ### 阶段一：根因调查 调试的第一步不是猜测，而是收集证据。这包括完整读取错误信息、稳定复现问题、检查最近的代码变更。 1. 完整读取错误信息和堆栈跟踪 2. 稳定复现问题（至少3次） 3. 检查最近的代码变更 ```bash # 查看最近变更 git log --oneline -10 # 查看特定文件的变更历史 git log -p -- path/to/suspicious/file.py # 使用git bisect定位引入问题的提交 git bisect start git bisect bad HEAD git bisect good <已知正常的提交> 追踪数据流，确定问题发生的完整路径 python # 添加调试日志追踪数据流 import logging logging.basicConfig(level=logging.DEBUG) def process_order(order_data): logging.debug(f"输入数据: {order_data}") validated = validate_order(order_data) logging.debug(f"验证后数据: {validated}") total = calculate_total(validated) logging.debug(f"计算结果: {total}") return total 阶段二：模式分析 找到代码库中正常工作的类似示例，通过对比差异来缩小问题范围。这种方法比凭空猜测要高效得多。 找到代码库中类似的工作示例 对比差异，确定不同之处 python # 对比正常工作的代码 def calculate_discount_normal(price, user_level): """正常工作的折扣计算""" if user_level == "vip": return price * 0.8 elif user_level == "regular": return price * 0.95 return price # 有问题的代码 def calculate_discount_buggy(price, user_level): """有Bug的折扣计算""" if user_level == "vip": return price * 0.8 elif user_level == "regular": return price * 0.95 # 缺少默认返回值，当user_level为None时返回None 阶段三：假设与验证 基于收集到的证据提出单一假设，然后通过最小化的实验来验证。每次只验证一个假设，避免多变量干扰。 提出单一假设 最小化验证 python # 假设：user_level为None时函数返回None导致后续计算错误 # 最小化验证 def test_hypothesis(): result = calculate_discount_buggy(100, None) print(f"当user_level为None时的返回值: {result}") # 输出: None - 假设得到验证 test_hypothesis() 阶段四：修复实现 在根因确认后，遵循TDD原则进行修复：先写失败测试，再实现修复，最后验证。 先写失败测试 python def test_calculate_discount_with_none_level(): """测试user_level为None的情况""" result = calculate_discount(100, None) assert result == 100 # 期望原价返回 def test_calculate_discount_with_empty_string(): """测试user_level为空字符串的情况""" result = calculate_discount(100, "") assert result == 100 修复代码 python def calculate_discount(price, user_level): """计算折扣价格""" if not user_level: # 处理None和空字符串 return price if user_level == "vip": return price * 0.8 elif user_level == "regular": return price * 0.95 return price 验证修复 bash $ pytest test_discount.py -v test_calculate_discount_with_none_level PASSED test_calculate_discount_with_empty_string PASSED test_calculate_discount_vip PASSED test_calculate_discount_regular PASSED 成功标准 根因已明确识别并记录 修复方案已通过测试验证 所有相关测试用例通过 问题不再复现 text 这个技能的核心价值在于将调试从“艺术”转变为“科学”。Iron Law“找到根因之前，不允许提修复方案”看似限制了效率，实际上避免了大量无效的尝试。通过强制遵循根因调查、模式分析、假设验证、修复实现四个阶段，调试过程变得可预测、可复现、可教学。 ## 四、常见问题与解决方案 在实际使用SKILL规范的过程中，开发者可能会遇到各种问题。本节梳理了五个最常见的问题及其解决方案，帮助读者更顺畅地应用这套规范。 第一个常见问题是技能未被自动触发。AI助手没有按照预期自动激活某个技能，而是按照默认行为模式工作。这个问题的根因通常在于description字段的触发关键词不够精确，或与当前上下文匹配度不足。解决方案是丰富description中的触发关键词，覆盖更多的表达方式。例如，一个调试技能的description如果只写了“用于调试”，AI可能无法识别“出问题了”、“不工作了”这类口语化表达。改进后的description应该写为：“当遇到任何bug、测试失败、运行时错误或意外行为时使用。触发关键词：bug、报错、异常、不工作、出问题、测试失败、错误、崩溃、闪退”。此外，在会话开始时显式调用技能可以帮助AI建立正确的上下文关联。 第二个问题是Iron Law被绕过。在某些情况下，AI会绕过Iron Law的约束，直接跳到后续步骤。这通常是因为Iron Law的表述不够绝对，或者缺少Red Flags的辅助约束。解决方案是强化Iron Law的表述，使用更绝对化的语言，并补充对应的Red Flags来覆盖各种可能的绕过路径。例如，将“应该先写测试再写代码”改为“没有先写失败测试，就不能写生产代码。此规则在任何情况下都不可违反”，同时添加Red Flags如“产生‘这个功能很简单，不需要测试’的想法”、“以‘先快速验证思路’为由跳过测试”等。 第三个问题是技能文件过于冗长导致上下文溢出。当技能文件包含过多的示例代码和详细说明时，会消耗大量上下文窗口，影响AI处理其他任务的能力。解决方案是采用分层设计，技能文件只保留核心流程和关键约束，将详细的代码示例和扩展说明放在独立文档中。在技能文件中使用引用语句指向这些文档，例如：“完整的代码示例请参考skills/brainstorming/examples/feature-request.md”。 第四个问题是多个技能的执行顺序混乱。AI在应该执行技能A时跳到了技能C，导致整个工作流程断裂。这个问题的根因在于技能之间的转换条件不够明确。解决方案是在每个技能的结尾明确指定下一步动作，形成清晰的技能调用链。例如，在头脑风暴技能的末尾添加：“设计方案经用户批准后，必须立即调用/writing-plans技能，不得跳过此步骤直接开始编码”。这种明确的转换指令确保了工作流的连贯性。 第五个问题是测试覆盖不足。按照TDD技能执行后，测试用例虽然通过了，但覆盖率不够，遗漏了边界情况和异常处理。解决方案是在技能中明确测试用例的类型要求，使用检查清单确保完整性。例如，在TDD技能中添加：“每个功能的测试必须覆盖正常情况、边界值、异常输入、空值处理和并发场景（如果适用）”。这种明确的覆盖要求能够引导AI生成更全面的测试用例。 ## 五、总结 Superpowers的SKILL规范代表了一种全新的AI辅助编程范式。它不是简单地告诉AI“要做什么”，而是通过结构化的文件格式、强制性的约束机制和渐进式的上下文管理，将软件工程方法论转化为AI可执行的行为准则。 回顾全文，我们可以提炼出五个核心要点。第一，SKILL的本质是“纪律”而非“能力”。AI助手本身已经具备规划、调试、重构等能力，SKILL规范的价值在于将这些能力组织成有序的、可预测的、不可跳过的工作流。Iron Law和Red Flags的设计模式是实现这一目标的关键机制，它们将模糊的建议转化为明确的规则。 第二，渐进式披露是高效上下文管理的基础。通过将技能文件设计为分层结构，Hook只包含指向性信息，详细内容按需加载，SKILL规范在保证功能完整性的同时，最大限度地节约了上下文窗口。这种设计使得AI能够在不消耗过多资源的情况下，获得完整的流程指导。 第三，测试驱动开发是SKILL规范的核心实践。“没有先写失败测试，就不能写生产代码”这一铁律，将质量保障从“事后检查”转变为“事前约束”，从根本上改变了AI的代码生成行为。红-绿-重构循环为代码质量提供了持续的保护网。 第四，系统化调试体现了“方法论即代码”的理念。通过将调试过程分解为根因调查、模式分析、假设验证、修复实现四个阶段，并严格规定“找到根因之前不允许提修复方案”，SKILL规范将人类专家的调试思维固化为机器可执行的流程。调试不再是凭直觉的猜测，而是可复现的科学实验。 第五，SKILL规范具有良好的可扩展性。任何团队都可以基于这套规范，将自己独特的开发流程、最佳实践和质量标准封装为自定义技能。这种可扩展性使得SKILL规范不仅适用于个人开发者，也适用于需要统一工程标准的团队协作场景。 掌握SKILL规范，意味着你不再只是“使用AI写代码”，而是“教会AI如何像一个资深工程师一样工作”。这不仅提升了开发效率，更重要的是，它确保了代码质量、流程纪律和团队协作的一致性。随着AI编程工具的持续演进，SKILL规范所代表的“方法论即代码”理念，将成为AI辅助软件开发的基础设施，推动整个行业向更高质量、更高效率的方向发展。