百度首页请帮我写一篇关于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.comGitHub - obra/superpowers: An agentic skills framework software development methodology that works. · GitHub-GitHubGitHub - netosw/superpowers: An agentic skills framework software development methodology that works. · GitHub-GitHubSuper Robot Wars/BX/Skill Parts - Akurasu Wiki-akurasu.netsuperpowers-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.com17.给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文件遵循特定的结构规范核心组成部分包括markdowndescription: 触发条件描述技能名称Iron Law铁律不可违反的核心原则通常以大写字母标注。Red Flags红旗清单触发该技能时必须警惕的常见问题模式。执行流程阶段一准备阶段具体步骤说明…阶段二执行阶段具体步骤说明…成功标准明确完成该技能应达到的标准。2.3 YAML Frontmatter元数据SKILL文件的头部使用YAML frontmatter定义元数据其中description字段最为关键——它不是简单的说明文字而是一段“触发指令”yamldescription: “当用户提出新功能需求、需要头脑风暴或设计方案时使用。触发关键词新功能、设计方案、头脑风暴、需求分析”当AI助手扫描所有可用技能时会匹配当前任务上下文与description字段。一旦命中该技能将被强制激活且不可绕过。2.4 Iron Law与Red Flags的设计模式这是SKILL规范中最具特色的设计模式。以调试技能为例markdownIron Law‌找到根因之前不允许提修复方案。‌Red Flags看到错误信息就立即猜测原因跳过复现步骤直接修改代码同时尝试多个修复方案不检查最近的代码变更Iron Law是绝对不可违反的底线Red Flags则帮助AI识别常见的错误倾向。这种设计将“纪律”注入AI的行为模式。2.5 渐进式披露机制SKILL规范采用渐进式披露设计避免上下文窗口被无关内容污染markdownSession-Start Hook 示例在会话启动时系统注入一个极小的Hook2000 tokens“请优先读取 getting-started/SKILL.md 文件该文件将告知你何时调用哪个技能。”getting-started/SKILL.md 内容片段何时使用各技能当用户提出新功能需求时 → 调用 /brainstorming当设计方案已批准时 → 调用 /writing-plans当遇到Bug时 → 调用 /systematic-debuggingHook本身不包含完整的方法论指令而是一个“书签”指向具体的技能文件。这种设计使得AI只在需要时才加载详细内容。三、实战应用3.1 示例一创建头脑风暴技能以下是一个完整的头脑风暴技能实现展示SKILL规范的核心要素markdowndescription: “当用户提出新功能需求、需要设计方案或开始任何新需求时使用。触发关键词新功能、设计方案、头脑风暴、需求分析、功能规划”Brainstorming头脑风暴Iron Law‌在用户批准设计方案之前绝对不能写任何代码。‌Red Flags听到需求就立即开始写代码跳过需求澄清直接设计方案只提供一个方案不给用户选择空间设计方案未经用户确认就开始实施执行流程阶段一了解现状读取项目相关文件了解当前架构检查现有文档和最近提交记录识别可能受影响的模块执行指令请先阅读以下文件以了解项目现状README.mddocs/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 zwnj;**没有先写失败测试就不能写生产代码。**zwnj; ## Red Flags - 先写实现代码再补测试 - 跳过验证测试确实失败这一步 - 测试覆盖不完整就认为功能完成 - 重构时不同步更新测试 ## 执行流程红-绿-重构循环 ### RED阶段编写失败测试 python # 示例为待实现的用户验证函数编写测试 import pytest def test_validate_email_valid(): 测试有效的邮箱地址 result validate_email(userexample.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 zwnj;**找到根因之前不允许提修复方案。**zwnj; ## 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(levellogging.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 技能未被自动触发 zwnj;**问题描述**zwnj;AI助手没有按照预期自动激活某个技能。 zwnj;**原因分析**zwnj;description字段的触发关键词不够精确或与当前上下文匹配度不足。 zwnj;**解决方案**zwnj; 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 zwnj;**没有先写失败测试就不能写生产代码。此规则在任何情况下都不可违反。**zwnj; ## Red Flags - 产生这个功能很简单不需要测试的想法 - 以先快速验证思路为由跳过测试 - 在测试失败前就开始编写实现代码 - 认为稍后补测试是可以接受的 4.3 技能文件过于冗长导致上下文溢出 ‌问题描述‌技能文件内容过多消耗了大量上下文窗口。 ‌原因分析‌将过多细节和示例直接写入技能文件未使用渐进式披露。 ‌解决方案‌采用分层设计技能文件只保留核心流程详细示例放在独立文档中。 markdown # 技能文件中的引用方式 ## 详细示例 完整的代码示例请参考 - skills/brainstorming/examples/feature-request.md - skills/brainstorming/examples/bug-fix.md 当前技能文件只保留核心流程和关键约束。 4.4 多个技能的执行顺序混乱 ‌问题描述‌AI在应该执行技能A时跳到了技能C导致流程混乱。 ‌原因分析‌技能之间的转换条件不够明确。 ‌解决方案‌在每个技能的结尾明确指定下一步动作。 markdown # 在brainstorming技能末尾 ## 完成后的下一步 设计方案经用户批准后zwnj;**必须**zwnj;立即调用 /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助手。通过本文的深入探讨我们可以总结出以下核心要点 zwnj;**第一SKILL是“纪律”而非“能力”**zwnj;。AI助手本身已经具备规划、调试、重构等能力SKILL规范的价值在于将这些能力组织成有序的、可预测的、不可跳过的工作流。Iron Law和Red Flags的设计模式是实现这一目标的关键机制。 zwnj;**第二渐进式披露是高效上下文管理的基础**zwnj;。通过将技能文件设计为分层结构Hook只包含指向性信息详细内容按需加载SKILL规范在保证功能完整性的同时最大限度地节约了上下文窗口。 zwnj;**第三测试驱动开发是SKILL规范的核心实践**zwnj;。“没有先写失败测试就不能写生产代码”这一铁律将质量保障从“事后检查”转变为“事前约束”从根本上改变了AI的代码生成行为。 zwnj;**第四系统化调试体现了“方法论即代码”的理念**zwnj;。通过将调试过程分解为根因调查、模式分析、假设验证、修复实现四个阶段并严格规定“找到根因之前不允许提修复方案”SKILL规范将人类专家的调试思维固化为机器可执行的流程。 zwnj;**第五SKILL规范具有良好的可扩展性**zwnj;。任何团队都可以基于这套规范将自己独特的开发流程、最佳实践和质量标准封装为自定义技能实现团队工程文化的标准化和自动化。 掌握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 zwnj;**在用户批准设计方案之前绝对不能写任何代码。**zwnj; ## 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 zwnj;**在用户批准设计方案之前绝对不能写任何代码。**zwnj; ## 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 zwnj;**没有先写失败测试就不能写生产代码。**zwnj; ## Red Flags - 先写实现代码再补测试 - 跳过验证测试确实失败这一步 - 测试覆盖不完整就认为功能完成 - 重构时不同步更新测试 ## 执行流程红-绿-重构循环 ### RED阶段编写失败测试 在编写任何生产代码之前必须先编写测试用例。这些测试用例在当前阶段必须失败因为它们测试的功能尚未实现。 python # 示例为待实现的用户验证函数编写测试 import pytest def test_validate_email_valid(): 测试有效的邮箱地址 result validate_email(userexample.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 ra-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( ra-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 zwnj;**找到根因之前不允许提修复方案。**zwnj; ## 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(levellogging.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辅助软件开发的基础设施推动整个行业向更高质量、更高效率的方向发展。