企业官网建设流程全解析

看到“superpowers”这个词被反复搜索，我心里大概就猜到大家在找什么了。GitHub上叫这个名字的项目少说也有七八个，有游戏引擎，有CSS动画库，还有一套基于Deno的写作工具。但2025年以来，开发者圈子里高频出现的superpowers，指的是一套给AI编码助手用的Agent技能集。它解决的是一个特别具体的痛点：大模型什么都能聊，但真正干活的时候经常跑偏，而superpowers就是把“一个资深工程师的工作习惯”固化成一份份技能文件，让AI照着执行。

它的定位不是插件，也不是框架，而是一套“技能包”。你不需要写复杂的system prompt，不需要反复调教模型，只要把技能文件放到指定目录，你的Claude Code、Cursor这类Agent工具就会自动感知，并在合适的时候调用它们。欠批评的人可能会觉得这不过是些Markdown文档，但实际用下来，效果差别极其明显。下面这篇东西，我会把安装方式、技能清单、完整使用流程和踩坑记录一次性讲完，尽量让新手也能照着配置出来。

1. 从混乱到有序：superpowers到底解决什么问题

1.1 什么是Agent技能

先明确一个基础概念：技能（Skill）是2025年各大AI编码工具主推的一种能力扩展方式。每个技能本质上是一个带固定结构的目录，里面有一个SKILL.md主文件，用YAML格式写明技能名称和描述，再用Markdown正文写清楚这个技能适合什么场景、需要遵循什么步骤、有哪些注意事项。当你的提示词与技能描述匹配时，Agent会自动把技能内容读进来，然后按照里面的流程去执行。和一个把“规则”写在上下文里的做法不一样，技能是即插即用的，不用整个项目都带着累赘的上下文。

superpowers就是按照这个规范做出来的一个开源技能合集。它全部由可读的文本文件组成，没有任何编译过程，也不用起服务。我最初打开这个项目的时候，第一反应是“就这？”——一堆文件夹而已。但真正用起来之后才发现，它的价值在于把一些非常高水平的编码工作流变成了可复用的行为模式。

1.2 为什么把工作流搬进技能文件

你可能要问，为什么不能直接跟AI说“你认真一点、多想想再动手”？我个人经验是，口头叮嘱的效果非常不稳定。你让大模型“先思考再编码”，它大概率会假装思考然后直接输出代码；你让它“写测试”，它可能写一个永远通过的假测试。原因很简单：自然语言指令太模糊，模型只能靠猜测来推断你想要的深度。

superpowers的解决思路是把工作流拆成明确的阶段，每个阶段都有具体的执行标准。以它的调试技能为例，它不是告诉你“排查一下bug”，而是会要求模型先复现问题、再缩小范围、然后提出一个或多个假设、逐个验证，最后给出可复现的验证步骤。这种结构化流程一旦被写进技能文件，模型执行起来就有章可循，而不是一上来就乱改代码。

另一个好处是可沉淀。一个团队踩过的坑、总结出来的最佳实践，完全可以写成自己的技能文件，放进项目里共享。新成员接入的时候，不用重新口头传授，Agent直接就按团队的标准来干活了。

2. 安装与引入：把技能挂到你的代理上

2.1 安装前要准备什么

你至少需要满足两个条件。第一，有一个支持Agent Skills格式的AI编码工具，目前生态最完整的是Claude Code，其他一些基于Claude模型的工具也逐渐支持了这套规范。第二，本地有Node.js环境，因为部分高级技能会依赖命令行工具来运行测试或处理文件。

如果你用的是Claude Code，安装路径是最顺的。它会在你的用户目录下创建.claude/skills这个文件夹，所有放在这里的技能都是全局技能，任何项目都能用。如果你的技能只服务某一个特定项目，那就把技能目录放进项目的.claude/skills下面，这样其他项目不会受到干扰。

2.2 安装方式和目录结构

安装superpowers有两种常见方式。第一种是全量安装：直接把整个仓库克隆下来，把skills目录里的内容复制到你的技能目录。第二种是按需安装：只挑你需要的几个技能文件夹复制过去，这种方式更灵活，也方便后期维护。

目录结构大致是下面这样的，技能名称本身就是一个文件夹，里面放着核心SKILL.md文件，部分复杂技能还会带references子目录，里面放案例或更详细的参考材料：

skills/ brainstorming/ SKILL.md behavioral-tdd/ SKILL.md references/ debugging/ SKILL.md references/

这里有一个很多人会忽略的细节：技能的description字段决定了自动触发的匹配度。你用的Agent就是靠读description来判断“当前对话是否该调用这个技能”。如果你发现某个技能怎么都触发不了，不要急着怪工具，先打开SKILL.md看看description写得是否足够具体，是否覆盖了你平时的提问习惯。必要时可以自己改几行描述，这是完全允许的，毕竟技能文件本来就是给人读、给人改的。

提示：不要一上来就把几十个技能全装进全局目录。技能太多反而会让Agent在选择时“选择困难”，出现该触发的没触发、不该触发的抢戏的情况。我一般建议首次装5个以内，用熟了再逐步扩展。

2.3 我建议的引入顺序

如果你只是想让日常编码更稳，我建议第一批先装这三个：behavioral-tdd、debugging、subagent。这三个基本上覆盖了从写代码、修Bug到拆任务的最核心场景。配下来大概只需要十分钟，之后你就能明显感觉到Agent的行为发生了变化，它不再像一个抢答器，更像一个带着流程的结对程序员。

第二批可以再加brainstorming、speccing和core-polish。这几类偏向前期需求梳理和后期代码打磨，适合你开始把它用在“整体模块开发”而不是“单点提问”的时候。

有些人安装完喜欢把仓库目录留在本机，定期拉更新。但我的建议是直接把所需技能复制到自己的技能目录，因为superpowers项目本身更新不算频繁，更重要的是，你很大概率会对技能内容做二次修改，复制出来的版本才是真正属于你的。

3. 有哪些核心skills：一张清单与使用时机

3.1 规划类技能：brainstorming、speccing、decompose-work

先说brainstorming。它适用于一个需求比较模糊，或者解决方案不唯一的场景。典型场景是你说“我想做一个批量重命名文件的工具”，模型如果直接开写，最后大概率给你一个只有基本功能的脚本。但启用brainstorming技能后，它会按照“提出关键问题-生成多个方案-评估取舍-确认方向”的顺序来做，先帮你把边界条件、用户场景和扩展方向盘清楚，再进入下一步。

speccing更偏产出规格说明。它适合已经确定了大致方向、需要把需求落到纸面上的阶段。技能会引导模型输出一份包含输入输出、行为规则、边界情况、验收标准的规格文档。这份文档会保存在你的项目目录里，后续写代码时Agent会反复参考它，减少中途跑偏的情况。

decompose-work做的是任务拆解，把一个大目标拆成可独立完成的小步骤，并明确依赖关系。它特别适合改造老项目，比如“把支付模块从v1迁移到v2”，涉及数据库改动、接口兼容、前端联动，如果不拆分，Agent很容易在一轮对话里超载，拆完之后再配合subagent并行推进，效率会高很多。

3.2 开发与调试类技能：behavioral-tdd、debugging、test-runner

behavioral-tdd是我用得最频繁的一个技能。它的核心逻辑是先写一个会失败的测试，再写实现代码，直到测试通过。看到这里你可能会想：我不做TDD，这个技能对我没用。其实不然，这个技能最大的价值不是“逼你写测试”，而是强迫Agent先想清楚“什么样算完成”。很多时候代码写完了，你问AI“你确定这功能完全对吗”，它会含糊其辞。但behavioral-tdd要求先定义验收测试，定义不了测试，就说明需求还没想透，这样就挡住了很多回不必要的编码工作。

debugging这个技能在修Bug场景下值得单独强调。它的执行流程高度标准化：先复现、再搜证、然后给假设、验证假设、修复、回归验证。我见过太多Agent在没有准确定位问题的情况下，直接根据一眼看上去可疑的代码去改，结果修好一个Bug又引入两个新Bug。如果让Agent遵循debugging技能的流程，它会主动去读日志、画堆栈、查最近变更，确保改动是基于证据而不是直觉。

test-runner则偏执行侧，它会主动查找项目的测试框架、运行相关测试、解析失败信息，并把结果反馈到调试循环里。说得直白点，它就是让Agent学会自己跑测试，而不是写完代码就说“应该没问题”。

3.3 质量与沉淀类技能：core-polish、concise-code、document-code

core-polish这个技能很有意思，它要求Agent在“从外向内审视”的框架下打磨代码，先把用户可见的部分做到位，再逐步深入内部实现。它处理的问题往往是“代码能跑，但体验很粗糙”：错误提示太笼统、边界条件没做保护、文件名不规范等。它跟直接说“优化一下代码”最大的区别在于，它有明确的调用时机和打磨顺序，不会一上来把所有代码重构成另一种风格。

concise-code着重治理代码膨胀，让Agent删掉重复分支、合并冗余逻辑、简化复杂表达式。这个技能适合用在“功能稳定、准备提交”之前，避免把自己和同事淹没在一堆绕来绕去的逻辑里。

document-code则是自动生成代码文档和注释。很多程序员排斥写文档，但成年人项目中，没有文档的代码就是负债。这个技能不会把所有函数都加注释，而是要求Agent只记录设计意图和让人困惑的特殊判断，很克制，也很有用。

实操心得：我自己最常用的是behavioral-tdd加debugging组合。写任何新功能，先用TDD技能把验收标准立起来，出问题时再切到debugging技能收口。这两个组合几乎覆盖了日常80%的需求。

4. “具体使用”是怎么一回事

4.1 靠自然语言触发技能

很多人对“怎么引入这些技能”有误解，以为需要输入某个命令、按某个快捷键。其实Agent Skills的触发方式非常自然，你只需要在对话里描述任务，Agent通过读取技能描述来匹配并自动加载。

但为了稳定触发，我养成了一个习惯：在需求描述里直接点出技能名。比如我不说“帮我实现一个导出功能”，而是说“请用behavioral-tdd流程帮我实现CSV导出功能”。这样等于给Agent一个明确的路标，它一看到技能名，就会主动去读对应的SKILL.md，然后按里面的流程工作。这个方法在测试中几乎百发百中，强烈推荐。

还有一种用法，稍微高级一点：如果你明确知道某个技能适合当前阶段，但Agent却没触发，你可以直接打开SKILL.md文件，把内容粘贴到对话里，然后说“按这个流程来”。这虽然粗暴，但非常有效，尤其适合面对复杂任务时，你想主导方向而不是让模型自由发挥。

4.2 一次完整实操

我拿一次真实的工作来演示。我有个需求：把大量零散Markdown文章批量转换成PDF，还要求支持封面、目录和页码。如果放在平时，我直接问AI怎么写，它多半会马上抛出一段Python脚本，用某种库来实现。等一运行，大概率会发现中文字体没处理、页码位置不对、目录生成方式不兼容。

但用了superpowers之后，整个流程就变成了这样。

第一步，我跟Agent说“用brainstorming技能帮我理一下这个批量转换工具的边界”。它没有直接写代码，而是问我：输入文件是单个文件夹还是多级目录？输出格式有没有特定版式？封面信息怎么提取？要不要并发处理大文件？这些平时容易被忽略的问题，几分钟内就被全部盘清。

第二步，我接着让它“用speccing生成任务规格”。它总结出了一份包含输入输出、转换规则、异常处理、验收标准的设计文档：文章按目录扫描，YAML前置信息提取封面，生成PDF临时目录，再用报告库统一合并加页码。

第三步，我让它按behavioral-tdd先写失败测试。这里它写出了两个关键测试：一篇含封面配置的文章能生成带书签栏的PDF，以及一个超过100页的文件在并发模式下不崩。然后才进入代码实现。

中途果然出了岔子：中文字体在PDF里变成方块。要是在以前，AI可能会自己去改字体配置或者换渲染库。但这次它触发debugging技能，追到“字体文件路径不存在”这个根因，发现原来把字体文件名搞错了一个字母，整个排查过程干净利落，没有动到无关代码。

4.3 核心套路：先感知，再决策

用多了superpowers之后，你会发现这些技能背后高度统一的思考方式。它让Agent在行动前先“感知”现状，而不是急着输出答案。这个模式有点像一个有经验的医生：先做检查，再下诊断，然后开药，最后安排复诊。

在代码场景中就体现为：接受任务先检查项目结构、读关键配置、跑现有测试，再去动手改代码；需要重构时会先确认调用点和行为边界，而不是直接按个人偏好重写；任务跨度较大时，会主动拆解、并用子代理并行执行相对独立的部分。

这也是superpowers第二层真正值钱的地方：它不是教你“怎么写某段代码”，而是给你一套“遇到任意代码任务时怎么做决策”的程序性记忆。它把这个过程拆成了触发条件、执行步骤和检查清单，Agent每次进入状态后都会按照这整套流程走，效果自然稳定得多。

5. 常见问题与排查经验

5.1 技能利用率不高，多半是不够“具体”

很多用户装完之后抱怨“感觉没什么变化”，我去看他们的使用方法，基本都是一个问题：提问太笼统。你输入“帮我看看这个项目有没有问题”，Agent就算读了技能描述，也不知道该触发哪个技能。最好的做法是把场景和期望说清楚，比如“先分析这个接口的性能瓶颈，再给出三个优化方案，我们讨论完再改代码”。技能是工具，不是魔法，输入清楚，输出才清楚。

5.2 技能目录和项目目录怎么配合

全局技能放在~/.claude/skills，项目级技能放在.claude/skills。如果同一个技能在两个目录里都存在，项目级的优先。这个设计的好处是，你完全可以把通用技能放全局，然后针对不同仓库添加自己的专属技能。比如你常做Rust项目，就可以把一个“Rust错误处理规范”的自定义技能放在项目里，只有进这个仓库的时候才会生效。

5.3 那些references文件夹该不该提交到代码库

该提交。很多人习惯把所有AI相关配置加进.gitignore，但我觉得项目内的技能文件应该共享给团队成员。因为这些技能不只是给Agent看的，也是人可读的团队规范。你写了一个“数据库迁移前必须备份”的技能，放进项目里，下次任何人开着Agent做迁移，模型就会主动检查备份步骤。这对团队来说是一份活的开发文档，比Wiki好用得多。

5.4 技能覆盖率低，如何排查

如果某个技能从不触发，按这三个顺序排查：先确认技能目录在正确位置，且SKILL.md格式没写错；再检查description是否覆盖你的实际提问方式；最后看当前工具版本是否完整支持Agent Skills。还有一个常见细节：技能文件里的描述应该用中文还是英文？如果你的Agent主语言是中文，描述可以用中文，匹配率往往更高；如果你依赖官方预设的英文描述，那就尽量用英文提问来稳定触发。

注意：遇到一次对话里同时触发了多个技能的情况，不要全部放行。让Agent按你给的优先级执行，或者你在对话里明确说“现在只执行调试部分，不要进入重构环节”。技能是用来帮你落地的，不是让你失去控制的。

6. 几个我一直在用的习惯

最后分享几个我个人在很多项目里沉淀下来的使用习惯，不算什么大道理，但确实帮我省了大量重复劳动。

第一，新项目启动时我只会装三个技能：brainstorming、speccing、behavioral-tdd。先用头脑风暴把需求聊透，再用规格文档把边界锁死，最后用TDD流程确保每一步都验收过。这三个技能跑顺了，项目初期的返工率会低很多。

第二，我会在项目根目录专门放一个“经验记录”技能目录，里面放一些自己写的小技能文件。每当踩了坑，比如发现某个第三方库在某些系统上有兼容性问题，我就把过程整理成一个简单的技能文档，下次再碰到类似问题，Agent会自动按这份经验来处理。时间一长，这些文件就成了团队的私有知识库。

第三，无论如何，不要只依赖自动触发。熟练之后你会发现，自己手动指定技能比让它自己猜要可靠得多。我现在拒绝跟Agent说空泛的“帮我优化”，都是直接说“用core-polish先处理用户可见的问题，再考虑内部简化”。这种指令既清晰，又能让每项工作真正作用于它该作用的层面。