直接说结论这篇文章聊的是开发圈里那个叫superpowers的 Claude Code 技能包项目。它解决的是很多 AI 辅助编程用户最头疼的问题——模型能力很强但发挥不稳定同一句话每次执行的结果都不一样。superpowers 的思路不是再给模型加一套工具而是给模型注入一套工作流程与行为规范让它在写代码、做规划、查问题的时候都有固定的高质量套路可以循。你不需要懂什么复杂的架构装好后只需要在对话里自然提起用 brainstorming 技能走 coding 流程AI 就会自动按技能包里约定好的步骤来干活。这篇内容适合两类人一是已经在用 Claude Code 但觉得输出质量忽高忽低的人二是刚接触 skills 机制、想知道这玩意儿到底能干嘛、怎么装怎么用的新手。我会从项目本质讲起把安装、引入、核心技能拆解、日常使用中的坑、以及自己写技能的全过程都过一遍全程是可复现的操作经验。1. superpowers 到底是什么先别急着装搞清楚机制再动手1.1 技能包不是插件而是一套行为模板superpowers 是一个开源的 skills 技能包集合运行在 Claude Code 环境下。它不是 IDE 插件也不是独立的命令行工具更不是某种 API 服务。它做的事情用一句话概括就是把如何系统地完成一类任务写成标准的 Markdown 指令文件放进 Claude Code 的技能目录让 AI 在需要时自动加载这些指令并按流程执行。我举个最简单的例子。你在 Claude Code 里直接说帮我重构这个函数模型大概率会根据自己的默认喜好来改半天之后你发现它顺手改了你没让它动的部分。但如果你说用 coding 技能帮我重构这个函数它就会主动遵守技能里定义的流程先读取周边代码、梳理调用关系、明确改动边界、列出改动清单、再动手修改、最后做回归自查。整个过程的差异就像让实习生自由发挥和给实习生一套公司 SOP的区别。skills 机制本身是 Claude Code 内建的能力任何放在~/.claude/skills/目录下的文件夹只要里面有标准格式的SKILL.mdClaude Code 启动时就会扫描并记录它的名字和描述。你提到相关需求时模型会先感知到有这么个技能然后按需读取完整的指令内容。superpowers 项目的全部工作就是利用这个机制把大量工程实践沉淀成几十个高质量的技能文件。1.2 为什么叫超能力技能包的触发逻辑项目名字起得挺形象。每个 skill 其实就对应一种超能力头脑风暴时有条理地发散、写代码前先做规划、审查代码时按严重程度分级。这些能力不是模型天生稳定的而是通过指令文件训练出来的调用路径。触发逻辑大概是这样模型在接受到你的请求后会先在自己已加载的上下文里检索所有技能的 name 和 description。如果发现某个技能的描述和当前任务高度匹配它就会把那个技能对应的 SKILL.md 完整读入然后严格按照里面的步骤执行。你也可以直接点名比如用 brainstorming 技能帮我梳理这个想法这相当于强制指定技能不给模型自由发挥的余地。我一开始用过之后的最大感受是技能包本质上是把好经验固化成了好流程让随机性很强的 AI 输出变得可预期。你说一句话它不再天马行空而是有一个固定的思考脚手架。这种稳定感在项目交付时特别值钱因为你的验收标准不再是感觉这次写得还行而是它是否走完了我要求的流程。1.3 它和官方内置能力的边界在哪里需要澄清一下Claude Code 本身就有很强的代码能力为什么还要装 superpowers因为内置能力是能做什么而 skills 解决的是按什么标准做、按什么顺序做。同样是写一个 Python 爬虫默认状态下模型可能直接甩一段脚本给你但在 superpowers 的 coding 技能约束下它会先确认目标网站结构、设计异常处理、考虑限流策略、最后才给代码并且主动补充测试方案。标准不同产出质量完全不同。所以我的建议是不要把 superpowers 当成一个必须装的增强插件而是把它当成一套可选的做事标准。装不装取决于你在不在意过程质量。如果只是随手写个脚本自用默认能力够用如果是正经项目交付这套技能包能帮你省掉大量 review 和返工的时间。2. 安装与引入官方命令、手动路径和版本管理2.1 官方推荐的一键安装方式安装方面项目 README 里有推荐的一键安装命令本质是调用 Claude Code 自带的技能安装机制从 GitHub 拉取项目并自动放入用户级技能目录。我当时执行之后Claude Code 会在终端输出安装进度显示每个技能文件夹被复制到~/.claude/skills/下。这里要提醒一句一键安装省事但装完之后你未必知道装了什么、放在哪里。我建议不管用什么方式装装完都去做一件事打开~/.claude/skills/目录逐项看一遍。这不仅能帮你理解技能结构还能给你后续自己写技能打基础。目录里每个子文件夹都代表一个独立技能里面至少有一个SKILL.md部分技能还带scripts/子目录存辅助脚本、reference/存参考资料。整体结构类似~/.claude/skills/ ├── brainstorming/ │ ├── SKILL.md │ └── scripts/ ├── coding/ │ ├── SKILL.md │ ├── reference/ │ └── scripts/ ├── code-review/ │ └── SKILL.md ├── debugging/ │ └── SKILL.md └── ...其余技能2.2 手动 Clone 软链我推荐的稳妥路径如果你对安全比较敏感或者想精确控制版本我更推荐手动方式先把仓库 clone 到本地再用软链接把它映射到 Claude Code 的技能目录。git clone https://github.com/GavinPacini/superpowers.git ~/superpowers mkdir -p ~/.claude/skills # 把仓库里的 skills 目录下所有技能都软链到用户级技能目录 ln -s ~/superpowers/skills/* ~/.claude/skills/走软链而不是直接复制的好处有三个第一后续升级只需要git pull不需要重新拷贝避免版本混乱第二你随时可以打开~/superpowers的原始目录审查内容所有技能文件一目了然第三如果你同时管理多台机器可以用统一的代码仓库来同步技能版本。需要注意软链之后要确认目标目录下是技能文件夹的直接链接而不是嵌套了一层目录。我见过有人把整个 superpowers 仓库作为一级目录链进去导致 Claude Code 扫描不到任何技能因为真正的技能文件在仓库/skills/下面。检查方法很简单ls -la ~/.claude/skills/看到的是brainstorming、coding这些名字就说明链接对了如果看到的是一个superpowers文件夹那就是嵌套了得再进一层。2.3 如何确认技能已成功引入安装完成后不急着直接进入工作流先做一次确认。重启 Claude Code 会话然后在对话里输入类似列一下你现在能用的 skills或者你加载了哪些技能模型会把它感知到的技能清单和描述输出给你。看到brainstorming、coding、debugging、writing-plans这些名字基本就说明引入成功了。这里有个经常被忽略的点技能的扫描只发生在 Claude Code 启动时。如果你在会话中途安装或更新了技能当前会话不会自动感知必须重启新会话才能生效。我一开始踩过这个坑装完就在原会话里问模型你新增了什么技能它一脸茫然我还以为是安装失败了白折腾了好一阵。另外如果你在项目里想只给这个项目用某些技能可以把技能放到项目根目录的.claude/skills/下而不是用户级目录。用户级技能对所有项目可见项目级技能只对当前项目可见。两者优先级上项目级会覆盖用户级同名技能这个机制适合团队场景每个人本地可以有一套通用技能某个特殊项目再单独放定制技能。3. 拆解核心 skills实测哪些技能真正值得反复用3.1 brainstorming 与 planning把模糊需求变可执行方案superpowers 里我使用频率最高的技能之一就是brainstorming。你可能觉得头脑风暴不就是让 AI 给点子吗用得着专门装个技能实际用下来发现它有一套完整的流程先澄清目标再分维度发散最后收敛成可评估的选项列表。它不会一上来就给你十个方案而是先逼你把问题定义清楚。我举一个真实场景。我最近想做一个内部工具需求只有一句话帮我做个批量重命名文件的脚本。我直接说用 brainstorming 技能梳理一下这个需求它会先问我重命名的规则是什么是否要处理文件夹嵌套要不要支持预览和回滚命名冲突时怎么处理这些问题的顺序是有讲究的它是在逐层收敛——先明确边界再确认约束条件最后才谈实现。一轮下来原本模糊的做个脚本变成了包含输入输出、异常处理、边界情况的完整需求描述后续写代码的返工率大幅下降。planning 技能则是 brainstorming 的下一步。需求厘清之后它负责把任务拆解成带依赖关系的实施计划输出一份结构化的步骤清单每步包含目标、涉及文件、验收标准。我在做一个小型 Web 服务时用过一次它把任务拆成了环境初始化、数据模型定义、API 路由、前端页面、联调测试五个阶段并且标注了先后依赖。这种能力在任务大的时候特别值钱等于让 AI 先当了一次架构师再回来当程序员。3.2 coding 与 code-review让 AI 按工程标准写代码、审代码coding技能是 superpowers 的核心输出位。它不是一个写代码的提示词而是一套编码规范工作流动手前先读文件结构、分析改动影响、参考项目已有的代码风格、编写单元测试、最后做自检。我实际用下来的感觉是它特别适合跨文件改动的场景。有次我需要重构一个模块的接口签名牵涉到十几个调用点。没开技能的时候模型改完主文件就完事了调用点全红开了 coding 技能后它会主动列出所有受影响的调用点、逐个修改、再跑测试验证整个过程的思路非常接近一个谨慎的工程师。这套先规划、后执行、再验证的流程成本并不高但能极大减少改完代码后的连锁错误。code-review技能则是我在代码交给同事之前的一道自查闸门。它会按严重程度对问题分级从阻断性问题bug、逻辑错误到风格问题命名、格式逐一列出。我特别喜欢它的一点是它不是简单说这代码有问题而是会给出问题原因和改法建议还会标注哪些是必须改的、哪些是可选的。有次我提交前跑了一遍它抓出了一个并发场景下的竞态条件这种东西靠肉眼看很容易漏掉。3.3 debugging 与 research定位问题和检索信息的正确姿势debugging技能的使用频率在我这里排第三。它的流程是先让用户描述问题现象再要求提供日志和最小复现步骤然后建立可能原因的排查清单最后逐条验证。这套流程听起来简单但实际价值在于它能逼你先复制问题再修问题。我印象最深的一次是排查一个偶发性的内存泄漏。我本来打算直接贴代码让 AI 找问题debugging 技能却先让我描述触发条件、给出堆内存快照、说明复现频率。按这个思路走下来很快发现泄漏出现在某个特定输入分支而不是整段代码通病。如果一开始就让 AI 直接看代码它大概率会在无关区域浪费大量时间。先锁定范围、再深入定位这八个字就是 debugging 技能最值钱的逻辑。research技能适合需要查阅大量资料的任务。它会先帮你规划检索维度再按维度去收集信息最后以结构化笔记的形式输出。我在调研一个第三方库的替代方案时用过一次它把候选库的功能范围、许可证、维护活跃度、社区口碑分别整理成表格比我自己漫无目的地搜索高效得多。这四个技能基本构成了我日常的主力阵容brainstorming 澄清需求planning 排实施计划coding 落地debugging 兜底排障。如果你装完不知道从哪下手我建议就从这四个开始用起。4. 实际使用中的配置细节与高频踩坑记录4.1 权限与安全问题脚本不是拿来就能跑的superpowers 里有一部分技能带有辅助脚本例如 organizing 类技能可能会调用搜索脚本web 开发类技能可能会调取代码脚手架。Claude Code 在执行这些脚本前会询问你是否允许但这里有个前提你最好在安装后先手动审查一遍所有脚本的内容再决定是否放行而不是每次弹窗直接允许。我的习惯是grep -r curl ~/.claude/skills/先看哪些脚本有网络请求再逐个打开检查是否有可疑操作。正常的技能脚本通常就是读写文件、格式化代码、跑测试这类操作。审查一遍之后我会在 Claude Code 的权限设置里按目录放行减少后续的弹窗打扰。安全这种事情宁可多花十分钟也不要让一个来源不明的脚本在没有任何审查的情况下直接执行。4.2 上下文膨胀与 token 消耗为什么越用越卡这是我最想提醒新用户的一点。技能包所有技能的 description 会常驻在模型的上下文里。虽然每个技能的描述只有几句话但当技能数量达到几十个时这部分固定开销会持续占掉不少 token。更关键的是当你点名某个技能后它的完整 SKILL.md 会加载进上下文有些技能文档几千字一加载就吃掉一大块上下文窗口。所以我的经验是不是所有技能都要装上只装你真正高频使用的。项目管理类、写作类、数据分析类这些如果你用不上完全可以从目录里移除或者单独建一个轻量技能目录只放核心几个。我目前的主力配置只保留了 brainstorming、planning、coding、debugging、code-review、research 这六个其余的都挪到了备份目录。另外如果你发现会话响应越来越慢先别急着怪网速很可能是上下文已经被技能文档和对话历史塞满了。这时候可以开一个新会话把旧会话的关键结论带过去继续而不是在同一个会话里硬扛。4.3 子代理模式省上下文的关键打开方式Claude Code 支持子代理Subagent机制子代理在独立的会话里执行任务只把最终结果回传给主会话。superpowers 里有一批技能在设计上就是为子代理场景准备的典型如 research、code-review它们产生的中间步骤和过程数据比较多如果全在主会话里跑上下文一下就顶满了。我的标准操作是在主会话里说用 research 技能但放到子代理里执行只把结论总结给我。这样主会话只拿到一份精炼的结果报告所有中间检索内容都留在子代理的上下文里主会话的上下文消耗能降到原来的几分之一。这个方法特别适合长对话场景主会话要保持足够的窗口给后续的编码和调试留空间。4.4 安装与调用中的问题排查链路我把自己踩过的坑整理成一个排查清单遇到问题按顺序检查可以省不少时间现象可能原因排查动作模型说感知不到技能路径放错/软链嵌套ls ~/.claude/skills/确认目录名是技能名不是仓库外层目录装了新技能但当前会话不生效Claude Code 启动时才扫描技能退出会话并重启新会话技能能感知但调用后没按流程走技能描述与当前任务匹配度不高直接在提示词里点名严格按 XX 技能流程执行脚本执行被拒绝权限未放行审查脚本后在权限设置里对该目录放行上下文消耗异常快加载了过多技能/未用子代理精简技能数量尽量把独立任务丢给子代理坦白说技能包本身出问题的概率很低绝大多数问题出在环境没配对上。按这个清单排查下来基本十分钟内能解决。5. 从装好到定制写一个属于自己的 skill 并让它生效5.1 SKILL.md 的标准格式与其一直用别人的技能包不如自己写一个这样你才能彻底理解这套机制。一个技能的文件夹里最重要的就是SKILL.md它的结构分两部分YAML 头信息和正文指令。--- name: my-awesome-skill description: 当用户需要XXX时使用该技能。它会先做A再做B最后输出C。 --- # 技能名称 ## 第一步收集信息 - 明确输入约束 - 输出结构模板 ## 第二步执行主流程 详细描述每个动作... ## 第三步输出与校验 定义成品的验收标准name和description是模型感知技能的关键字段。description 一定要写清楚什么时候用、用了之后做什么、最终产出什么因为模型就是靠这段文字来判断要不要调用这个技能的。正文部分要尽量结构化用步骤、清单、模板来约束模型的行为。模型越到细节越听话这和你给新员工写 SOP 是一个道理。5.2 一个可复用的自定义 skill 模板拿我自己写的python 脚本自动化测试技能举例需求是每次写完脚本后自动生成测试用例并执行。SKILL.md 正文我大概这样组织--- name: python-script-tests description: 指定要测试的 Python 脚本路径时使用。该技能会分析脚本核心逻辑、生成测试用例、执行测试并汇总结果。 --- ## 1. 脚本分析 - 读取目标脚本找出所有可独立测试的函数 - 整理输入参数、返回值、异常分支 ## 2. 测试用例生成 - 为每个函数创建正常路径用例、边界用例、异常用例 - 使用 pytest 框架 ## 3. 执行与报告 - 运行 pytest -q收集通过/失败/错误统计 - 输出失败的堆栈和修复建议这个技能写完之后我在对话里说用 python-script-tests 测试一下刚才那个脚本它就会严格按三段流程执行。相比默认状态下模型写代码时测试爱做不做的习惯自定义技能的价值就是把你个人的工作标准固化下来。5.3 让自定义 skill 无缝进入 superpowers 体系自己写的技能可以有两种方式接入。一种是直接放进~/.claude/skills/目录和 superpowers 技能平级共存另一种是 fork 整个 superpowers 仓库把自己的技能加进它的 skills 目录这样后续拉最新版本时自定义技能也跟着走。我推荐第二种原因是可以利用 git 做版本管理。我在本地维护一个 forksuperpowers 上游更新了就合并我的自定义技能也完全不冲突。目录安排上我会把自己的技能统一放在skills/下并列从来不改上游文件这样合并时不会有冲突。如果你不想 fork只把这些自写技能放在~/.claude/skills/下共存也完全没问题。系统不关心技能是从哪来的它只关心目录结构是否符合标准。把自定义技能和 superpowers 混编在一起调用逻辑完全一致。6. skills 与 MCP 工具搭配使用时的边界问题6.1 两者的定位差异一个管流程一个管操作很多把 Claude Code 玩得比较深的人电脑里同时装了 superpowers 和一堆 MCP 服务器比如数据库 MCP、文件系统 MCP、浏览器 MCP。两者确实容易让人混淆但定位非常清晰MCP 是手给模型提供操作外部系统能力比如查数据库、调用 API、读写文件。skills 是大脑流程教模型在什么场景下按什么顺序做事。我用一个生活类比来解释MCP 是厨师手里的锅碗瓢盆skills 是菜谱。没有菜谱给你再好的锅你也不知道先放油还是先放盐没有锅菜谱写得再好也做不出菜。两者相辅相成不冲突。6.2 混用时的两个高频问题和我现在的用法混用时最容易出现的问题是模型绕过了技能流程直接调用 MCP 工具。典型场景是你让它用 research 技能调研数据库表结构但因为装了数据库 MCP模型可能直接调 MCP 查询工具硬查而没有先走技能里定义的确认目标-列候选表-设计查询流程。解决方法是把命令下得更明确严格使用 research 技能MCP 工具仅作为技能执行过程中的数据来源。两次都这么说了之后模型基本就能守住边界了。第二个问题是技能和 MCP 互相抢上下文。一个带大量文档的技能加载进来再加上活跃的 MCP 工具返回结果上下文压力会翻倍。我的应对策略是分工明确技能负责生成思路和方案MCP 只在方案确定了之后去执行具体查询。这样两种机制各干各的事互不干扰上下文也能控制在合理范围内。现在我的常规工作流是这样的brainstorming 澄清需求planning 排计划涉及外部数据时用 MCP 工具做数据获取coding 技能负责落地最后 code-review 收尾。整套流程跑下来一个功能从想法到交付的路径非常清晰每一步都有据可查、可复现。这套技能包工具的组合我已经稳定用了快两个月代码质量和交付效率的提升都很明显整个过程里最值得的投资其实就是花那半小时把机制弄清楚——后面省下的全是返工时间。