前几天在技术群里看到有人刷“superpowers”第一反应是游戏里的角色强化点进去才知道这是一个给AI助手批量注入“专业技能”的开源方案。名字确实嚣张但我把文档和示例翻完之后觉得它配得上这个名号。如果你也遇到过这种情况AI助手聊天、改文案、写点小脚本都很溜但让它严格按照你的项目规范去干活、处理多步骤任务、调取一堆工具时总是差点意思——那这套叫superpowers的技能框架大概率对你有用。它不是某个具体的AI模型也不是一个聊天机器人而是一套把“能力包”安装到AI里的机制让AI从“什么都会一点”变成“在特定场景下能稳定干活”。这篇文章我会从安装、引入、技能清单、实际调用到排坑完整过一遍。无论你是刚开始玩AI编程助手还是已经在用Claude、Codex这类工具写代码跑自动化都能在里面找到能直接抄作业的部分。1. 先搞清楚 superpowers 到底是个什么东西1.1 名字起得嚣张本质是一套“技能包”很多人第一次听到 superpowers会以为它是个新模型或者某个高端IDE插件。其实它的核心形态是一堆写好的、结构化的“技能定义文件”一般以 Markdown 居多里面装着给AI看的指令、上下文、使用步骤和示例。你可以把它理解为“AI的岗位手册”。你给AI装一个“代码审查”技能它就获得了一套审查规则、检查清单、输出格式你给它装一个“周报生成”技能它就知道该去哪些文件里找数据、按什么结构写、写到什么颗粒度。这些技能不等同于模型能力而是帮AI少走弯路、稳定输出的一套“操作规范”。我最初看到这样的设计觉得挺奇怪的——直接写个复杂的提示词不就行了但用下来发现完全不是一回事。提示词是“一次性需求描述”技能是“可复用、可组合、可配置的工作流”。前者每次都要从头说清楚背景后者装一次全项目都能用。1.2 它解决的真实痛点AI不是没能力是没“章法”我自己用过几款主流的AI编程助手最明显的感觉是让它做点宽泛的事比如“帮我优化这段代码”它通常能给出不错的建议但一旦遇到需要固定流程、固定规范、固定产物的任务比如“按团队规范生成接口文档”“把日志按格式整理成周报”“对PR做一次全面的安全检查”它就容易自由发挥输出的东西漂亮但不符合要求。问题不在模型的智力而在“缺少约束和上下文”。 superpowers 的核心价值就是把这类高频任务固化成标准的技能文件让AI每次执行时都“有法可依”——该看哪些文件、该遵循哪些规则、该输出什么结构全部提前定义好。这就把AI从“即兴表演”变成了“按剧本演出”稳定性和可复现性一下子提上来了。1.3 适合谁用经常让AI干活干到一半又重新交代的人如果你是下面几类人我强烈建议试一下用 AI 编程助手写代码、跑自动化脚本但每次都要在对话里反复交代项目背景的开发者在团队里负责把AI能力标准化希望不同成员都能得到一致输出结果的技术负责人做内容生产、数据分析想让AI按固定模板出报告、出总结的运营或产品同学单纯想折腾AI玩法给AI装各种奇奇怪怪技能的好奇派。我自己属于第一类之前经常在同一个项目里重复粘贴十几次相同的规范说明装了技能包之后一句“用代码审查技能看看这个文件”就够了效率和一致性完全不是一个量级。2. 安装与引入把技能装进AI大脑2.1 前置准备确认你手里的AI工具支持技能读取superpowers 这套技能体系并不是绑定某一个特定工具的目前主流的做法都是基于“项目文件配置文件”的方式运行。也就是说你不需要安装一个很重的客户端只需要把技能文件和配置放在指定的目录里让AI启动时能读取到就行。我用下来比较顺手的组合是Claude 之类的命令行AI 本地目录里的技能文件夹。因为命令行工具的工作目录就是项目目录AI能直接看到技能文件调用起来最自然。当然桌面客户端一般也支持通过规则文件或项目记忆来加载这些技能原理大同小异都是“把技能内容注入上下文”。注意无论你用哪个工具前提是它允许你通过自定义指令、项目文件或系统提示词来扩展AI的行为。如果某个工具完全封闭、不接受用户自定义规则那就没法挂载 superpowers。2.2 标准步骤三步完成安装以我实际的操作路径为例安装 superpowers 通常就三步拉取技能包把技能库克隆到本地或者只拷贝你需要的几个技能文件到项目里。拉取时建议直接放到项目根目录下一个叫.superpowers之类的隐藏目录里避免污染你的业务代码目录。声明技能路径在AI助手的配置文件中把技能目录的路径加进去让AI启动时知道去哪里找技能。这一步非常关键配置不对的话AI根本感知不到技能存在。验证加载在对话里直接问“你现在可用的技能有哪些”如果AI能说出技能清单就说明加载成功。我这里用一个典型的本地仓库结构举个例子your-project/ ├── .superpowers/ │ ├── skills/ │ │ ├── code-review.md │ │ ├── generate-report.md │ │ └── analyze-logs.md │ └── README.md └── .ai-config.ai-config里写上技能目录的路径AI每次启动时会自动扫描这个目录把里面的 Markdown 文件当作候选技能加载进上下文。2.3 两种引入方式全局挂载 vs 项目级安装用下来我发现superpowers 有两种典型的引入方式适用场景完全不同。全局挂载是把技能装在你的全局配置目录下这样任何项目里都能用。适合放那些和项目无关的通用技能比如“写作润色”“代码解释”“时间管理”。优点是省心所有项目共享一套技能缺点是技能太杂AI每次都要在大量技能里挑选容易选错而且会浪费上下文窗口。项目级安装是只把技能放进当前项目的.superpowers目录里只在当前项目生效。适合放那些和项目强相关的规范类技能比如“按团队规范生成API文档”“从测试日志提取失败原因”。优点是精准AI进入项目后自然就带着项目特有的技能缺点是需要花费一点时间逐个项目安装。我个人的建议是通用技能全局挂载项目规范技能按项目安装。别一股脑全丢全局后面你就该头疼“AI为什么总在无关紧要的时候调用多余的技能”了。2.4 配置文件的写法给AI一份“技能地图”配置文件不用写得很复杂核心是给AI一份“技能地图”。我把自己的配置精简一下大概是这个意思skills: - name: code-review path: .superpowers/skills/code-review.md enabled: true - name: weekly-report path: .superpowers/skills/weekly-report.md enabled: true - name: legacy-skill enabled: false关键点在于每个技能有一个唯一的名字、一个具体的文件路径以及一个开关状态。名字是给AI和用户调用的标识路径指向技能文件的真实位置开关用来在不删除文件的情况下临时停用某个技能。配置里还可以给每个技能加一个简短的描述比如“用于在提交代码前检查常见安全问题”。描述写清楚一点非常有帮助因为AI在决定“用户当前需求匹配哪个技能”时主要就是靠技能名和描述来匹配的。技能名起得模棱两可后面调用就容易翻车。2.5 安装后立刻要做的验证装完别急着直接上任务先在对话里验证一下三件事让AI列出它能看到的技能清单确认数量对不对让AI简述某个技能的用途确认文件内容加载完整让AI执行一个技能里的最小示例确认输出符合预期。这三步走完基本能确认安装环境是通的。如果第二步发现AI对技能内容理解得支离破碎不用怀疑一定是技能文件格式写得有问题或者上下文被截断了先检查文件头部说明是否清晰再考虑是否拆分大文件。3. 内置技能清单都有哪些“超能力”3.1 技能类型的大致分布superpowers 的技能库五花八门但按功能归类大致能分成这几类分类典型技能适用场景开发辅助代码审查、Bug定位、重构建议、安全扫描写代码、提PR、排查问题文档生产快速生成README、API文档、周报、技术方案归档、汇报、团队协作数据分析CSV分析、日志聚合、统计报表生成看数据、写总结运维自动化服务器巡检、部署检查、日志排查习惯用命令行的人生活效率会议纪要、邮件撰写、日程整理日常办公看到这个分类你就明白了superpowers 并没有限定在编程领域。它的本质是“把AI调用方式标准化”所以理论上任何你经常重复、有固定流程的任务都可以做成一个技能。3.2 几个典型技能深度拆解我挑两个用得最多的技能给你看看内部到底是什么样的。第一个是“代码审查”技能。这个技能的文件开头会写明“该技能用于对指定代码文件进行系统性审查重点检查安全性、性能、可维护性三方面。”然后给出一份检查清单比如是否有硬编码密钥、是否有明显的N1查询、变量命名是否清晰、是否有重复代码块等。最后规定输出格式必须是“问题列表严重级别修改建议示例代码”。有了这个文件AI执行审查时就不再是泛泛而谈“代码不错”了它会逐条对照清单输出结构化结论。我用它检查过一个工具脚本还真揪出了两个潜在的文件路径注入问题那种感觉就像给AI戴上了一副专门的眼镜能看到平时忽略的细节。第二个是“周报生成”技能。它的内容往往包括从Git提交记录里统计本周改动、识别主要模块变更、汇总近期未完成事项最后按“本周进展/问题风险/下周计划”的结构生成周报。重点是它会规定AI“必须基于实际提交记录不允许编造数据”。这一点对做团队汇报特别重要否则AI生成周报再好看数据是编的就没意义了。3.3 技能文件的标准结构三段式一个合格的技能文件内部结构通常遵循“三段式”头部技能名称、一句话说明、适用场景、启用条件。这一部分决定了AI什么时候想起这个技能。正文详细的执行步骤、需要查看的文件、需要遵守的规则、需要避免的错误。这一部分是技能的核心内容。样例一个完整的输入输出示例让AI照着模板走。样例可以大幅度降低AI理解偏差。我在看别人写的技能文件时发现新手最容易忽略“禁用规则”。比如在某个技能里明确写“不要修改原始文件”“不要删除未确认的数据”AI就会变得谨慎很多。没有这层约束AI很可能好心办了坏事。4. 上手实操从安装到调用的完整案例4.1 场景设定让AI自动生成项目周报光聊概念太虚我带你完整走一遍实际案例。假设我在维护一个开源工具项目每周都需要给团队发一份周报。以前我都是手动整理Git提交记录费时且容易漏。现在我用 superpowers 的技能把它自动化。我先在.superpowers/skills/下新建一个weekly-report.md内容分为上面说的三段。头部写着“生成项目周报从Git历史提取数据按‘本周进展/问题风险/下周计划’输出”。正文部分要求AI执行以下步骤运行git log --oneline --sincelast Monday --untilthis Monday获取提交列表将提交按模块分类统计每类提交数量查找近期未关闭的issue列出风险项把所有信息填入周报模板。我用这个技能跑了一整个季度周报生成时间从原来的半小时压缩到五分钟而且每周格式都一致团队反馈阅读体验也好多了。4.2 关键点让AI有数据源可用实践里最容易遇到的问题就是“AI没有数据源”。很多AI助手并不会主动去跑 git log 或读取文件目录如果技能里只写了“请分析本周贡献”AI很可能直接编造一个漂亮的周报出来。所以在写技能时一定要把数据获取的方式写明确。比如我上面脚本里的那条git log命令如果AI支持执行命令它可以自己去跑如果AI不支持执行命令那你得把命令结果粘贴给它再让它统计。总之AI需要基于真实数据输出否则这个技能就是空中楼阁。重要提醒所有让AI自动生成报告类的技能务必在正文里加上“只基于提供的数据进行分析不要编造不存在的提交记录或数据”这一条。我见过太多周报技能因为缺少这句话输出一堆假数据拿去汇报会出大问题。4.3 自定义技能把你自己重复劳动变成技能除了用现成的技能包superpowers 最有魅力的地方是你可以把个人工作流也固化成技能。比如我经常要处理Nginx访问日志里的异常状态码以前每次都在对话里重复粘贴日志并解释“帮我提取5xx状态的URL占比”。后来我直接写了一个analyze-nginx-log.md技能把这些说明全写进去。写自定义技能的思路很直接把你平时在AI对话里重复发的指令整理成模板化的步骤和规则。我自己总结了一个脚本先写一句话说清楚这个技能会带来什么价值再列出开始执行的前置条件比如需要哪些文件、哪些命令可用然后分步骤写执行过程越具体越好最后放一个完整的示例输出格式对齐你希望得到的结果。写完之后测试一遍不行就调整措辞。技能文件本质上还是文字指令AI对文字的敏感度很高有时候你调整一个措辞输出质量就能上一个台阶。4.4 多技能组合一件事拆给多个技能干superpowers 还支持把多个技能串起来。比如我想写一份“版本发布说明”可以先调用“代码审查”技能检查版本分支的代码再调用“Git提交分析”技能收集提交信息最后调用“文档生成”技能把信息组织成发布说明。这种组合方式非常像流水线每个技能负责一个环节AI在技能之间切换前一技能的输出变成后一技能的输入。我在实际项目里已经用这种方式搭建了“自动生成变更日志”的小流程效果稳定而且每一步都可以追溯。如果你的AI工具支持自动调用技能这种组合的效率会更高如果只能手动触发那就在对话里分步下达指令效果也不会差太多。5. 常见问题与排查技巧实录5.1 技能明明装了但AI就是“看不到”这是最常遇到的情况。明明.superpowers目录里放了文件配置里也写了路径但AI一问三不知。排查思路按三步走检查文件路径是否和配置里填的完全一致特别注意大小写和斜杠方向确认AI的工作目录是不是项目根目录很多工具默认在家目录或临时目录自然扫不到项目里的技能重新启动AI会话确保配置重新加载有一部分工具不会热更新技能文件。我自己的经验是90%的“技能不生效”都出在路径或工作目录上而不是技能文件内容的问题。所以第一步先检查这两项别急着去改技能文件的措辞。5.2 技能加载太多上下文窗口塞爆superpowers 看起来是纯文本文件但AI每次读取技能都会占用上下文窗口。如果把上百个技能全塞进去AI的注意力会被稀释不仅可能导致真正需要的技能没有被采纳还可能出现“过载”导致回答质量急剧下降。解决方案也很简单项目级只放当前用得上的技能全局只放最频繁调用的通用技能。另外技能文件本身要控制篇幅。我看过有人把技能写成五十行以上的长篇大论AI读起来吃力执行时抓不住重点。简洁、分条、示例明确才是好技能文件的共同特征。如果确实有大量技能需求建议把技能文件拆成两个级别——一个“索引文件”里只放技能名和一句话描述AI根据索引判断要不要读取详细内容。这样能显著降低上下文消耗。5.3 多个技能相互冲突AI不知道该听谁的当两个技能同时被命中时AI可能会把它们混在一起执行导致输出四不像。比如一个技能要求“生成详细报告篇幅不限”另一个技能要求“所有输出控制在200字以内”AI就会很纠结。解决办法是在技能文件开头写明“当本技能与其他技能冲突时请优先执行本技能”或者“本技能不适用于xxx场景”。你也可以在配置里给技能设置优先级让AI在冲突时知道该以哪个为准。这个高级玩法需要反复测试但一旦调好整个技能体系会变得非常可靠。5.4 排坑心得汇总我整理了一份自己踩过坑之后的速查表希望对你有用症状可能原因解决办法AI从不主动调用技能技能描述太模糊在描述中写明“当用户提到xxx时使用此技能”技能输出格式不规范技能文件缺少示例在文末加一个完整的输入输出示例技能执行到一半停止步骤太复杂超出上下文窗口拆分技能让每个技能只负责一个环节AI执行技能时编造数据技能未明确禁用编造在规则中加入“只基于事实数据”要求更新技能文件后不生效会话未重新加载重启AI会话或重新加载配置文件6. 我自己在实操中的一些体会折腾 superpowers 这段时间我最大的感受是它改变了我和AI协作的方式。以前我总觉得AI好不好用全看提示词写得好不好但提示词一次性消耗完就没了每次都要重新写技能则是可以沉淀、可复用的资产。我上一周辛苦调教出来的“发布说明自动生成”流程这周一个指令就能复用而且效果比上周还稳定因为技能文件里积累了更多调优后的细节。建议第一次上手的朋友不要急着把所有技能包都装上。先挑一个和你日常工作最贴近的技能比如代码审查或日志分析安装、试用、拆解它的结构、试着改一改里面的规则跑顺之后再逐步拓展。技能不在多精准才有意义。最后分享一个小技巧技能文件其实可以用中文写。网上很多示例是英文的但AI对中文的理解完全没问题。用自己最熟悉的语言组织技能规则比硬翻译成英文要自然得多。只要格式清晰、步骤明确、示例完整语言不是障碍。这套方法论本身也没绑定任何编程语言或平台它更像是一套“和AI协作的工程实践”你可以把它迁移到任何支持自定义指令的AI环境里。今天你把这套思路学会了以后无论AI工具怎么换这份技能库都能跟着你走。
前几天在技术群里看到有人刷“superpowers”第一反应是游戏里的角色强化点进去才知道这是一个给AI助手批量注入“专业技能”的开源方案。名字确实嚣张但我把文档和示例翻完之后觉得它配得上这个名号。如果你也遇到过这种情况AI助手聊天、改文案、写点小脚本都很溜但让它严格按照你的项目规范去干活、处理多步骤任务、调取一堆工具时总是差点意思——那这套叫superpowers的技能框架大概率对你有用。它不是某个具体的AI模型也不是一个聊天机器人而是一套把“能力包”安装到AI里的机制让AI从“什么都会一点”变成“在特定场景下能稳定干活”。这篇文章我会从安装、引入、技能清单、实际调用到排坑完整过一遍。无论你是刚开始玩AI编程助手还是已经在用Claude、Codex这类工具写代码跑自动化都能在里面找到能直接抄作业的部分。1. 先搞清楚 superpowers 到底是个什么东西1.1 名字起得嚣张本质是一套“技能包”很多人第一次听到 superpowers会以为它是个新模型或者某个高端IDE插件。其实它的核心形态是一堆写好的、结构化的“技能定义文件”一般以 Markdown 居多里面装着给AI看的指令、上下文、使用步骤和示例。你可以把它理解为“AI的岗位手册”。你给AI装一个“代码审查”技能它就获得了一套审查规则、检查清单、输出格式你给它装一个“周报生成”技能它就知道该去哪些文件里找数据、按什么结构写、写到什么颗粒度。这些技能不等同于模型能力而是帮AI少走弯路、稳定输出的一套“操作规范”。我最初看到这样的设计觉得挺奇怪的——直接写个复杂的提示词不就行了但用下来发现完全不是一回事。提示词是“一次性需求描述”技能是“可复用、可组合、可配置的工作流”。前者每次都要从头说清楚背景后者装一次全项目都能用。1.2 它解决的真实痛点AI不是没能力是没“章法”我自己用过几款主流的AI编程助手最明显的感觉是让它做点宽泛的事比如“帮我优化这段代码”它通常能给出不错的建议但一旦遇到需要固定流程、固定规范、固定产物的任务比如“按团队规范生成接口文档”“把日志按格式整理成周报”“对PR做一次全面的安全检查”它就容易自由发挥输出的东西漂亮但不符合要求。问题不在模型的智力而在“缺少约束和上下文”。 superpowers 的核心价值就是把这类高频任务固化成标准的技能文件让AI每次执行时都“有法可依”——该看哪些文件、该遵循哪些规则、该输出什么结构全部提前定义好。这就把AI从“即兴表演”变成了“按剧本演出”稳定性和可复现性一下子提上来了。1.3 适合谁用经常让AI干活干到一半又重新交代的人如果你是下面几类人我强烈建议试一下用 AI 编程助手写代码、跑自动化脚本但每次都要在对话里反复交代项目背景的开发者在团队里负责把AI能力标准化希望不同成员都能得到一致输出结果的技术负责人做内容生产、数据分析想让AI按固定模板出报告、出总结的运营或产品同学单纯想折腾AI玩法给AI装各种奇奇怪怪技能的好奇派。我自己属于第一类之前经常在同一个项目里重复粘贴十几次相同的规范说明装了技能包之后一句“用代码审查技能看看这个文件”就够了效率和一致性完全不是一个量级。2. 安装与引入把技能装进AI大脑2.1 前置准备确认你手里的AI工具支持技能读取superpowers 这套技能体系并不是绑定某一个特定工具的目前主流的做法都是基于“项目文件配置文件”的方式运行。也就是说你不需要安装一个很重的客户端只需要把技能文件和配置放在指定的目录里让AI启动时能读取到就行。我用下来比较顺手的组合是Claude 之类的命令行AI 本地目录里的技能文件夹。因为命令行工具的工作目录就是项目目录AI能直接看到技能文件调用起来最自然。当然桌面客户端一般也支持通过规则文件或项目记忆来加载这些技能原理大同小异都是“把技能内容注入上下文”。注意无论你用哪个工具前提是它允许你通过自定义指令、项目文件或系统提示词来扩展AI的行为。如果某个工具完全封闭、不接受用户自定义规则那就没法挂载 superpowers。2.2 标准步骤三步完成安装以我实际的操作路径为例安装 superpowers 通常就三步拉取技能包把技能库克隆到本地或者只拷贝你需要的几个技能文件到项目里。拉取时建议直接放到项目根目录下一个叫.superpowers之类的隐藏目录里避免污染你的业务代码目录。声明技能路径在AI助手的配置文件中把技能目录的路径加进去让AI启动时知道去哪里找技能。这一步非常关键配置不对的话AI根本感知不到技能存在。验证加载在对话里直接问“你现在可用的技能有哪些”如果AI能说出技能清单就说明加载成功。我这里用一个典型的本地仓库结构举个例子your-project/ ├── .superpowers/ │ ├── skills/ │ │ ├── code-review.md │ │ ├── generate-report.md │ │ └── analyze-logs.md │ └── README.md └── .ai-config.ai-config里写上技能目录的路径AI每次启动时会自动扫描这个目录把里面的 Markdown 文件当作候选技能加载进上下文。2.3 两种引入方式全局挂载 vs 项目级安装用下来我发现superpowers 有两种典型的引入方式适用场景完全不同。全局挂载是把技能装在你的全局配置目录下这样任何项目里都能用。适合放那些和项目无关的通用技能比如“写作润色”“代码解释”“时间管理”。优点是省心所有项目共享一套技能缺点是技能太杂AI每次都要在大量技能里挑选容易选错而且会浪费上下文窗口。项目级安装是只把技能放进当前项目的.superpowers目录里只在当前项目生效。适合放那些和项目强相关的规范类技能比如“按团队规范生成API文档”“从测试日志提取失败原因”。优点是精准AI进入项目后自然就带着项目特有的技能缺点是需要花费一点时间逐个项目安装。我个人的建议是通用技能全局挂载项目规范技能按项目安装。别一股脑全丢全局后面你就该头疼“AI为什么总在无关紧要的时候调用多余的技能”了。2.4 配置文件的写法给AI一份“技能地图”配置文件不用写得很复杂核心是给AI一份“技能地图”。我把自己的配置精简一下大概是这个意思skills: - name: code-review path: .superpowers/skills/code-review.md enabled: true - name: weekly-report path: .superpowers/skills/weekly-report.md enabled: true - name: legacy-skill enabled: false关键点在于每个技能有一个唯一的名字、一个具体的文件路径以及一个开关状态。名字是给AI和用户调用的标识路径指向技能文件的真实位置开关用来在不删除文件的情况下临时停用某个技能。配置里还可以给每个技能加一个简短的描述比如“用于在提交代码前检查常见安全问题”。描述写清楚一点非常有帮助因为AI在决定“用户当前需求匹配哪个技能”时主要就是靠技能名和描述来匹配的。技能名起得模棱两可后面调用就容易翻车。2.5 安装后立刻要做的验证装完别急着直接上任务先在对话里验证一下三件事让AI列出它能看到的技能清单确认数量对不对让AI简述某个技能的用途确认文件内容加载完整让AI执行一个技能里的最小示例确认输出符合预期。这三步走完基本能确认安装环境是通的。如果第二步发现AI对技能内容理解得支离破碎不用怀疑一定是技能文件格式写得有问题或者上下文被截断了先检查文件头部说明是否清晰再考虑是否拆分大文件。3. 内置技能清单都有哪些“超能力”3.1 技能类型的大致分布superpowers 的技能库五花八门但按功能归类大致能分成这几类分类典型技能适用场景开发辅助代码审查、Bug定位、重构建议、安全扫描写代码、提PR、排查问题文档生产快速生成README、API文档、周报、技术方案归档、汇报、团队协作数据分析CSV分析、日志聚合、统计报表生成看数据、写总结运维自动化服务器巡检、部署检查、日志排查习惯用命令行的人生活效率会议纪要、邮件撰写、日程整理日常办公看到这个分类你就明白了superpowers 并没有限定在编程领域。它的本质是“把AI调用方式标准化”所以理论上任何你经常重复、有固定流程的任务都可以做成一个技能。3.2 几个典型技能深度拆解我挑两个用得最多的技能给你看看内部到底是什么样的。第一个是“代码审查”技能。这个技能的文件开头会写明“该技能用于对指定代码文件进行系统性审查重点检查安全性、性能、可维护性三方面。”然后给出一份检查清单比如是否有硬编码密钥、是否有明显的N1查询、变量命名是否清晰、是否有重复代码块等。最后规定输出格式必须是“问题列表严重级别修改建议示例代码”。有了这个文件AI执行审查时就不再是泛泛而谈“代码不错”了它会逐条对照清单输出结构化结论。我用它检查过一个工具脚本还真揪出了两个潜在的文件路径注入问题那种感觉就像给AI戴上了一副专门的眼镜能看到平时忽略的细节。第二个是“周报生成”技能。它的内容往往包括从Git提交记录里统计本周改动、识别主要模块变更、汇总近期未完成事项最后按“本周进展/问题风险/下周计划”的结构生成周报。重点是它会规定AI“必须基于实际提交记录不允许编造数据”。这一点对做团队汇报特别重要否则AI生成周报再好看数据是编的就没意义了。3.3 技能文件的标准结构三段式一个合格的技能文件内部结构通常遵循“三段式”头部技能名称、一句话说明、适用场景、启用条件。这一部分决定了AI什么时候想起这个技能。正文详细的执行步骤、需要查看的文件、需要遵守的规则、需要避免的错误。这一部分是技能的核心内容。样例一个完整的输入输出示例让AI照着模板走。样例可以大幅度降低AI理解偏差。我在看别人写的技能文件时发现新手最容易忽略“禁用规则”。比如在某个技能里明确写“不要修改原始文件”“不要删除未确认的数据”AI就会变得谨慎很多。没有这层约束AI很可能好心办了坏事。4. 上手实操从安装到调用的完整案例4.1 场景设定让AI自动生成项目周报光聊概念太虚我带你完整走一遍实际案例。假设我在维护一个开源工具项目每周都需要给团队发一份周报。以前我都是手动整理Git提交记录费时且容易漏。现在我用 superpowers 的技能把它自动化。我先在.superpowers/skills/下新建一个weekly-report.md内容分为上面说的三段。头部写着“生成项目周报从Git历史提取数据按‘本周进展/问题风险/下周计划’输出”。正文部分要求AI执行以下步骤运行git log --oneline --sincelast Monday --untilthis Monday获取提交列表将提交按模块分类统计每类提交数量查找近期未关闭的issue列出风险项把所有信息填入周报模板。我用这个技能跑了一整个季度周报生成时间从原来的半小时压缩到五分钟而且每周格式都一致团队反馈阅读体验也好多了。4.2 关键点让AI有数据源可用实践里最容易遇到的问题就是“AI没有数据源”。很多AI助手并不会主动去跑 git log 或读取文件目录如果技能里只写了“请分析本周贡献”AI很可能直接编造一个漂亮的周报出来。所以在写技能时一定要把数据获取的方式写明确。比如我上面脚本里的那条git log命令如果AI支持执行命令它可以自己去跑如果AI不支持执行命令那你得把命令结果粘贴给它再让它统计。总之AI需要基于真实数据输出否则这个技能就是空中楼阁。重要提醒所有让AI自动生成报告类的技能务必在正文里加上“只基于提供的数据进行分析不要编造不存在的提交记录或数据”这一条。我见过太多周报技能因为缺少这句话输出一堆假数据拿去汇报会出大问题。4.3 自定义技能把你自己重复劳动变成技能除了用现成的技能包superpowers 最有魅力的地方是你可以把个人工作流也固化成技能。比如我经常要处理Nginx访问日志里的异常状态码以前每次都在对话里重复粘贴日志并解释“帮我提取5xx状态的URL占比”。后来我直接写了一个analyze-nginx-log.md技能把这些说明全写进去。写自定义技能的思路很直接把你平时在AI对话里重复发的指令整理成模板化的步骤和规则。我自己总结了一个脚本先写一句话说清楚这个技能会带来什么价值再列出开始执行的前置条件比如需要哪些文件、哪些命令可用然后分步骤写执行过程越具体越好最后放一个完整的示例输出格式对齐你希望得到的结果。写完之后测试一遍不行就调整措辞。技能文件本质上还是文字指令AI对文字的敏感度很高有时候你调整一个措辞输出质量就能上一个台阶。4.4 多技能组合一件事拆给多个技能干superpowers 还支持把多个技能串起来。比如我想写一份“版本发布说明”可以先调用“代码审查”技能检查版本分支的代码再调用“Git提交分析”技能收集提交信息最后调用“文档生成”技能把信息组织成发布说明。这种组合方式非常像流水线每个技能负责一个环节AI在技能之间切换前一技能的输出变成后一技能的输入。我在实际项目里已经用这种方式搭建了“自动生成变更日志”的小流程效果稳定而且每一步都可以追溯。如果你的AI工具支持自动调用技能这种组合的效率会更高如果只能手动触发那就在对话里分步下达指令效果也不会差太多。5. 常见问题与排查技巧实录5.1 技能明明装了但AI就是“看不到”这是最常遇到的情况。明明.superpowers目录里放了文件配置里也写了路径但AI一问三不知。排查思路按三步走检查文件路径是否和配置里填的完全一致特别注意大小写和斜杠方向确认AI的工作目录是不是项目根目录很多工具默认在家目录或临时目录自然扫不到项目里的技能重新启动AI会话确保配置重新加载有一部分工具不会热更新技能文件。我自己的经验是90%的“技能不生效”都出在路径或工作目录上而不是技能文件内容的问题。所以第一步先检查这两项别急着去改技能文件的措辞。5.2 技能加载太多上下文窗口塞爆superpowers 看起来是纯文本文件但AI每次读取技能都会占用上下文窗口。如果把上百个技能全塞进去AI的注意力会被稀释不仅可能导致真正需要的技能没有被采纳还可能出现“过载”导致回答质量急剧下降。解决方案也很简单项目级只放当前用得上的技能全局只放最频繁调用的通用技能。另外技能文件本身要控制篇幅。我看过有人把技能写成五十行以上的长篇大论AI读起来吃力执行时抓不住重点。简洁、分条、示例明确才是好技能文件的共同特征。如果确实有大量技能需求建议把技能文件拆成两个级别——一个“索引文件”里只放技能名和一句话描述AI根据索引判断要不要读取详细内容。这样能显著降低上下文消耗。5.3 多个技能相互冲突AI不知道该听谁的当两个技能同时被命中时AI可能会把它们混在一起执行导致输出四不像。比如一个技能要求“生成详细报告篇幅不限”另一个技能要求“所有输出控制在200字以内”AI就会很纠结。解决办法是在技能文件开头写明“当本技能与其他技能冲突时请优先执行本技能”或者“本技能不适用于xxx场景”。你也可以在配置里给技能设置优先级让AI在冲突时知道该以哪个为准。这个高级玩法需要反复测试但一旦调好整个技能体系会变得非常可靠。5.4 排坑心得汇总我整理了一份自己踩过坑之后的速查表希望对你有用症状可能原因解决办法AI从不主动调用技能技能描述太模糊在描述中写明“当用户提到xxx时使用此技能”技能输出格式不规范技能文件缺少示例在文末加一个完整的输入输出示例技能执行到一半停止步骤太复杂超出上下文窗口拆分技能让每个技能只负责一个环节AI执行技能时编造数据技能未明确禁用编造在规则中加入“只基于事实数据”要求更新技能文件后不生效会话未重新加载重启AI会话或重新加载配置文件6. 我自己在实操中的一些体会折腾 superpowers 这段时间我最大的感受是它改变了我和AI协作的方式。以前我总觉得AI好不好用全看提示词写得好不好但提示词一次性消耗完就没了每次都要重新写技能则是可以沉淀、可复用的资产。我上一周辛苦调教出来的“发布说明自动生成”流程这周一个指令就能复用而且效果比上周还稳定因为技能文件里积累了更多调优后的细节。建议第一次上手的朋友不要急着把所有技能包都装上。先挑一个和你日常工作最贴近的技能比如代码审查或日志分析安装、试用、拆解它的结构、试着改一改里面的规则跑顺之后再逐步拓展。技能不在多精准才有意义。最后分享一个小技巧技能文件其实可以用中文写。网上很多示例是英文的但AI对中文的理解完全没问题。用自己最熟悉的语言组织技能规则比硬翻译成英文要自然得多。只要格式清晰、步骤明确、示例完整语言不是障碍。这套方法论本身也没绑定任何编程语言或平台它更像是一套“和AI协作的工程实践”你可以把它迁移到任何支持自定义指令的AI环境里。今天你把这套思路学会了以后无论AI工具怎么换这份技能库都能跟着你走。
