这套东西叫什么就叫Superpowers名字起得挺直白——它不是一个具体功能而是一套技能管理与扩展框架。你可以把它理解成“给开发环境装外挂的操作系统”把那些重复的、手动的、靠记忆的活封装成一个个skills技能然后像装插件一样装进你的日常工作流里。装完之后你敲几个命令或者直接让 AI 助手调用就能完成以前要写一堆脚本才能搞定的事。先说清楚它能解决什么问题。做开发这些年我最大的痛点不是不会写代码而是大量时间耗在“已知怎么做但懒得重复做”的事上。写单元测试模板、跑环境初始化、整理日志、生成接口文档、处理常见的文本转换……这些事情每个都简单但架不住天天做。Superpowers 的思路就是把这些“会做的事情”标准化、模块化、可复用——你只需要把技能写好一次之后随时调用。这篇文章我会完整讲清楚它的核心设计、有哪些内置技能、怎么安装、怎么引入自定义技能以及我实际使用中踩过的坑适合正在搭建个人效率体系、或者想给团队沉淀一套共享技能库的开发者参考。1. 整体设计与思路拆解为什么需要一套“技能框架”1.1 从“零散脚本”到“技能库”的转变很多人早期是这么过来的桌面上堆满fix_log.sh、generate_test.py、clean_cache.rb这种文件临时要用就翻出来改两行再跑。时间一长脚本之间依赖混乱、参数不统一换台机器就少几个依赖包根本没法维护。Superpowers 解决的就是这个“脚本通胀”问题——它把零散脚本升级为有统一接口、有描述信息、可以被发现和调用的“技能”。一个技能本质上是一个结构化的执行单元它比单个脚本多三样东西元信息这个技能叫什么、干什么用、需要哪些参数、标准化的输入输出统一的参数解析和结果返回形式、自包含的环境要求依赖哪些包、最低版本、需要什么环境变量。你可以在项目根目录放一个superpowers.yaml里面声明用到的技能也可以用命令行随时列出当前可用的技能清单。这个设计的好处是任何一台新机器只要拉下配置、执行同步命令所有技能和环境就都准备好了不再有“这脚本在我电脑上能跑啊”的尴尬。1.2 为什么不是直接写一堆 npm 包或 pip 包我一开始也想过把这些东西直接封装成 npm 包不行吗后来发现不行。包管理器解决的是“代码分发”问题而 Superpowers 解决的是“能力接入”问题。npm 包装的是库函数调用方要自己写逻辑去拼装而 Superpowers 的技能是面向任务的它直接给你一个“完成某件事”的能力入口。再说得直白点npm 包是“砖头”Superpowers 技能是“砌好的墙”你只需要说“我要在这面墙旁边加个门”剩下的细节技能内部处理了。这也带来了一个实际好处非核心开发者也能用。团队里不是每个人都熟悉所有工具链。以前让运维同事跑一个 Python 脚本他得装 Python、装依赖、改路径现在他在 Superpowers 里一键调用输入参数拿结果完事。门槛低了协作效率自然就上去了。1.3 核心概念技能包、运行时与市场Superpowers 的架构围绕三个核心概念展开概念作用比喻技能包Skill Pack一组相关技能的集合可整体安装/卸载一盒乐高积木运行时Runtime负责技能加载、参数校验、执行和日志乐高底版技能市场Marketplace在线技能仓库一键搜索和安装应用商店运行时是常驻的它可以作为一个命令行工具存在比如sp run skill-name也可以作为一个本地服务被 IDE 插件或 AI 助手调用。技能市场则解决了“发现”的问题——你不需要先知道某个技能存在再去搜文档你直接在市场里搜关键词就能找到合适的技能来安装。我自己的体会是有了这个之后很多“原来没想过能自动化”的事情反而因为逛市场发现了新思路。2. 核心技能模块解析开箱能用的那些 skills2.1 开发者常用技能包详解Superpowers 官方市场里维护了一批高质量的技能包覆盖了日常开发的常见场景。我用了一段时间挑几个最常驻的给大家拆一下。文本与编码处理包。这个包里有text-transform、encoding-convert、template-render这类技能。text-transform支持大小写转换、驼峰/下划线互转、字符串截取和替换encoding-convert可以在 UTF-8、GBK、Base64、URL 编码之间互转。听起来简单但实际用起来非常省时间——我处理一批遗留系统导出的 GBK 编码的 CSV 文件以前要写个 Python 脚本现在直接sp run encoding-convert -i input.csv -f gbk -t utf-8就完事了。项目脚手架包。这个包提供init-python-project、init-node-project、init-rust-project等技能。它们和create-next-app这类工具的区别在于更注重“团队规范一致性”你可以配置好模板仓库技能会按模板生成项目结构同时自动配置好 ESLint、Prettier、提交信息规范等。新成员入职之后跑一遍技能项目骨架就按团队标准搭好了不用再对着 README 一条条手动配置。测试辅助包。里面有gen-test-stub、mock-http-server、coverage-summary几个技能。gen-test-stub会扫描源文件为每个公开函数生成测试桩代码附带边界值提示mock-http-server可以快速起一个本地 Mock 服务模拟接口响应用于前端联调coverage-summary则是把覆盖率报告汇总成年月维度的趋势表格方便在周报里直接引用。这几个技能组合起来基本覆盖了一个迭代周期里测试相关的琐碎工作。文档生成包。这个我必须单独夸。写文档是绝大多数开发者最抵触的事但只要一个技能就能把文档从负担变成顺手的事。gen-api-doc能读取 OpenAPI 规范或者直接扫描路由注解自动生成接口说明文档输出 Markdown 或 HTMLgen-changelog能根据 Git 提交记录自动聚合生成变更日志按 Conventional Commits 规范分类。自从用了它我的 CHANGELOG.md 再也没手写过。2.2 社区技能包与自定义技能体系除了官方维护的常用包市场里还有大量社区贡献的包覆盖了 CI 辅助、云资源巡检、日志分析等细分领域。社区包的质量参差不齐是正常的但 Superpowers 提供了一套技能健康度评分——包括下载量、最近更新时间、测试覆盖率和用户评分——可以帮助你判断该不该用。更高级的用法是写自己的技能包。一个自定义技能的结构一般是这样的my-skill-pack/ ├── pack.yaml # 技能包元信息名称、版本、依赖 ├── skills/ │ ├── daily-report/ # 技能目录 │ │ ├── skill.yaml # 技能定义描述、参数、入口 │ │ ├── run.py # 实现逻辑 │ │ └── assets/ # 需要的模板或其他静态资源 │ └── ... └── tests/ # 技能的测试用例技能定义文件skill.yaml是核心它声明了这个技能的入参、出参和执行方式。Superpowers 运行时支持python、node、shell三种执行类型你可以根据技能逻辑的特性选择最合适的实现语言。我自己常用的实践是数据密集型逻辑用 Python前端相关的小工具用 Node纯系统操作直接用 Shell。3. 安装与引入技能的实操指南从零到一跑起来3.1 安装 Superpowers 运行时Runtime安装过程不复杂但有些细节值得注意。官方推荐的方式是通过命令行安装脚本执行curl -fsSL https://get.superpowers.dev/install.sh | bash安装脚本会自动检测你的操作系统和架构macOS 的 arm64、Linux 的 x86_64 等下载对应的运行时二进制文件并把它放到~/.local/bin下。安装完成后需要把运行时路径加到 shell 的 PATH 环境变量里脚本默认会在.bashrc或.zshrc里追加一行。这里有个容易踩坑的地方如果你用的是fishshell脚本可能不会自动帮你配置需要手动在~/.config/fish/config.fish里加上set -gx PATH $HOME/.local/bin $PATH安装完执行sp doctor可以验证环境是否正常。它会检查运行时版本、配置目录权限、是否有可用更新。我第一次跑的时候提示配置目录不存在sp doctor直接帮我初始化好了。另外Superpowers 依赖系统里已有的git和curl如果你在精简版容器环境里记得提前装好。3.2 引入官方技能包一步步操作演示运行时装好之后引入官方技能包是熟悉这套体系的最好方式。按下面步骤操作搜索技能包sp search testing这个命令会在市场里搜索所有描述中包含“testing”的包返回包的名称、简介、评分和维护状态。搜索结果里会有个verified标签优先选这类官方验证过的包稳定性要好很多。安装技能包sp install testing-toolkit安装过程会下载包文件到~/.superpowers/packs/目录同时解析依赖关系并安装依赖包。值得说明的是这里的依赖既包括 Superpowers 技能层面的依赖也包括技能运行时需要的第三方库。技能包安装器会尝试自动安装 Python 或 Node 依赖如果安装失败会给出重试建议。查看已安装的技能列表sp list这个命令展示所有已安装技能包括技能名、版本、来源和简要描述。列表输出支持grep过滤比如sp list | grep doc快速找文档类技能。查看技能的具体说明sp info gen-api-doc查看某个技能的详细帮助信息包括每个参数的含义、默认值、必要参数和示例命令。这一步很关键很多技能虽然功能相近但参数设计各有差异先看说明能少踩不少坑。立即运行一个技能sp run gen-api-doc -i ./openapi.yaml -o ./docs/api.md运行后会在终端实时输出进度日志。运行日志存放在~/.superpowers/logs/下如果技能执行失败日志里会记录详细的错误栈和上下文环境信息排查起来非常方便。3.3 引入自定义技能的完整流程自定义技能的可贵之处在于它沉淀的是你个人的工作方式。我来走一遍完整流程从写技能定义到验证使用。假设我要做一个“自动生成每日站会汇报”的技能它会读取我今天的 Git 提交记录和待办事项文件输出一份日报草稿。第一步创建技能包骨架sp pack init daily-standup这个命令生成基础目录结构和模板文件。第二步编写技能定义skill.yamlname: daily-standup description: 生成每日站会汇报草稿 version: 1.0.0 runtime: python entry: run.py inputs: - name: time-range type: string required: false default: 1d description: 提交记录时间范围如 1d、3d、1w outputs: - name: report type: file path: standup-report.md这里的关键在于把inputs定义清楚。参数名、类型、默认值、描述缺一不可因为它们直接关系到技能被调用时的参数解析也决定了sp info向使用者展示帮助信息的质量。写得越清晰别人包括未来的你用起来越顺手。第三步实现核心逻辑run.pyimport subprocess from pathlib import Path from datetime import datetime, timedelta def main(): time_range 1d # 实际项目里建议使用 superpowers 提供的参数注入机制 # 这里为清晰演示直接解析。 commits subprocess.run( [git, log, f--since{time_range}, --oneline], capture_outputTrue, textTrue ).stdout.strip() todo_path Path(todo.md) todo_items [] if todo_path.exists(): todo_items [line for line in todo_path.read_text().splitlines() if line.startswith(- [ ])] report f# 站会汇报 {datetime.now():%Y-%m-%d}\n\n## 昨日提交\n{commits}\n\n## 待办事项\n \n.join(todo_items) Path(standup-report.md).write_text(report, encodingutf-8) print(报告已生成standup-report.md) if __name__ __main__: main()实现逻辑本身不复杂重点是保持技能的单一职责——它只做一件事但做到清晰可靠。如果逻辑多了就应该拆成多个技能而不是塞进一个。第四步本地验证sp run daily-standup -t 1d运行成功后在项目目录生成了standup-report.md。我建议把自己的技能先放到团队的公共仓库通过 Git 管理版本别人拉下来直接用sp pack install ./daily-standup就能安装。4. 具体使用场景与配置示例让技能真正融入工作流4.1 日常开发中的组合技一次命令完成多项任务Superpowers 真正强的是组合使用技能。单独用每个技能只是自动化了单点操作把它们串起来才能体现出“超能力”的含金量。我分享一个典型的实战组合——接手一个遗留项目后做完技术债梳理的过程。以前我需要手动干这些事读取项目文档梳理模块结构、统计测试覆盖率、扫描未使用的依赖、整理接口清单。这个过程大概要小半天。现在我用三条命令串起来sp run gen-api-doc -i ./src/routes -o ./docs/legacy-api.md sp run coverage-summary --project-dir . --format table sp run dep-scan --ignore dev --output unused-deps.txt三条命令跑完接口文档、覆盖率趋势、依赖分析全部到手大概几分钟。再花点时间把结果整理进项目 wiki整个交接期的信息透明程度高了一大截。这一个组合就直接体现了技能框架相比孤立脚本的核心优势统一的参数风格和输出格式让组合本身变得简单自然。4.2 与 AI 助手协作给模型装上“技能调用”的能力Superpowers 一个特别受关注的使用方式是作为 AI 助手的“工具层”。它提供了一种 MCP模型上下文协议兼容的接入方式——概念上可以理解成一个桥梁让 AI 模型在生成回复时能够按需调用你本地的技能。接入方式很简单sp mcp start --transport stdio启动一个本地 MCP 服务把这个进程配置给 AI 客户端目前主流支持 MCP 的桌面客户端和开发插件都能直接用。配置好之后你可以在对话里直接说“帮我把 openapi.yaml 生成接口文档”AI 会识别这个意图、调用对应的gen-api-doc技能、返回结果给你。这么多人大力推荐这个模式不是因为 AI 能“学会”某个技能的细节而是技能框架很好地解决了 AI 生成代码时“看着对但跑不通”的老问题。AI 不需要自己写一遍实现逻辑它直接调用你已经验证过的、环境就绪的技能输出自然就是可靠的。这个思路也是我建议团队引入 Superpowers 的强大理由——AI 落在团队里的地位从“偶尔帮写代码的”变成了“能安全调用内部工具的得力助手”可控性提高了一大截。4.3 配置进阶技能别名、环境变量与加密数据配置这块有三个小进阶技巧值得了解。技能别名alias如果某个技能名太长或者你想用团队习惯的缩写可以在~/.superpowers/config.yaml里配别名aliases: gen-api-doc: gad gen-changelog: gcl coverage-summary: cov之后直接用sp run cov就能跑输入输出和原名一致。环境变量env很多技能在执行时需要读取环境变量比如云厂商的密钥、数据库连接串等。可以写在技能定义文件里声明env: - name: CLOUD_ACCESS_KEY required: true description: 云平台访问密钥 - name: LOG_LEVEL required: false default: INFO运行时会把声明的环境变量从当前 shell 环境中继承并传进技能进程。特别要注意技能定义里永远不要直接写明文密钥应该引用环境变量名称。加密数据secrets对于真正的机密信息如上云密钥的私钥文件Superpowers 提供了一个sp secret命令把加密后的值存入~/.superpowers/secrets.json运行时只在使用那一刻解密并注入环境变量。加密用的主密钥可以从系统钥匙串macOS 的 Keychain 或 Linux 的 Secret Service读取不落地明文到磁盘。这点对团队共享技能库时尤其重要——技能包可以公开但 secrets 是个人本地的。5. 常见问题与排查技巧实录5.1 安装和运行阶段的典型问题我在使用过程中踩过不少坑也帮团队同事排查过一些问题整理成速查表现象常见原因解决办法sp命令找不到安装后 shell 没有重新加载配置执行source ~/.bashrc或重开终端技能安装失败网络受限或依赖源不可达配置镜像源重试或直接把技能包 clone 到本地安装技能运行超时技能内部逻辑阻塞查看~/.superpowers/logs/下日志定位卡住的步骤输出结果中文乱码技能子进程编码不匹配在技能执行命令前设置export PYTHONIOENCODINGutf-8依赖冲突不同技能依赖同一库的不同版本优先使用隔离运行环境每个技能独立 venv见下文参数明明是必需的却报“未找到”参数名大小写或拼写不一致用sp info skill查看参数定义严格按定义传参技能结果和预期不符本地环境变量未注入或数据源变化打印技能传入的环境变量列表核对是否一致5.2 排查超时和依赖问题时的方法论超时问题的排查我先给一个小技巧临时给技能传入更长的超时时间同时打开详细日志sp run>sp install testing-toolkit --isolated安装时创建一个独立的 Python venv后续这个技能的所有依赖都装在里面互不干扰。代价是多占一些磁盘空间但对于依赖冲突严重的团队来说这个取舍很划算。5.3 我总结的避坑心得和实用建议踩过这些坑后我给自己定了几条使用规则也推荐给刚开始用的人参考。第一次用某个技能前先跑一遍它的测试。每个技能包通常自带测试用例安装后执行sp test pack-name跑一遍确认在当前环境下所有用例都通过再实际使用。这一步几十秒能省去后面几小时的排查时间。写自定义技能时把“非法输入”处理得尽量严格。不要假设调用者一定会传合法的参数。参数校验的逻辑宁可写多一点也不要让一个非法参数引发后续步骤的连锁报错。运行时支持的 schema 校验功能可以声明参数的取值范围和格式用起来。技能版本一定要显式锁定。刚开始用的时候大家都喜欢装最新版但升级之后技能行为变化导致结果对不上排查起来非常消耗时间。现在我的做法是技能包安装后在superpowers.yaml里锁定版本号团队协作时同步这份文件保证所有人用的都是同一版本。多关注官方市场和社区动态及时更新已被标记为“维护中”的包。有些核心技能包维护者会在新版中修复已知问题、适配新语言版本保持更新能少踩很多雷。不过更新之前记得看一眼变更日志确认没有破坏性变更。6. 从一个人用到团队协作Superpowers 的推广建议6.1 让团队技能库从“个人玩具”变成“公共基建”自己用得好了自然想推荐给团队。但直接扔给同事说“你用这个吧”效果通常不好——每个人工作习惯不一样一上来就装一堆技能包反而会让人抵触。我推荐循序渐进的方式先从团队里大家都会遇到的痛处下手挑两三个普适性强的技能比如gen-changelog、mock-http-server、text-transform配上简单场景说明让他们感受到“这东西确实能帮我省时间”就够了。等第一批人用起来了再逐步把团队特有的流程技能比如项目初始化、部署前检查、数据迁移脚本做成自定义技能包放到内部 Git 仓库里统一管理。注意团队技能库要配一个明确的owner角色负责 review 技能变更、维护文档、处理紧急故障。技能库不是写完就完事了它和代码库一样需要持续养护不然很快会腐烂成新的“历史包袱”。6.2 沉淀一批团队级技能包的设计模式经过这段时间的实践我总结了几个设计团队技能包时的原则写在这里和大家分享。技能粒度是“任务”级别而不是“操作”级别。与其做一个“读取数据库配置”的技能不如做一个“同步数据库Schema”的技能。前者只是操作后者才是用户真正关心的任务。技能的设计应该面向使用者的目标而不是面向内部实现细节。技能之间不要直接互相调用。如果两个技能有公共逻辑把它拆成共享的辅助库或者留在技能自己内部做重复实现。技能之间保持独立是为了能单独替换、升级和测试。一旦出现 A 技能依赖 B 技能的运行环境整个体系就变得非常脆弱。技能的名字和描述要写得像搜索引擎索引一样清晰。团队成员会用sp search去找技能如果你的技能描述模糊不清就没人敢用。多用动词开头说清楚这个技能能帮你完成什么任务而不是技术细节。6.3 结合我在实际工作里的收获做最后分享最后再说点个人体会。Superpowers 对我最大的影响不是“省了多少时间”而是它改变了我的思维方式——每当我发现自己在做第三次重复操作的时候第一反应已经变成了“是不是该把这个封装成一个技能”。这种“自动化优先”的心智习惯才是这套框架真正留给我的财富。对于正准备引入的人我也给出一个具体建议不要妄想一次把所有东西都自动化。先选一个你每周都会做、步骤相对固定、耗时大概在 15 分钟以上的任务把它做成第一个技能。做完你会立刻感受到那种“以后再也不用手动做这件事了”的快感这份正反馈会支撑你持续做下去直到你的工作流越来越接近“全自动”。技能库的建设是个滚雪球的过程起初慢越到后面越顺。希望这篇内容能帮你顺利迈出第一步。