1. 从“superpowers”说起这套 agentic skills framework 到底在解决什么问题第一次看到 “superpowers” 这个词是在几个做 AI 编程工具链的朋友群里。有人甩了个链接配文是“终于有人把 agentic skills framework 这件事讲明白了”。点进去之前我以为又是个蹭热度的概念包装看完之后发现不太一样——它试图回答一个很具体的问题当 Claude Code、Codex CLI 这类终端里的 AI 编程代理越来越能干的时候我们怎么让它们稳定地、可复用地完成复杂任务而不是每次都要重新“教”一遍这就是 superpowers 的核心定位。它不是某个具体的软件也不是一个可以直接npm install的包而是一套面向 AI 编程代理的技能框架和方法论。你可以把它理解成给 AI 代理准备的“操作手册 工具箱 工作流模板”三合一。它要解决的是当前 AI 辅助开发里最让人头疼的几个痛点任务一复杂代理就开始胡来、同样的操作每次都要重复描述、多个代理之间没法协同、做完的事情没法沉淀成可复用的能力。适合读这篇内容的人我大致分三类。第一类是已经在用 Claude Code 或者 Codex CLI 做日常开发但总觉得“差点意思”的开发者——你可能已经体验过让 AI 帮你重构一个模块结果它改着改着就跑偏了。第二类是团队里负责搭建 AI 开发流程的技术负责人你需要一套能落地的规范而不是一堆零散的 prompt 技巧。第三类是对 agentic skills framework 这个概念好奇想搞清楚它和普通的 prompt engineering 到底有什么区别的人。我自己的背景是后端开发转工具链过去一年多时间深度使用 Claude Code 和 Codex CLI 做项目踩过的坑包括但不限于代理把测试文件删了、代理在错误的目录里执行命令、代理生成的代码风格和项目完全不一致。superpowers 这套框架里的很多设计恰好就是我踩坑之后自己摸索出来的土办法的系统化版本。所以这篇内容我会结合自己的实操经验把 superpowers 的核心思路、关键实现、落地步骤和避坑要点全部拆开讲。2. 核心思路拆解为什么是“技能框架”而不是“提示词集合”2.1 从 prompt 到 skill一次认知升级大部分人接触 AI 编程代理的路径是这样的先学会写 prompt发现效果不稳定然后开始研究 system prompt 怎么写、few-shot 怎么给、context 怎么管理。这条路走到后面会遇到一个天花板——你所有的经验都散落在不同的对话里没法沉淀没法复用没法组合。superpowers 的思路是把“技能”作为一等公民。一个 skill 不是一段 prompt而是一个有明确输入输出、有前置条件、有执行步骤、有验证标准的完整能力单元。举个例子普通的做法是你告诉 Claude Code “帮我给这个函数写单元测试”然后它可能写出来一堆跑不通的测试。而 skill 化的做法是定义一个叫write-unit-test的技能它包含先读取目标函数的签名和依赖、检查项目现有的测试框架和风格、生成测试骨架、填充测试用例、运行测试、根据失败结果迭代修正、最后输出覆盖率报告。这一整套流程被固化下来每次调用都是同样的质量。这个区别很关键。prompt 是“一次性”的skill 是“可积累”的。你团队里每解决一个复杂场景就多一个 skill下次遇到类似问题直接调用不需要重新描述。这就是 agentic skills framework 和普通 prompt engineering 的本质差异。2.2 为什么选 Claude Code 和 Codex CLI 作为主要载体superpowers 这套框架在设计上明显是围绕终端里的 AI 编程代理来做的而 Claude Code 和 Codex CLI 是目前这个领域最成熟的两个载体。原因有几个。Claude Code 的优势在于它的工具调用能力和上下文管理。它可以直接读写文件、执行终端命令、搜索代码库而且对长上下文的理解比较稳。你在 Claude Code 里定义一个 skill它可以真正地去“做事情”而不是只给你一段建议。Codex CLI 的优势在于它的轻量和可组合性适合做流水线式的任务比如批量重构、代码审查、生成文档这类不需要太多交互的场景。我自己的用法是复杂任务用 Claude Code因为它的推理链更长能处理多步骤的依赖关系重复性任务用 Codex CLI因为它的启动成本低适合塞进脚本里跑。superpowers 框架在设计上兼容这两者你可以根据任务类型选择不同的执行载体。2.3 框架的三个核心抽象拆开来看superpowers 这套框架有三个核心抽象理解了这三个东西整个框架就通了。第一个是 Skill技能。这是最小的能力单元定义了一个具体的、可复用的操作。一个 skill 通常包含名称和描述、触发条件、输入参数、执行步骤、验证标准、输出格式。你可以把它类比成函数——有签名、有实现、有返回值。第二个是 Workflow工作流。这是多个 skill 的组合用来完成一个更大的任务。比如“实现一个新功能”这个工作流可能包含分析需求、设计接口、写实现代码、写测试、跑测试、生成文档、提交代码。每个步骤都是一个 skill工作流定义了它们的执行顺序和依赖关系。第三个是 Context上下文。这是 skill 执行时的环境信息包括项目结构、代码风格、依赖版本、历史决策等。superpowers 强调上下文要显式管理而不是让代理自己去猜。这一点非常重要后面会详细讲。这三个抽象的关系是Context 为 Skill 提供执行环境Workflow 把 Skill 编排成完整的任务流程。整个框架的目标就是让这三者都能被版本控制、被复用、被组合。3. 核心细节解析Skill 的定义、触发与执行机制3.1 一个 Skill 的完整结构长什么样先说结论一个设计良好的 skill应该让一个不了解项目背景的人或者代理只看定义就能正确执行。我见过太多所谓的“技能”其实就是一句模糊的指令比如“优化代码性能”这种定义等于没定义。一个完整的 skill 定义通常包含以下字段。我用一个实际的例子来说明——假设我们要定义一个叫refactor-extract-function的技能用于把一段代码里的逻辑抽取成独立函数。name: refactor-extract-function description: 将选定的代码块抽取为独立函数保持行为不变 trigger: - 用户明确要求抽取函数 - 代码审查中发现重复逻辑 inputs: - target_file: 目标文件路径 - target_range: 要抽取的代码行范围 - function_name: 新函数的名称 preconditions: - 目标文件存在且可读 - 项目有测试覆盖目标代码 steps: - 读取目标文件和周边上下文 - 分析代码块的输入依赖和输出 - 生成新函数签名 - 替换原代码块为函数调用 - 运行相关测试 - 如果测试失败回滚并报告 validation: - 所有原有测试通过 - 新函数有明确的输入输出类型 output: - 修改后的文件 - 变更摘要这个结构里preconditions 和 validation 是最容易被忽略但最重要的部分。preconditions 确保 skill 在正确的环境下执行validation 确保执行结果符合预期。没有这两个skill 就是不可靠的。3.2 触发机制什么时候该调用哪个 SkillSkill 的触发有两种模式显式触发和隐式触发。显式触发就是用户直接说“用 xxx 技能做 yyy”比如“用 refactor-extract-function 把这段逻辑抽出来”。这种方式简单直接适合用户明确知道要用什么技能的场景。隐式触发是代理根据当前上下文自动判断该用哪个 skill。这需要框架维护一个 skill 索引代理在执行任务前先检索可用的 skill匹配当前需求。隐式触发的好处是用户不需要记住所有 skill 的名字坏处是可能匹配错误。我的经验是关键任务用显式触发探索性任务用隐式触发。比如生产环境的代码修改一定要显式指定 skill避免代理自作主张。而在做原型或者探索新方案的时候可以让代理自己选说不定能发现你没想到的组合方式。这里有个实操技巧给每个 skill 加一个confidence_threshold字段当代理对某个 skill 的匹配度低于阈值时不自动执行而是询问用户确认。这个阈值我一般设在 0.8 左右太低会频繁误触发太高会漏掉合适的技能。3.3 执行机制Skill 是怎么被“跑”起来的Skill 的执行不是简单的“把定义丢给代理然后等结果”。一个可靠的执行机制需要处理几个问题上下文注入、步骤编排、错误处理、结果验证。上下文注入是指执行 skill 之前要把相关的项目信息、代码片段、历史决策等喂给代理。superpowers 的做法是维护一个 context 文件里面记录了项目的关键信息每次执行 skill 时自动注入。这个 context 文件需要定期更新否则代理会基于过时的信息做决策。步骤编排是指 skill 内部的多个步骤怎么串起来。简单的 skill 可以线性执行复杂的 skill 需要条件分支和循环。比如“修复测试失败”这个 skill可能需要“运行测试 → 分析失败原因 → 修改代码 → 重新运行测试”这样的循环直到测试通过或者达到最大重试次数。错误处理是很多人会忽略的。代理执行 skill 时可能遇到各种意外文件不存在、命令执行失败、生成的代码有语法错误。一个健壮的 skill 应该定义好每种错误的处理方式——是重试、是回滚、还是报告给用户。结果验证是最后一道防线。skill 执行完之后要检查输出是否符合 validation 标准。不符合的话要么自动修正要么标记为失败。我见过太多“看起来执行成功了但实际上改错了”的情况验证这一步绝对不能省。4. 实操过程从零搭建一套可用的 Skill 体系4.1 环境准备与工具链配置在开始搭建之前需要先把基础环境准备好。这里我假设你用的是 macOS 或者 UbuntuWindows 用户建议用 WSL2因为 Claude Code 和 Codex CLI 在原生 Windows 上的兼容性还有一些问题。首先是 Claude Code 的安装。官方提供了多种安装方式我推荐用 npm 全局安装因为更新方便npm install -g anthropic-ai/claude-code安装完成后在项目目录下运行claude命令首次使用需要完成账号配置。如果你所在的环境无法直接使用官方服务可以考虑通过第三方 API 接入的方式把 Claude Code 指向兼容的模型服务。具体做法是配置环境变量把 API endpoint 和 key 指向你使用的服务商。这里不展开讲具体配置因为不同服务商的参数不一样核心思路就是让 Claude Code 认为它在和一个兼容的 API 通信。Codex CLI 的安装类似npm install -g openai/codexCodex CLI 的配置相对简单主要是设置好 API key 和默认模型。它支持通过配置文件来管理多个模型配置方便在不同场景下切换。VS Code 的集成是可选但强烈推荐的。Claude Code 有官方的 VS Code 插件安装之后可以在编辑器里直接调用代理不用来回切终端。配置的关键是确保插件能找到 Claude Code 的可执行文件路径以及项目的工作目录设置正确。注意安装过程中如果遇到网络问题导致下载失败可以尝试配置 npm 的镜像源。另外某些企业网络环境可能会限制对特定域名的访问这种情况需要联系网络管理员。4.2 定义你的第一个 Skill环境准备好之后我们从一个最简单的 skill 开始。我建议第一个 skill 选“代码审查”类的因为这类任务边界清晰、验证标准明确适合练手。在项目根目录下创建一个.superpowers/skills/目录然后新建一个文件code-review.md。内容大致如下--- name: code-review description: 对指定的代码变更进行审查输出问题列表和改进建议 trigger: - 用户请求审查代码 - 提交前自动触发 inputs: - diff_range: 代码变更范围默认为最近一次提交 - focus_areas: 重点关注领域如安全性、性能、可读性 steps: - 获取指定范围的代码变更 - 逐文件分析变更内容 - 检查是否符合项目编码规范 - 识别潜在的安全问题 - 识别性能隐患 - 评估代码可读性和可维护性 - 生成审查报告 validation: - 报告包含具体的文件路径和行号 - 每个问题都有明确的严重程度分级 - 改进建议可操作 output: - 结构化的审查报告 --- ## 审查标准 ### 严重问题必须修复 - 安全漏洞SQL 注入、XSS、敏感信息硬编码 - 逻辑错误边界条件未处理、空指针风险 - 资源泄漏未关闭的文件句柄、数据库连接 ### 一般问题建议修复 - 命名不规范变量名无意义、函数名与实际行为不符 - 重复代码超过 10 行的重复逻辑 - 缺少注释复杂逻辑没有说明 ### 轻微问题可选修复 - 格式问题缩进不一致、多余空行 - 拼写错误注释和字符串中的拼写问题这个 skill 定义好之后在 Claude Code 里就可以通过“执行 code-review 技能”来调用了。第一次执行的时候代理可能会问一些澄清问题比如“审查范围是哪些文件”这是正常的说明它在正确理解 skill 的输入要求。4.3 把 Skill 串成 Workflow单个 skill 能解决具体问题但真正的效率提升来自于把多个 skill 串成工作流。我们来看一个实际的例子“实现一个新 API 接口”这个工作流。这个工作流包含以下步骤每个步骤对应一个 skillanalyze-requirement分析需求输出接口设计文档design-api根据设计文档生成 API 签名和数据结构implement-handler实现接口处理逻辑write-test生成单元测试和集成测试run-test执行测试并修复失败generate-doc生成 API 文档review-code代码审查工作流的定义文件放在.superpowers/workflows/目录下格式如下name: implement-api description: 从需求到上线的完整 API 实现流程 skills: - analyze-requirement - design-api - implement-handler - write-test - run-test - generate-doc - review-code transitions: - from: analyze-requirement to: design-api condition: 设计文档已确认 - from: design-api to: implement-handler condition: API 签名已确认 - from: implement-handler to: write-test condition: 实现代码无语法错误 - from: write-test to: run-test condition: 测试文件已生成 - from: run-test to: generate-doc condition: 所有测试通过 - from: generate-doc to: review-code condition: 文档已生成 error_handling: - skill: run-test on_failure: 回到 implement-handler 修复 max_retries: 3这个工作流定义里transitions定义了步骤之间的流转条件error_handling定义了失败时的处理策略。有了这个代理就知道在每一步该做什么、做完之后该往哪走、出错了该怎么办。4.4 上下文管理让代理“记住”项目的关键信息上下文管理是 superpowers 框架里最容易被低估的部分。很多人觉得只要 skill 定义得好就够了但实际上代理执行 skill 的质量很大程度上取决于它掌握的上下文信息。我建议在项目根目录下维护一个.superpowers/context.md文件内容包含项目的技术栈和版本信息代码风格规范命名约定、目录结构、注释风格关键架构决策及其原因常用的命令和脚本已知的坑和注意事项这个文件不需要很长但要精准。比如“我们用的是 PostgreSQL 14ORM 是 Prisma所有数据库操作必须通过 Prisma 进行不允许直接写 SQL”这样的信息能避免代理生成不符合项目规范的代码。上下文文件需要定期更新。我的做法是每次做完一个较大的功能或者修复一个典型的 bug 之后花两分钟看看有没有需要补充到 context 里的信息。这个习惯坚持下来代理的“懂事程度”会明显提升。5. 常见问题与排查技巧实录5.1 Skill 执行失败的典型原因在实际使用中skill 执行失败的原因五花八门但大部分可以归为以下几类。我整理了一个速查表方便对照排查。问题现象可能原因排查方法解决方案代理不执行 skillskill 未注册或路径错误检查.superpowers/skills/目录确认文件存在且格式正确执行到一半卡住步骤依赖不满足查看代理的输出日志补充前置条件或调整步骤顺序结果不符合预期上下文信息不足检查 context 文件补充项目相关信息反复重试失败错误处理逻辑有误检查 error_handling 配置调整重试策略或增加回滚生成的代码风格不对缺少风格规范检查 context 中的规范定义补充代码风格示例这个表里的每一行都是我实际踩过的坑。比如“代理不执行 skill”这个问题我遇到过好几次最后发现是文件扩展名的问题——superpowers 只识别.md和.yaml格式的 skill 定义我用了.txt所以没被加载。5.2 代理“自作主张”怎么办这是使用 AI 编程代理时最让人头疼的问题之一。你让它做 A它顺便把 B 也改了结果 B 的改动引入了新问题。superpowers 框架通过几个机制来约束代理的行为。首先是preconditions明确告诉代理在什么条件下才能执行。其次是scope 限制在 skill 定义里指定允许修改的文件范围。最后是validation执行完之后检查是否只改了该改的地方。但说实话这些机制只能降低概率不能完全杜绝。我的经验是对于关键代码路径永远不要让代理全自动执行至少要有人工确认环节。可以在 workflow 里加一个manual-approval步骤代理执行到这一步时暂停等人工确认后再继续。5.3 性能优化让 Skill 执行更快更稳当 skill 数量多起来之后执行效率会成为一个问题。每个 skill 执行都要加载上下文、调用模型、处理结果累积起来时间不短。我总结了几个优化技巧。第一给 skill 分级。高频使用的 skill 做精简只保留核心步骤低频但复杂的 skill 可以保留完整流程。比如code-review这种每次提交都要跑的定义要尽量简洁。第二缓存上下文。如果多个 skill 共享同一份上下文不要每次都重新加载。superpowers 支持上下文缓存配置好之后能省不少时间。第三并行执行无依赖的 skill。比如generate-doc和write-test如果互不依赖可以并行跑。这需要在 workflow 定义里显式声明并行关系。第四定期清理失效的 skill。项目在演进有些 skill 可能已经不再适用了。我一般每个月 review 一次 skill 列表把过时的删掉或者更新。5.4 团队协作中的 Skill 管理如果是团队使用skill 的管理需要额外的规范。我们团队的做法是所有 skill 定义必须经过 code review 才能合并到主分支每个 skill 要有明确的 owner负责维护和更新skill 的变更要记录 changelog方便追溯定期组织 skill 分享会让大家了解彼此定义的技能这些规范看起来有点重但实际执行下来能避免很多“这个 skill 是谁写的、为什么这么写”的困惑。特别是当团队有新成员加入时一套清晰的 skill 体系能大大缩短上手时间。6. 进阶玩法把 Skill 体系接入现有开发流程6.1 与 CI/CD 的集成Skill 体系真正发挥威力是在接入 CI/CD 之后。我们团队的做法是在 pre-commit hook 里跑code-reviewskill在 CI 流水线里跑run-test和security-scanskill。这样每次提交代码代理会自动做一轮检查把问题拦在合并之前。配置方式是在.husky/pre-commit里加一行调用 Claude Code 的命令#!/bin/sh claude --skill code-review --diff HEAD~1CI 里的配置类似在流水线的测试阶段调用相应的 skill。需要注意的是CI 环境里代理的执行时间要控制好太慢会影响开发效率。我的经验是单个 skill 的执行时间控制在 30 秒以内比较合适。6.2 自定义 Skill 的进阶技巧当你熟悉了基础用法之后可以尝试一些进阶技巧。组合 skill把多个小 skill 组合成一个复合 skill。比如full-stack-feature可以组合前端、后端、数据库三个方向的 skill一次性完成一个完整功能的开发。参数化 skill让 skill 接受更灵活的参数。比如refactorskill 可以接受一个strategy参数值可以是extract-function、inline、rename等根据参数执行不同的重构策略。条件 skill根据项目状态动态决定执行哪些步骤。比如deployskill 可以根据当前分支是main还是feature走不同的部署流程。这些进阶技巧的核心思路是一样的把重复的决策逻辑固化到 skill 定义里让代理少做“选择题”多做“执行题”。代理做选择题的时候容易出错做执行题的时候相对可靠。6.3 效果评估与持续改进搭好 skill 体系之后怎么知道它有没有效果我建议跟踪几个指标任务完成率skill 执行成功的比例平均执行时间从触发到完成的时间人工干预率需要人工介入的比例问题发现率skill 发现的问题中真正有价值的问题占比这些指标不需要很精确有个大概的趋势就行。如果发现某个 skill 的人工干预率特别高说明它的定义有问题需要优化。如果问题发现率很低说明这个 skill 可能太宽松了需要加严验证标准。我自己的体会是skill 体系不是搭好就完事的它需要持续迭代。项目在变团队在变skill 也要跟着变。把 skill 当成代码一样维护定期 review、定期更新才能保持它的价值。最后分享一个我踩过的坑刚开始用 superpowers 的时候我恨不得把所有操作都定义成 skill结果搞了几十个管理成本比收益还高。后来砍到十几个核心 skill反而效率更高。skill 不在多在于精。每个 skill 都应该解决一个真实的、高频的、有明确验证标准的问题否则就是负担。