1. 当大模型只会聊天时superpowers补上了什么短板说句实话这两年我用过不少号称智能的AI工具最大的感触是模型很聪明但大多时候只能动嘴不能动手。你让它写一段分析报告它能给你写出花来你让它帮你把桌面上几十个文件按日期整理好它只会回你一句抱歉我无法直接访问您的文件系统。知识它都有能力它全无这种体验就像请了个满腹经纶的顾问却让人家隔着玻璃窗指挥你干活。superpowers这个名字起得很直白——它就是来给大模型装技能的。我第一次看到这个项目的时候脑子里冒出来的第一个问题是这跟普通的AI工具包有什么区别后来把一个技能包装进去实测了几轮我才意识到它的核心价值不在多了一个工具而在它彻底改变了LLM的工作方式。简单说superpowers把让AI学会一个新本事这件事从一个需要写代码、调接口、改Prompt的工程问题变成了一个像装手机App一样简单的操作。你不需要理解微调不需要写复杂的Agent框架只需要按照它的约定准备一个技能包AI就能在合适的场景下主动调用这个技能完成从前需要人工介入的实操任务。这篇文章就是围绕superpowers这个开源项目把我从安装、配置、编写自定义技能到排查问题这一路的完整经历分享出来。写给谁看主要三类人一是被AI只会说不会做折磨的产品经理和运营二是想在项目里快速集成AI自动化能力的开发者三是纯粹好奇大模型到底还能怎么用的折腾型玩家。门槛不高但你得愿意动手。2. 技能包的心脏一个SKILL.md如何让AI学会新本事2.1 技能包的三层结构不是玄学是约定要说superpowers里的技能到底是个什么东西我拆开给你看。每一个技能本质上就是一个文件夹里面装了三种东西说明文档、可执行脚本、辅助资源。这三样合在一起构成了LLM能理解、能调用、能完成任务的最小单元。拿官方仓库里一个我印象很深的技能举例。假设你装了一个批量重命名文件的技能它的目录大概是这样的rename-files/ ├── SKILL.md # 技能说明书告诉AI这个技能干嘛用的、怎么用 ├── scripts/ │ ├── rename.py # 实际干活的脚本接收参数执行重命名 │ └── preview.py # 预览改名效果避免AI想当然地乱改 └── resources/ ├── examples/ │ └── before_after.txt # 改名前后的对照示例 └── templates/ └── naming_rules.md # 命名规则模板最关键的永远是那个SKILL.md。它不是给人看的技术文档而是写给LLM的操作手册。AI在接任务的时候会先扫描所有已安装技能的SKILL.md判断眼前这个任务跟哪个技能匹配。匹配上了它再按照SKILL.md里的步骤指引去调用对应的脚本把活儿干完。这就解释了为什么superpowers敢说自己给LLM装技能——它其实并没有改动模型本身的权重而是利用了大模型天然具备的阅读理解能力和工具调用能力用一份精心编写的说明书把模型的知识转化成了行动。2.2 LLM怎么知道该用哪个技能描述匹配与工具调用的联动很多人不理解AI是怎么在几十个技能里挑中正确那一个的其实原理跟你用搜索引擎差不多。llm会把当前用户请求和每个技能的description描述字段做语义匹配挑一个最相关的。这个机制听起来简单实际操作里全是细节。我记得官方文档里反复强调描述字段别写废话要写这个技能在什么情况下该用、能干什么、不能干什么。比如你写处理文件AI大概率不知道该不该用它你写当用户需要批量修改文件名、按规则重命名大量文件时使用不要用于单文件改名AI就能精准触发。选定技能之后第二步是参数抽取。LLM会阅读SKILL.md里定义的参数规范从用户的自然语言里抽取出脚本需要的输入。比如用户说把downloads文件夹里所有.jpg按拍摄日期改名为IMG_YYYYMMDD格式AI会抽出三个参数目标路径、匹配模式、命名规则然后传给rename.py执行。![注意] 这一步是整个技能体系里最容易出问题的地方。LLM抽取参数经常会有自己的小聪明比如给参数加一些原文没有的前缀后缀。所以技能脚本的鲁棒性很重要后面我会专门讲怎么处理这类问题。2.3 为什么选择文档脚本而不是纯代码有人可能会问与其搞这么一套SKILL.md的约定为什么不直接把功能写成API接口让AI去调不就完了这个问题我当初也纠结过真实对比下来才明白superpowers这么设计的高明之处。纯API接口的问题在于AI不知道什么时候该用。你写了一个文件重命名接口但AI面对帮我把文件整理一下这种模糊需求时根本想不到去调它。而SKILL.md的存在相当于给每个API配了一个使用场景说明书极大地提高了AI的触发准确率。文档先行意味着技能可以被阅读理解而非硬编码。你可以随时修改SKILL.md里的操作步骤不需要改动一行代码AI的执行逻辑就跟着变了。这种灵活性是传统API没法比的。脚本与LLM解耦让技能可以复用。你的重命名脚本用Python写的但某天你把这个技能分享给一个用Node.js环境的同事他不需要改脚本——只要他的环境能跑Python就行。AI调用脚本时根本不关心脚本语言它只关心这个脚本接收什么输入、输出什么结果。一句话总结这套设计把意图识别交给LLM把确定性操作交给脚本各干各擅长的部分。可以说superpowers给我最大的启发不是某个具体技能而是这种能力分层的架构思想。3. 从安装到首次跑通superpowers的上手全流程3.1 环境准备它其实没那么挑食先泼一盆冷水superpowers不是那种装了就能用的一键解决方案它有一个前提——你得先有一个能支持工具调用的LLM环境。目前主流的支持方式是接Claude Code这类终端工具环境或者其他兼容工具调用协议的客户端。如果你的环境只支持纯文本对话那技能装了也白装因为AI根本没有执行脚本这条通道。环境清单我给你列一份实测版本需要准备的东西说明替代方案支持工具调用的LLM环境Claude Code或同类终端工具其他兼容的Agent环境Node.js环境用于运行superpowers的CLI工具版本建议18以上Python可选但推荐部分官方技能脚本用Python写的不装的话部分技能跑不了但核心框架不受影响Git从仓库拉取技能包和项目源码没有也能用zip下载3.2 安装与初始化两条路线任选安装superpowers本身不复杂走的是标准npm发布流程。我自己用的是全局安装的方式在终端里执行npm install -g superpowers装完之后先别急着用跑一个初始化命令它会帮你把技能目录结构、配置文件、工作目录全部准备好superpowers init这一步会生成一个类似于~/.superpowers/的目录里面按功能分了几个子目录skills/放已安装的技能config/放配置文件logs/记录调用日志。初始化的意义不只是建文件夹更是在你的LLM环境配置里加一段技能引导词让AI在一开始就知道自己有这些技能可用。如果你不想全局安装也可以直接拉源码跑git clone https://github.com/obra/superpowers.git cd superpowers npm install npm run setup两条路线我都试过结论是普通用户直接npm全局安装就够了源码跑主要适合想二次开发的人。3.3 查看已装技能与验证调用装完之后我先做了一件很多人忽略的事——查看当前环境里到底有哪些技能可用superpowers list输出的结果里每个技能会显示名字、版本、描述、状态enabled/disabled。我第一次看到这个列表的时候发现官方仓库默认带了一批技能比如文件整理、批量重命名、数据格式转换、定时任务生成等等覆盖了不少日常场景。验证调用是否正常最稳妥的方式不是直接扔一个复杂需求而是先给AI一个标准任务。比如装完文件重命名技能我就把测试文件夹里放了三五个文件然后对LLM说请用superpowers里的文件重命名技能把当前目录下所有.txt文件改成小写文件名。这个指令足够清晰又带上了明确技能指向能直接看出技能链路通不通。第一次跑通的时候我盯着终端里AI自动完成参数抽取、脚本执行、返回结果的全过程说实话还挺有成就感的。那一刻我才真正理解什么叫从知识到行动的跨越。4. 零基础写一个自己的技能从需求到上线的完整实操4.1 什么场景值得做成技能在讲怎么写之前先说一个我踩过的坑不是所有任务都适合做成技能。你把所有功能都塞进技能列表结果就是AI面对一个简单问题时要在几十个技能里做选择反而拖慢响应速度甚至出现误匹配。我现在的判断标准很简单满足下面任意一条就值得做操作步骤确定且可重复比如每周生成一份周报每次的流程都一样只是数据不同。需要访问外部系统或本地环境比如读取文件、执行shell命令、调用某个本地工具这些是纯对话LLM做不了的。步骤多、容易中间出错比如下载一批CSV→清洗→转成Excel→发邮件拆成技能后每一步的中间结果都有脚本把关不会让AI自由发挥。反过来那些开放性强、没有固定流程的任务比如帮我写一段创意文案让AI直接回答反而更好没必要套一个技能的壳。4.2 搭建目录与SKILL.md的写法确定要做技能之后我会先建一个技能骨架。用superpowers自带的脚手架命令最省事它会自动生成标准的目录结构和占位文件superpowers create skill --name weekly-report这个命令执行完后会生成一个weekly-report/文件夹里面有初始化的SKILL.md和一个空的scripts/目录。下面来说SKILL.md怎么写这是重头戏。我强烈建议你参考一个格式化的模板而不是从零憋。我自己的SKILL.md通常长这样--- name: weekly-report description: 当用户需要生成每周工作汇报、周报或汇总本周工作内容时使用。这个技能会自动读取本周完成事项记录并生成结构化周报。不要用它处理月度汇报或项目总结。 allowed-tools: bash, python --- # Weekly Report Generator ## 使用场景 - 用户说生成周报整理本周工作时 - 用户提供了一个包含工作记录的文档路径时 ## 输入参数 - source_path: 工作记录文件路径支持 .txt/.md/.json - output_format: 输出格式可选 markdown/html默认 markdown ## 执行步骤 1. 读取 source_path 指向的文件 2. 提取本周完成的事项按完成事项/进行中事项/待办事项三类分组 3. 调用 scripts/generate_report.py 生成周报 4. 将结果返回给用户 ## 输出 - 一份 markdown 格式的周报包含日期范围和三类事项列表 ## 注意事项 - 如果 source_path 不存在请先向用户确认路径不要自行猜测 - 周报中不要包含具体的数据指标除非用户明确要求写完之后我复盘过几遍发现一份好的SKILL.md有几个共性description里明确写出了什么时候用和什么时候不用执行步骤是给LLM看的操作流程步骤编号清晰注意事项兜底了很多边界情况。这三点缺一不可。4.3 编写能被LLM稳定调用的脚本脚本写得好不好直接影响AI调用的成功率。我最早犯的一个错是把脚本写得太聪明——支持很多灵活的参数组合结果AI每次传参都不一样脚本频繁报错。后来我总结了一套稳定的写法参数尽量用标准JSON接收。让SKILL.md里定义好参数名脚本用json.loads(sys.stdin.read())解析输入。这样比让AI拼命令行参数可靠得多因为JSON天然有结构AI不容易拼错。#!/usr/bin/env python3 import json import sys from datetime import datetime def main(): # 从stdin读取JSON参数 try: input_data json.load(sys.stdin) source_path input_data.get(source_path, ) output_format input_data.get(output_format, markdown) except Exception as e: # 参数解析失败返回结构化错误信息 print(json.dumps({status: error, message: f参数解析失败: {e}})) sys.exit(1) # ... 实际处理逻辑 ... if __name__ __main__: main()输出也返回JSON。脚本执行的最终结果不要用一堆print堆给人看的文本而是返回一个JSON对象。AI拿到JSON之后自己会组织语言转述给用户。这样做的好处是AI永远能拿到结构化结果哪怕它转述得不太好底层信息也是准的。错误处理要显式。脚本崩溃的时候不要让异常堆栈直接扔给AI——它看到一堆Traceback很容易懵。我的习惯是捕获所有异常统一输出{status: error, message: 发生了什么问题}AI看到之后就能根据message向用户解释或尝试其他方案。4.4 测试与迭代在真实会话里验证技能写完不是终点测试和迭代才是真正花时间的地方。我的测试套路分三步走先用最简单的指令测通链路再用模糊一点的指令测AI的意图识别最后用反例测试看AI会不会在技能不适用时强行调用。第一步最小可行测试。直接给AI下非常明确的指令用weekly-report技能读取worklog.md生成markdown格式周报。这时候主要看链路通不通AI识别技能了吗参数抽取对吗脚本执行成功了吗结果返回正常吗第二步模糊需求测试。什么也不指明直接说帮我写个周报。这时候AI需要自己判断——它会不会主动选到weekly-report技能如果它选择直接口述一段周报而没有调用技能说明技能描述写得还不够吸引AI去选择。我通常会调整SKILL.md里的description让它更贴近用户日常表达习惯。第三步反例测试。说一个和技能无关的需求比如帮我写一份项目商业计划书。这时候如果AI还是调用了weekly-report说明技能的边界描述不够清晰需要在description里加强不要用于的部分。这个过程我大概迭代了三轮才让一个技能达到该用的时候一定用不该用的时候不乱用的理想状态。说句掏心窝的话技能开发最花时间的不是写脚本而是调描述、调边界、调AI对这个技能的理解。5. 实测中的翻车现场与排查经验5.1 翻车现场一描述写得太泛AI把技能用成了万能工具这个坑我印象太深了。我最早写的一个文件搜索技能description写的是搜索文件。结果安装之后AI碰到任何跟找东西沾边的需求——找关键词、找联系人、找聊天记录——都会尝试调这个技能然后返回一堆莫名其妙的结果。排查过程是这样的我先看日志发现AI调用技能的触发记录远超预期然后逐个检查用户的原始请求和AI的调用理由确认问题出在description过于宽泛。修复办法说来也简单我把description改成了带搜索本地文件系统中的文件支持按文件名、扩展名、修改日期过滤。仅用于文件系统内的文件查找不用于文本内容搜索这样的精确描述再测试了几轮误触发率明显下降。经验总结写description时把该用和不该用两个维度都写进去效果远好过只写该用。5.2 翻车现场二脚本参数里的特殊字符导致JSON解析失败第二件翻车的事是脚本解析参数时遇到的。用户让AI整理文件名说把带括号(1)的文件改名去掉括号。LLM抽取参数后传给我的Python脚本时括号和空格被转义了一遍又一遍最后JSON字段里的字符串变成了文件名称 (1).txt这种带各种转义符号的内容脚本直接解析失败。我当时排查了半小时才想明白问题不在LLM也不在JSON解析而在LLM和脚本之间转述参数时特殊字符的语义被改变了。解决办法有两层第一层在SKILL.md里明确要求所有参数以原始字符串传入不要做任何转义处理第二层脚本里增加一层参数清洗逻辑把常见的转义序列还原成原始字符。做完了这两层处理这个问题的复发率基本降为零。这种小问题在文档里是看不到的只有真跑起来才会遇到。5.3 翻车现场三AI自作主张改了脚本输出导致结果失真第三个坑更隐蔽。我的周报技能里脚本会输出本周完成12项任务这样的统计结果。结果实测的时候AI觉得这个数字看起来不够丰满在转述给用户时自己加了一句其中包括3项高优先级任务——问题是脚本根本没有输出这个信息AI是脑补的。这个问题的根源在于LLM在向用户转述脚本结果时会有润色和合理想象的倾向。我的解决办法是在SKILL.md的注意事项里写死一句话脚本返回的结果必须原样呈现给用户不得添加脚本输出之外的任何数据或结论。同时在脚本文本里用注释提醒开发者测试这类场景。做了这个约束之后AI照着脚本原文转述的比例高了很多。5.4 一个快速的排查框架把几轮翻车经验总结一下我的排查顺序固定成了四步排查步骤检查内容常用手段第一步技能有没有被正确触发看日志里AI选技能的理由第二步参数有没有被正确抽取在脚本入口打印收到的完整参数第三步脚本执行有没有报错检查stdout和stderr看异常信息第四步结果有没有失真转述对比脚本原始输出和AI最终回复这套排查框架帮我在后续的技能调试里省了很多时间。遇到问题别急着改代码先定位是哪一层的毛病对症下药效率能高一倍。6. 从单技能到技能编排superpowers的进阶用法6.1 让多个技能协作完成一条工作流把单技能跑通之后我开始琢磨一个更刺激的问题能不能让几个技能串联起来形成一条完整的工作流举个例子我做过一个周报自动生成邮件发送的组合。流程是这样AI先调用工作记录读取技能读取数据再调用周报生成技能产出周报最后调用邮件发送技能把周报发出去。全程我不需要手动干预只需要对LLM说一句帮我生成这周的周报并发给团队。实际操作下来我发现这件事能跑通的关键在于每个技能的输出格式要为下一个技能的输入做好准备。前一个技能生成的周报得是一个有固定结构的markdown文件这样下一个技能才能顺利读取。所以我在设计技能的时候会有意识地让脚本输出标准化的中间产物而不是只输出给人看的最终结果。6.2 技能的版本管理与分享技能做得多了版本管理就成了刚需。superpowers的目录结构天然适合用Git管理我自己的做法是给每个技能建独立的仓库用Git标签标记版本。更新技能的时候先看changelog再跑一遍最小可行测试确认没有破坏已有的调用链路才推送新版本。如果你想把技能分享给别人官方社区有一套约定俗成的格式核心就是保持目录结构完整、SKILL.md描述清晰、脚本依赖说明写清楚。我自己在社区里下载过别人的技能也分享过自己的最大的感受是一个技能好不好用七成取决于SKILL.md的写作质量不是脚本的技术含量。6.3 值得优先安装的几类技能对于刚上手的朋友我建议从这几类技能开始试水性价比最高文件与目录操作类批量重命名、文件归档、格式转换。这类技能逻辑简单、触发频繁适合用来理解整个工作链路。数据清洗类CSV处理、去重合并。日常办公里用到的地方很多LLM又天然不擅长精确处理结构化数据脚本正好补位。格式转换类docx转markdown、JSON转表格。这类任务步骤单一几乎不会出错。报告生成类周报、月报、会议纪要转结构化文档。这类技能最容易让你感受到AI替人干活的价值。我不建议一上来就装几十个技能。技能贵精不贵多装得太多反而稀释了AI的注意力。我自己日常高频使用的技能大概也就五六个其余的按需临时装。6.4 未来的扩展方向让技能成为团队资产到这一步superpowers在我这里的定位已经从AI工具变成了团队知识沉淀的容器。试想一下把你们团队内部的各种操作手册、数据处理规则、业务逻辑都封装成一个个标准技能新来的同事只需要对LLM说一句按照标准流程处理这份数据AI就会自动执行整套操作。这种资产的价值比任何培训文档都直接。我自己正在尝试的方向是把一些常见业务的经验规则写成技能的一部分。比如处理客户反馈时应该先分类再归档、生成报表时应该默认包含哪些指标维度——这些说不清道不明的团队默契一旦沉淀成技能的规则执行起来反而比人更稳定。踩过这么多坑之后我个人的体会是superpowers真正难的不是安装和配置而是你愿不愿意花时间去打磨每一个技能的边界和描述。它不会让AI一夜之间变成全能超人但它确实提供了一条很实在的路径让AI在你熟悉的领域里从能聊天进步到能干活。最后再分享一个小技巧技能的迭代不要憋大招先跑通一个最小场景再在真实使用中一点点磨你会发现它比想象中更快变成你离不开的帮手。