1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去看完之后我的第一反应是这东西本质上不是又一个“提示词合集”而是一套软件研发方法论的工程化封装。说得再直白一点superpowers 想做的事情是把“一个资深工程师在接到需求之后怎么拆任务、怎么选工具、怎么验证结果、怎么沉淀经验”这一整套思维流程变成 AI 编程助手可以稳定复用的技能模块。它面向的不是“让 AI 帮我写个快排”这种一次性需求而是“让 AI 像一个有纪律的工程团队成员一样持续参与真实项目的开发”。这就引出了它和 Claude Code、Codex CLI 这类工具的关系。Claude Code 和 Codex CLI 是“执行器”它们负责在终端里读文件、改代码、跑命令而 superpowers 更像是“操作系统层”的东西它定义了这些执行器在什么场景下该调用什么技能、按什么顺序执行、产出什么样的中间产物。你可以把它理解成给 AI 编程助手装了一套“职业素养培训体系”。为什么这件事值得单独拿出来聊因为过去大半年我见过太多人装完 Claude Code 之后第一反应是“哇它能直接改我代码”第二反应是“但它改得乱七八糟”。问题不在于模型能力不够而在于缺少一套约束机制——什么时候该先读文档、什么时候该先写测试、什么时候该停下来问人。superpowers 这类框架的价值恰恰在于把这些“工程直觉”显式化、模块化。这篇文章适合三类人看一是已经在用 Claude Code 或 Codex CLI但觉得输出质量不稳定、想找一套方法论来兜底的开发者二是正在评估要不要把 AI 编程助手引入团队工作流的技术负责人三是对 agentic skills framework 这个概念感兴趣想搞清楚它和普通 prompt engineering 区别在哪的人。我会尽量把安装配置、核心机制、实操踩坑都讲透让你看完能直接上手试。2. 核心设计思路拆解为什么是“技能框架”而不是“提示词库”2.1 从提示词工程到技能工程的关键跃迁大部分人接触 AI 编程的路径是这样的先学会写 prompt然后发现 prompt 越写越长最后变成一个几百行的“系统提示词”。这种做法在单次任务里还行一旦任务变复杂、步骤变多就会暴露两个致命问题上下文漂移和技能不可复用。上下文漂移是指当对话轮次变多模型会逐渐“忘记”最初设定的规则。你在一开始写了“所有代码必须带类型注解”聊到第十轮它就开始写无类型代码了。技能不可复用是指你为 A 项目精心调教的提示词换到 B 项目几乎要重写一遍因为项目结构、技术栈、团队规范都不一样。superpowers 的设计思路是把“提示词”升级成“技能”。一个技能不是一段文字而是一个有明确输入输出、有触发条件、有验证标准的模块。比如“写单元测试”这个技能它的输入是“一个待测试的函数”输出是“一组覆盖边界条件的测试用例”触发条件是“用户要求实现新功能或修改现有逻辑”验证标准是“测试能跑通且覆盖率达标”。这种设计带来的直接好处是技能可以被组合、被替换、被版本管理。你可以今天用 A 技能写测试明天换成 B 技能只要接口一致上层工作流不用改。这跟微服务架构的思路是一模一样的——把能力拆成独立单元通过标准协议通信。2.2 为什么选择与 Claude Code、Codex CLI 深度绑定有人可能会问为什么不做一个独立的 IDE 插件非要绑定终端工具我的理解是终端是 AI 编程助手最自然的栖息地。原因有三第一终端能直接访问文件系统和命令行这是 AI 改代码、跑测试、查日志的基础能力。IDE 插件受限于编辑器 API很多操作要绕弯。第二终端工具天然支持“人在回路”的交互模式AI 执行一步、人确认一步这比全自动改代码安全得多。第三Claude Code 和 Codex CLI 都已经解决了“模型怎么调用工具”这个底层问题superpowers 只需要在上面定义“什么时候调用什么工具”。从实际使用体验来看Claude Code 的/compact、/model、/resume这些命令本质上就是给技能框架预留的“控制接口”。/compact用来压缩上下文防止漂移/model用来切换模型应对不同复杂度任务/resume用来恢复会话支持长周期项目。这些命令单独看很普通但放在技能框架里就变成了工作流的控制节点。2.3 技能模块的粒度设计多大算一个技能这是我在实际使用中踩过的最大的坑。一开始我把技能切得太细比如“读文件”“写文件”“跑命令”各算一个技能结果发现调度开销比执行开销还大。后来又把技能切得太粗一个“实现功能”技能包打天下结果又回到了提示词工程的老路。比较合理的粒度是按“工程活动”来切。一个工程活动通常包含多个原子操作但有明确的起止点和交付物。比如技能名称输入输出典型原子操作需求澄清模糊需求描述结构化需求文档提问、查文档、写摘要方案设计需求文档技术方案任务拆解读现有代码、画架构、列任务功能实现单个任务可运行代码写代码、改文件、跑测试代码审查代码变更审查意见读 diff、查规范、写评论问题排查错误现象根因修复方案读日志、复现、定位、修复这个粒度下每个技能大概对应 5 到 15 分钟的 AI 工作时间人可以在每个技能结束后介入检查既不会太频繁打断也不会让错误累积到不可收拾。3. 环境准备与工具链搭建从零到能跑通第一个技能3.1 Claude Code 的安装与基础配置先说 Claude Code 的安装。官方文档给的路径是最稳的但国内网络环境下经常会遇到note: claude code might not be available in your country这类提示。我的建议是先把基础环境准备好再处理账号和网络问题。在 macOS 上最省事的方式是用 npm 全局安装npm install -g anthropic-ai/claude-code装完之后跑claude --version确认版本。如果提示命令找不到检查 npm 全局 bin 目录有没有加到 PATH 里。Ubuntu 上的步骤类似但要注意 Node.js 版本不能太低建议 18 以上。我试过在 Ubuntu 22.04 上用 Node 16 装跑起来各种奇怪的报错换成 Node 20 之后一切正常。Windows 用户要注意一个坑claude code 由于与64位版本的windows不兼容这个报错通常是因为装了 32 位的 Node.js。去官网重新下 64 位安装包覆盖安装就行。另外 Windows 上建议用 WSL2 而不是原生 PowerShell文件路径和权限问题会少很多。配置方面核心是两件事模型接入和权限控制。模型接入默认走官方账号如果你有第三方 API 或者想接本地模型比如通过 LM Studio 跑的模型需要配置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。这里不展开具体服务商只说配置方法export ANTHROPIC_BASE_URL你的服务地址 export ANTHROPIC_API_KEY你的密钥权限控制是很多人忽略的。Claude Code 默认会问你“是否允许执行这个命令”如果你嫌烦可以配置白名单但我的建议是前期不要开全自动至少用一周时间观察它都会执行哪些命令心里有数之后再逐步放开。3.2 Codex CLI 的安装与命令体系Codex CLI 的安装更简单它是个独立的二进制文件从官方仓库下载对应平台的版本就行。装完之后核心要掌握的命令不多但每个都要用熟/compact压缩当前会话上下文。当你感觉 AI 开始“忘事”或者响应变慢时跑一下这个它会总结之前的对话并丢弃冗余信息。/model切换模型。简单任务用小模型省钱复杂任务切大模型保质量。/resume恢复之前的会话。长周期项目必备不用每次从头解释背景。/clear清空当前会话。跟/compact的区别是它不保留摘要彻底重来。删除 Codex CLI 也很简单找到安装目录直接删掉二进制文件再把 PATH 里的相关配置清理掉就行。但删之前建议把~/.codex目录下的配置和会话记录备份一下里面可能有你调教好的技能配置。3.3 VS Code 集成让编辑器成为技能框架的前端claude code for vs code这个插件我用了大概两个月最大的价值不是“在编辑器里聊天”而是它能把当前打开的文件、选中的代码片段、终端输出自动作为上下文传给 Claude Code。这省掉了大量“复制粘贴给 AI 看”的操作。配置步骤不复杂在 VS Code 扩展市场搜 Claude Code安装后重启然后在设置里填 API 配置。如果遇到your organization has disabled claude subscription access for claude code这个提示说明你的账号类型不支持需要换成 API 计费模式或者用第三方接入。VS Code 插件的使用技巧有几个一是用CmdShiftP调出命令面板搜 “Claude” 能看到所有可用命令二是选中代码后右键可以直接“发送到 Claude”三是终端里跑的 Claude Code 会话插件能自动同步上下文。这三点用熟了效率提升非常明显。4. 核心技能模块的实操拆解以“功能实现”技能为例4.1 技能定义文件的结构与编写要点superpowers 框架里每个技能通常用一个 Markdown 文件定义放在项目的.skills目录下。文件结构一般包含四个部分元信息、触发条件、执行步骤、验证标准。元信息部分写技能名称、版本、依赖的其他技能。触发条件用自然语言描述“什么情况下该用这个技能”写得越具体越好。执行步骤是核心要拆到“AI 能一步步跟着做”的粒度。验证标准是很多人会漏掉的但它恰恰是保证质量的关键——没有验证标准的技能AI 做完之后你不知道对不对。我拿“功能实现”技能举个例子实际文件大概长这样--- name: implement-feature version: 1.2 depends: [clarify-requirement, design-solution] --- ## 触发条件 用户要求实现一个已经过需求澄清和方案设计的功能点。 ## 执行步骤 1. 读取方案设计文档确认本次要实现的任务编号 2. 读取相关现有代码理解代码风格和依赖关系 3. 编写实现代码遵循项目现有的命名和注释规范 4. 编写或更新对应的单元测试 5. 在本地运行测试确认全部通过 6. 输出变更摘要包括修改的文件列表和测试结果 ## 验证标准 - 所有新增和修改的测试用例通过 - 代码通过项目的 lint 检查 - 变更摘要中明确列出每个文件的修改原因这个文件看起来简单但每一条都是踩坑踩出来的。比如“读取相关现有代码”这一步一开始我没写结果 AI 写出来的代码风格跟项目完全不搭review 的时候被同事吐槽“像两个人写的”。加上这一步之后风格一致性问题基本消失了。4.2 技能链的编排多个技能如何串起来单个技能好用但真正的威力在于技能链。一个完整的功能开发流程通常是这样串的需求澄清 → 方案设计 → 功能实现 → 代码审查 → 问题排查如果有 bug每个箭头代表一次技能切换切换的触发条件由上一个技能的输出来决定。比如“方案设计”技能输出了一份任务列表“功能实现”技能就逐个任务执行每完成一个任务就回到技能链的起点判断下一步。这里有个实操细节技能切换时要不要清空上下文。我的经验是如果两个技能共享大量背景信息比如都在同一个模块里工作就保留上下文用/compact压缩如果跨度很大比如从后端跳到前端就/clear重来避免旧上下文干扰。还有一个坑是技能循环。我遇到过“功能实现”做完之后“代码审查”发现问题又回到“功能实现”修改改完再审查来回好几轮。这本身是正常的但要设置一个上限比如三轮之后还没通过就停下来人工介入。不然 AI 会在两个技能之间无限循环烧 token 不说还可能把代码改得越来越乱。4.3 与本地模型配合用 LM Studio 跑私有技能claude code 调用 lmstudio 的本地模型这个需求我实测下来是可行的但有几个前提。LM Studio 要开启 OpenAI 兼容的 API 服务然后在 Claude Code 里把ANTHROPIC_BASE_URL指向 LM Studio 的地址。模型选择上建议至少 14B 参数以上不然复杂技能的执行质量会明显下降。本地模型跑技能框架的优势是数据不出本地适合处理敏感项目。劣势是速度和稳定性不如云端尤其是长上下文场景本地模型容易崩。我的折中方案是需求澄清、方案设计这类需要强推理的技能用云端模型功能实现、代码格式化这类确定性高的技能用本地模型。配置的时候注意一点LM Studio 的 API 默认不支持 Claude Code 用的一些高级参数需要在配置里关掉对应的功能开关。具体是哪些参数看 LM Studio 的日志报错就行它会明确告诉你哪个字段不支持。5. 常见问题与排查技巧实录5.1 安装与配置阶段的典型报错这个阶段的问题占了我在群里看到提问的一半以上。整理成表格方便对照报错信息根本原因解决方法command not found: claudenpm 全局 bin 不在 PATH把npm config get prefix的路径加到 PATHnote: claude code might not be available in your country账号地区限制检查账号类型或改用 API 计费模式your organization has disabled claude subscription access组织策略限制联系管理员或换个人账号与64位版本的windows不兼容装了 32 位 Node.js重装 64 位 Node.js连接本地模型超时LM Studio 服务没启动或端口不对确认服务运行检查端口配置这里重点说一个很多人装完之后跑claude没反应也不报错就是卡住。这种情况九成是网络问题Claude Code 启动时会尝试连接服务端连不上就静默等待。解决办法是在配置里加超时设置或者先用curl测试一下服务端地址通不通。5.2 技能执行中的“翻车”场景与补救技能执行翻车主要有三种表现改错文件、改坏代码、陷入循环。改错文件通常是因为技能定义里没写清楚“只修改哪些文件”。补救方法是在技能定义里加一条“修改前先列出将要修改的文件清单等待确认”。这个确认步骤看起来多余但能避免 90% 的误操作。改坏代码的补救靠版本控制。我的习惯是每次让 AI 执行技能之前先git commit一次这样出问题直接git checkout回滚。不要指望 AI 自己改回来它越改越乱的概率更大。陷入循环前面提过设置轮次上限是最简单的办法。另外可以在技能定义里加“如果连续两次修改同一个问题仍未解决停止并输出当前状态”给人工介入留出空间。5.3 性能与成本优化的实操经验用技能框架跑项目token 消耗比单次对话高不少因为每个技能都要读上下文、写中间产物。优化方向有三个一是技能粒度要合理前面讲过太细调度开销大太粗质量不稳定。二是善用/compact我一般每完成两到三个技能就压缩一次能省 30% 左右的 token。三是模型分级简单技能用便宜模型复杂技能用贵模型整体成本能降一半。还有一个容易被忽略的点技能定义文件本身要精简。我见过有人把技能定义写成两千字每次执行都要读一遍纯属浪费。技能定义控制在 500 字以内把详细说明放到单独的文档里需要时再读。6. 把技能框架接入真实项目一个完整案例的复盘6.1 项目背景与技能链设计上个月我接了个小项目给一个内部工具加数据导出功能。需求不复杂但涉及后端接口、前端按钮、导出格式三个部分正好适合用技能框架跑一遍。技能链设计是这样的需求澄清确认导出格式和字段→ 方案设计确定用 CSV 还是 Excel接口怎么设计→ 功能实现分三个子任务后端接口、前端按钮、格式转换→ 代码审查 → 联调测试。每个技能我都提前写好了定义文件放在项目根目录的.skills文件夹里。这里有个小技巧技能定义文件也纳入 git 管理这样团队其他人能复用也能追溯每次修改的原因。6.2 执行过程中的关键决策点执行到“方案设计”技能时AI 给出了两个方案一是后端直接生成 CSV 返回二是后端返回 JSON 前端生成 CSV。我让它把两个方案的优缺点列出来然后人工选了第一个因为数据量不大后端生成更简单。这个决策点很关键。如果完全让 AI 决定它可能会选一个“技术上更优雅但实际不必要”的方案。技能框架的价值不是替代人做决策而是把决策点显式暴露出来让人在关键节点介入。执行到“功能实现”时AI 第一次写的后端接口没有处理空数据的情况测试的时候报错了。“问题排查”技能介入定位到是边界条件没覆盖回到“功能实现”补上。整个过程大概花了 40 分钟比我自己写快不了太多但代码规范性和测试覆盖率明显更好。6.3 复盘哪些技能好用哪些需要改跑完这个项目我对技能定义做了几处修改。一是“功能实现”技能里加了“必须处理空数据和异常输入”的检查项二是“代码审查”技能里加了“检查是否有硬编码的配置项”三是给技能链加了“每个技能结束后输出一句话摘要”的要求方便回溯。不好用的技能也有。“需求澄清”技能在需求本身比较明确的时候显得多余后来我加了个判断条件如果需求描述超过 200 字且包含明确的验收标准就跳过澄清直接进设计。这套东西用下来我最大的体会是技能框架不是让 AI 更聪明而是让 AI 更稳定。它不会帮你写出惊艳的代码但能保证每次输出的质量都在及格线以上这对工程团队来说比偶尔的惊艳重要得多。7. 技能框架的扩展与团队协作7.1 自定义技能的编写规范写自定义技能我总结了一个“三要三不要”原则。三要要写清楚触发条件要定义验证标准要控制篇幅。三不要不要写模糊的步骤比如“优化代码”这种不要依赖未定义的技能不要在技能里硬编码项目路径。触发条件这块特别重要。我见过有人写“当需要写代码时触发”这等于没写。好的触发条件应该是“当用户要求实现一个已经在任务列表中的功能点且该功能点的依赖任务都已完成时触发”。条件越具体误触发的概率越低。验证标准要可量化。“代码质量好”不是验证标准“通过 lint 检查且测试覆盖率不低于 80%”才是。可量化的标准还有个好处就是能自动化检查不用人肉判断。7.2 团队共享技能的版本管理团队用技能框架最大的挑战是技能定义的版本一致性。A 同学改了“功能实现”技能B 同学不知道还在用旧版本结果两人产出的代码风格不一致。解决办法是把技能定义当成代码来管理放 git 仓库改动用 PR合并前 review。另外给技能定义加版本号技能链里引用的时候指定版本避免“上游改了导致下游崩”的情况。还有个实操细节技能定义里的“项目特定配置”比如代码规范、目录结构应该抽出来放到单独的配置文件里技能定义本身保持通用。这样换项目的时候只需要改配置不用改技能。7.3 从个人工具到团队基础设施的演进路径我观察到的演进路径大概是这样的第一阶段个人用技能框架提升自己的效率第二阶段把好用的技能分享给团队大家各自用第三阶段团队统一技能定义和技能链形成标准工作流第四阶段技能框架和 CI/CD 打通AI 产出的代码自动进入审查和测试流程。大部分团队卡在第二阶段到第三阶段之间因为统一技能定义意味着统一工作习惯这比技术问题难多了。我的建议是先从“代码审查”和“问题排查”这两个技能开始统一因为它们对个人习惯的依赖最小最容易达成共识。走到第四阶段的话技能框架就不只是“AI 编程助手”了而是团队研发流程的一个执行层。这时候要考虑的东西更多比如技能执行的审计日志、失败重试策略、和现有工单系统的集成。这些我还在摸索有进展再单独写一篇。8. 一些零散但重要的实操心得8.1 关于模型选择的经验不同技能对模型能力的要求差异很大。“需求澄清”和“方案设计”需要强推理建议用大模型“功能实现”和“代码格式化”确定性高中小模型就够“代码审查”介于两者之间看项目复杂度。切换模型用/model命令但要注意切换模型会丢失部分上下文。我的做法是在技能切换的间隙切模型不要在技能执行中途切。8.2 关于上下文管理的经验上下文管理是技能框架里最容易被低估的部分。我的经验是每个技能执行前只加载该技能需要的上下文。比如“功能实现”技能只需要当前任务描述和相关代码文件不需要整个项目的架构文档。加载过多上下文不仅浪费 token还会干扰模型判断。/compact的时机也有讲究。我一般在技能链完成一个完整循环比如“实现→审查→修复”走完一轮之后压缩一次而不是每个技能结束都压缩。压缩太频繁会丢失有用的中间信息。8.3 关于错误恢复的经验AI 执行技能出错是常态关键是快速恢复。我的标准流程是出错后先git diff看改了什么判断是局部问题还是全局问题。局部问题让 AI 修全局问题直接git checkout回滚重来。回滚重来的时候把出错的信息作为“负面示例”加到技能定义里避免下次再犯。这个习惯坚持下来技能定义的健壮性会越来越高。8.4 关于学习曲线的经验从零开始用技能框架前两周是最痛苦的因为要同时学工具用法、写技能定义、适应新的工作流。我的建议是先从单个技能开始比如只用“代码审查”技能用熟了再加第二个。不要一上来就搭完整技能链那样挫败感太强。另外前期不要追求技能定义的完美。先写个能用的版本在实际使用中迭代。我现在的技能定义文件跟第一版比起来几乎重写了三遍但每一版都是被实际问题逼出来的比一开始就“设计完美”要实用得多。8.5 关于工具边界的经验最后说一个认知层面的东西技能框架不能替代工程判断。它能保证 AI 按流程做事但流程本身对不对、某个决策该怎么做还是要人来定。我见过有人把技能框架当成“全自动开发机”结果产出代码一堆逻辑问题因为 AI 根本不知道业务背景。正确的定位是技能框架是放大器它放大的是你已有的工程能力。你工程能力强它让你更快你工程能力弱它让你更快地写出烂代码。所以用这套东西之前先把基本功打扎实不然工具越好翻车越快。