企业官网建设流程全解析

1. 从“superpowers”这个标题说起：它到底是什么，能解决什么问题

第一次看到“superpowers”这个标题，很多人会下意识联想到超级英雄电影里的超能力，但在技术圈子里，这个词最近被反复提起，指向的其实是一套围绕 AI 编程助手构建的技能扩展体系。简单来说，它让原本只会“聊天写代码”的 AI 助手，变成能按固定流程、固定规范、固定输出格式干活的“熟练工”。你可以把它理解成给 AI 装上了一套“操作手册加工具箱”，让它不再每次从零开始猜你想要什么，而是直接调用预先定义好的技能模块来完成任务。

这套东西解决的核心痛点非常具体：AI 编程助手在真实项目里“不稳定”。同一个需求，今天问它写出来的代码风格和昨天不一样；让它做代码审查，它可能漏掉关键的安全检查项；让它生成接口文档，格式每次都要手动调整。这些问题的根源在于，AI 每次对话都是“即兴发挥”，没有一套固定的行为约束。superpowers 的思路就是把这些“即兴发挥”变成“按剧本演出”——把常见的开发任务拆解成一个个独立的技能包，每个技能包定义了明确的触发条件、执行步骤和输出规范。

适合谁来参考这套东西？三类人最值得花时间研究。第一类是日常重度使用 AI 编程助手的开发者，如果你每天都要和 AI 来回对话几十轮来写代码、改 bug、写测试，superpowers 能帮你把重复性的对话模板固化下来，省掉大量“调教”时间。第二类是技术团队的负责人或架构师，你需要让团队里不同的人用 AI 助手时产出一致的结果，superpowers 提供了一种把团队规范“编码”进 AI 工作流的可能。第三类是对 AI 工程化感兴趣的技术爱好者，想了解怎么把大模型的通用能力约束到具体场景里，这套体系是一个很好的观察样本。

需要提前说明的是，superpowers 本身不是一个独立的软件或服务，它更像是一套约定和配置的集合，依附于你正在使用的 AI 编程助手环境。所以它的安装和使用方式，和你选择的底层工具强相关。下面我会从整体设计思路开始拆解，然后逐步深入到具体的安装配置、技能编写、实操流程和踩坑经验，尽量把每个环节都讲透。

2. 整体设计思路拆解：为什么是“技能包”而不是“万能提示词”

2.1 核心思路：把“提示词工程”升级为“技能工程”

大多数人用 AI 编程助手的方式是：遇到问题，临时想一段提示词，粘贴进去，看结果不满意再改提示词。这种方式在简单任务上够用，但一旦任务复杂起来，比如“帮我审查这个模块的代码并生成报告”，提示词就会变得又长又乱，而且每次都要重新组织。superpowers 的设计者显然意识到了这个问题，他们的解法是：把提示词从“一次性消耗品”变成“可复用的技能资产”。

具体做法是，每个技能被定义为一个独立的文件或配置块，里面包含几个关键部分：技能的名称和描述（告诉 AI 什么时候该用这个技能）、执行步骤（告诉 AI 按什么顺序做什么事）、输出格式要求（告诉 AI 最终结果长什么样）、以及可能的参数占位符（让技能可以接受外部输入）。当你在对话中触发某个技能时，AI 助手会读取这个技能的定义，然后严格按照里面的步骤来执行，而不是自由发挥。

这个思路的巧妙之处在于，它把“怎么写好提示词”这个难题，从每次对话中剥离出来，变成了一个可以提前设计、反复打磨、团队共享的工程问题。你不需要每次都想“怎么问才能让 AI 写出规范的代码”，只需要在技能文件里把规范写死，之后每次调用都自动生效。

2.2 方案选型背后的考量：为什么不做成插件或独立工具

你可能会问，为什么不直接做一个 IDE 插件或者独立的命令行工具来实现这些功能？非要依附于 AI 助手的对话环境？这背后有几个现实考量。

第一，降低使用门槛。如果做成独立工具，用户需要额外安装、配置、学习一套新的界面和命令，而依附于现有的 AI 助手环境，用户只需要在熟悉的对话框里输入触发词就能用，学习成本几乎为零。第二，利用 AI 的理解能力。技能定义里不需要把每一步都写成死板的脚本，可以用自然语言描述步骤，AI 会根据上下文灵活执行，这比写死脚本要健壮得多。第三，避免重复造轮子。AI 助手本身已经具备了代码生成、文件读写、命令执行等基础能力，superpowers 只需要在这些能力之上加一层“行为约束”，不需要重新实现底层功能。

当然，这种方案也有代价。它高度依赖底层 AI 助手的能力和稳定性，如果助手本身对技能定义的理解出现偏差，执行结果就会打折扣。另外，不同助手对技能格式的支持程度不一样，迁移起来可能需要调整。但总体来看，对于“让 AI 按规范干活”这个目标，技能包方案是当前性价比最高的选择。

2.3 优势与边界：它能做什么，不能做什么

superpowers 最明显的优势是一致性和可积累性。一致性体现在，同一个技能无论调用多少次，输出格式和检查项都是固定的，不会因为对话上下文的变化而漂移。可积累性体现在，你可以不断往技能库里添加新的技能，今天加一个“生成单元测试”的技能，明天加一个“检查 SQL 注入风险”的技能，技能库越丰富，AI 助手能覆盖的场景就越多。

但它也有明确的边界。首先，它不能替代人的判断。技能定义得再详细，AI 执行时仍然可能遇到边界情况需要人来决策，比如代码审查时发现一个模棱两可的设计问题，最终拍板还得靠人。其次，它不适合高度创造性的任务。如果你让 AI 从零设计一个全新架构，技能包反而会限制它的发挥空间，这种场景下自由对话可能效果更好。最后，它需要持续维护。项目在演进，规范在变化，技能定义也要跟着更新，否则过时的技能反而会误导 AI。

3. 核心细节解析：一个技能包里到底装了什么

3.1 技能定义的基本结构

虽然不同 AI 助手对技能格式的支持细节有差异，但一个典型的技能定义通常包含以下几个字段。我用一个“代码审查”技能作为例子来说明。

name: code-review description: 对指定代码文件进行系统性审查，检查安全、性能、可读性和规范符合度 trigger: 当用户要求审查代码、检查代码质量、或提到 review 时触发 steps: - 读取目标文件内容 - 检查是否存在硬编码密钥、SQL注入风险、XSS风险 - 检查循环和递归是否有性能隐患 - 检查变量命名和函数长度是否符合规范 - 按严重程度分级列出问题 output_format: | ## 审查结果 ### 严重问题 - [文件:行号] 问题描述 ### 一般问题 - [文件:行号] 问题描述 ### 建议改进 - [文件:行号] 建议内容

这个结构里，name是技能的唯一标识，description帮助 AI 判断什么时候该用这个技能，trigger是更明确的触发条件，steps是执行步骤清单，output_format规定了最终输出的格式。有些实现还会支持parameters字段，让技能可以接受文件路径、检查级别等参数。

3.2 触发机制的设计细节

触发机制是技能包能否被正确调用的关键。如果触发条件写得太宽泛，AI 可能会在不该用的时候乱用技能；写得太窄，又可能该用的时候不触发。我的经验是，用“用户意图”而不是“关键词”来定义触发条件。比如上面例子里的“当用户要求审查代码、检查代码质量、或提到 review 时触发”，覆盖了多种表达方式，比单纯写“触发词：review”要健壮得多。

另外，多个技能之间的触发条件要避免重叠。如果你同时定义了“代码审查”和“安全检查”两个技能，而安全检查的触发条件里也包含了“检查代码”，那 AI 就不知道该用哪个。解决办法是在描述里明确区分场景，比如安全检查技能描述为“当用户明确要求检查安全漏洞、或代码涉及用户输入处理时触发”，把边界划清楚。

3.3 输出格式的约束技巧

输出格式的约束直接决定了技能好不好用。如果格式定义得太死，AI 可能会为了凑格式而忽略内容质量；定义得太松，输出又会变得随意。我试过几种方式，最后觉得**“结构化模板加灵活填充”**最实用。具体来说，就是给出明确的章节标题和列表格式，但每个章节内部的内容让 AI 根据实际情况填充。

还有一个技巧是，在输出格式里加入严重程度分级或优先级标记。比如代码审查技能里用“严重问题/一般问题/建议改进”三级分类，AI 在审查时就会主动判断每个问题的严重程度，而不是把所有问题混在一起列出来。这个小小的格式约束，对最终输出的可用性提升非常明显。

注意：输出格式里不要用太复杂的嵌套结构，比如表格里套列表再套代码块，AI 在生成时容易出错。保持两层以内的结构最稳定。

3.4 参数化与动态内容处理

有些技能需要接受外部输入才能工作，比如“生成单元测试”技能需要知道目标文件路径和测试框架类型。这时候就需要用到参数化。参数的定义方式通常是在技能描述里用占位符标记，比如{{file_path}}和{{framework}}，然后在调用时由用户或 AI 自动填充。

参数化带来的一个问题是，如果参数没有正确传入，技能执行就会失败或产生错误结果。我的做法是在技能定义里加入参数校验步骤，比如第一步就是“检查 file_path 是否为空，如果为空则提示用户提供”。这样即使参数缺失，AI 也能给出明确的提示，而不是默默生成一堆无意义的内容。

4. 实操过程：从零搭建一套可用的技能库

4.1 环境准备与安装位置选择

superpowers 的安装方式取决于你使用的 AI 编程助手环境。常见的几种情况：如果助手支持自定义指令文件（比如某些编辑器里的规则文件），你可以把技能定义写进对应的配置目录；如果助手支持插件或扩展机制，可能需要按照插件规范来组织技能文件；如果助手只支持对话，那可能需要把技能定义作为对话的初始上下文传入。

我实测下来，把技能文件放在项目根目录下的一个专用文件夹里（比如.ai-skills/或.assistant/skills/）是最稳妥的做法。这样做的好处是：技能定义和项目代码一起版本控制，团队成员拉取代码后自动获得相同的技能库；不同项目可以有不同技能库，互不干扰；迁移项目时技能库跟着走，不需要额外配置。

安装步骤大致如下：

1. 在项目根目录创建技能文件夹，比如mkdir .ai-skills
2. 在文件夹里创建技能定义文件，每个技能一个文件，文件名用技能名，比如code-review.yaml
3. 按照你使用的 AI 助手的规范，在助手的配置里指定技能文件夹的路径
4. 重启助手或重新加载配置，让技能生效
5. 在对话中测试触发技能，检查是否按预期执行

提示：第一次配置时，建议先只放一个最简单的技能（比如“生成提交信息”），确认整个链路通了之后，再批量添加其他技能。这样出问题时排查范围小。

4.2 编写第一个技能：从“生成提交信息”开始

“生成提交信息”是一个很好的入门技能，因为它逻辑简单、触发场景明确、输出格式容易定义。下面是我实际使用的一个版本。

name: commit-message description: 根据代码变更内容生成符合约定式提交规范的提交信息 trigger: 当用户要求生成提交信息、写 commit message、或提到提交时触发 steps: - 读取暂存区的变更文件列表和差异内容 - 判断变更类型：新增功能(feat)、修复缺陷(fix)、重构(refactor)、文档(docs)、测试(test)、杂项(chore) - 提取变更的核心内容，用一句话概括 - 如果变更涉及多个类型，按主要类型归类 output_format: | <type>(<scope>): <subject> <body> <footer> parameters: - name: scope description: 影响范围，可选，默认为空 required: false

这个技能定义里，steps描述了 AI 需要执行的判断逻辑，output_format给出了约定式提交的标准格式。实际使用时，你只需要说“帮我生成提交信息”，AI 就会读取变更内容，判断类型，然后按格式输出。

我踩过的一个坑是：AI 有时会把变更类型判断错，比如把重构当成新功能。后来我在步骤里加了一条“如果不确定类型，优先选择 fix 或 refactor，避免误标为 feat”，准确率明显提升。这个经验说明，技能定义里的步骤不仅要描述“做什么”，还要在容易出错的环节给出“兜底规则”。

4.3 技能库的组织与分类策略

当技能数量超过十个之后，就需要考虑分类组织了。我的做法是按开发阶段分类，把技能分成几组：编码阶段（生成代码、补全函数、重构）、审查阶段（代码审查、安全检查、性能检查）、测试阶段（生成测试、检查覆盖率）、文档阶段（生成注释、生成接口文档、生成变更日志）、协作阶段（生成提交信息、生成合并请求描述）。

分类的好处是，在配置触发条件时可以按组设置优先级。比如审查阶段的技能优先级高于编码阶段，因为审查通常是在编码完成后进行的。另外，分类也方便团队分工维护，不同的人负责不同组的技能更新。

在文件组织上，可以用子文件夹来体现分类：

.ai-skills/ coding/ generate-function.yaml refactor-code.yaml review/ code-review.yaml security-check.yaml testing/ generate-test.yaml docs/ generate-comment.yaml

4.4 技能之间的协作与串联

单个技能的能力有限，但多个技能串联起来就能完成复杂任务。比如“代码审查”技能发现了一个安全问题，可以自动触发“生成修复建议”技能；修复完成后，再触发“生成测试”技能来验证修复效果。这种串联可以通过在技能定义里加入“后续技能”字段来实现。

name: security-check description: 检查代码中的安全漏洞 trigger: 当用户要求安全检查、或代码涉及用户输入处理时触发 steps: - 检查硬编码密钥 - 检查 SQL 注入风险 - 检查 XSS 风险 - 检查权限校验缺失 next_skill: generate-fix-suggestion

next_skill字段告诉 AI，这个技能执行完后，如果发现了问题，可以接着调用“生成修复建议”技能。这样就把两个独立的技能串成了一条工作流。

不过要注意，串联层数不要超过三层。我试过串四五个技能，结果 AI 在执行过程中容易丢失上下文，后面的技能拿不到前面技能的输出结果。三层以内比较稳定，再复杂的话建议拆成多轮对话来完成。

5. 常见问题与排查技巧实录

5.1 技能不触发或触发错误

这是最常见的问题，表现是你说了一句话，AI 没有调用你期望的技能，或者调用了错误的技能。排查思路如下。

先检查触发条件是否匹配。把你实际说的话和技能定义里的trigger字段对比，看是否有语义上的偏差。比如你说了“帮我看看这段代码有没有问题”，而技能触发条件写的是“当用户要求审查代码时触发”，AI 可能认为“看看有没有问题”不等于“审查”，就不触发。解决办法是把触发条件写得更口语化、更宽泛。

再检查技能之间是否有冲突。如果两个技能的触发条件都匹配了你当前说的话，AI 可能会随机选一个，或者选优先级更高的那个。这时候需要调整触发条件的边界，让每个技能有明确的适用场景。

还有一个容易被忽略的原因是技能文件没有被正确加载。检查助手配置里的技能路径是否正确，文件格式是否符合要求（比如 YAML 缩进是否正确），文件名是否和技能名一致。我遇到过因为 YAML 里多了一个空格导致整个技能文件解析失败的情况，排查了半天才发现。

5.2 输出格式不符合预期

AI 没有按照output_format里的格式输出，可能的原因有几个。一是格式定义太复杂，AI 理解不了。解决办法是简化格式，去掉嵌套层级，用最直白的标题和列表。二是格式定义里有歧义，比如用了“可选”这样的词，AI 可能理解为“可以省略”，结果把关键部分省掉了。解决办法是用明确的“必须包含”和“禁止包含”来约束。

三是 AI 在生成过程中“忘记”了格式要求。这种情况在长对话中尤其常见，因为对话历史太长，格式要求被淹没在大量文本里。解决办法是在技能定义里加入“输出前检查格式”的步骤，让 AI 在生成完内容后自己核对一遍格式。

5.3 技能执行结果不稳定

同一个技能，有时候执行得好，有时候执行得差，这种不稳定性最让人头疼。根据我的经验，原因通常不在技能定义本身，而在输入内容的差异。比如代码审查技能，审查一个简单的工具函数和审查一个复杂的业务模块，AI 的表现肯定不一样。对于复杂输入，AI 可能只检查了前几个步骤就“累了”，后面的步骤草草了事。

应对办法是在技能定义里加入强制检查点。比如在代码审查技能的步骤里，每一步后面都加一句“完成后输出当前步骤的检查结果”，这样 AI 必须逐步输出，不能跳步。另外，对于特别复杂的任务，可以拆成多个技能分多次调用，每次只处理一个方面，而不是试图用一个技能搞定所有事。

5.4 常见问题速查表

5.5 几个我踩过的坑和对应的经验

第一个坑是技能命名太随意。一开始我用“check1”“helper2”这样的名字，结果时间一长自己都忘了每个技能是干什么的，更别说让 AI 正确调用了。后来改成用“动词+名词”的命名方式，比如“review-code”“generate-test”“check-security”，一目了然。

第二个坑是在技能定义里写太多“不要做什么”。比如“不要生成太长的代码”“不要忽略边界情况”，这些否定式指令 AI 理解起来反而容易出错。后来我改成正面描述：“生成的代码控制在 50 行以内”“必须包含空值和边界值处理”，效果好了很多。

第三个坑是技能库更新后没有通知团队。有一次我修改了一个代码审查技能，增加了新的检查项，但团队其他人不知道，还在用旧的对话方式，结果审查结果不一致。后来我们约定，技能库的修改要像代码修改一样走合并请求流程，确保所有人都知道变更内容。

6. 进阶玩法：把技能库变成团队资产

6.1 技能库的版本管理与协作

技能库既然是团队共享的资产，就应该像代码一样管理。我的做法是把.ai-skills/目录纳入版本控制，每次修改技能都提交一个独立的变更，写清楚修改原因和影响范围。在合并请求里，可以附上修改前后的技能执行对比，让审查者直观看到变化。

对于大型团队，还可以考虑把技能库拆分成“基础技能”和“项目技能”两层。基础技能是所有项目通用的，比如代码审查、生成提交信息；项目技能是特定项目专用的，比如某个项目的接口规范检查。基础技能放在一个独立的仓库里，通过子模块或包管理工具引入到各个项目中，这样更新基础技能时所有项目都能受益。

6.2 根据项目特点定制技能

不同技术栈的项目需要不同的技能。比如 Java 项目可能需要“检查空指针异常”的技能，前端项目可能需要“检查组件命名规范”的技能，数据项目可能需要“检查 SQL 性能”的技能。定制技能的关键是把项目里反复出现的检查项固化下来。

我参与过一个 Java 后端项目，团队经常在代码审查时发现“日志打印没有脱敏”的问题。后来我们写了一个“检查日志脱敏”的技能，触发条件是“当代码中包含日志打印语句时触发”，步骤是“检查日志参数是否包含手机号、身份证号、邮箱等敏感字段，如果有则标记为严重问题”。这个技能上线后，同类问题再也没在审查中漏掉过。

6.3 技能效果的度量与优化

技能库建好之后，怎么知道它有没有效果？我通常看两个指标：问题发现率和返工率。问题发现率是指技能执行后发现的真实问题数量，返工率是指技能输出被人工修改的比例。如果问题发现率高且返工率低，说明技能定义得比较准确；如果返工率高，说明技能输出不符合实际需求，需要调整。

度量的方式可以很简单，就是在技能输出后面加一个“人工确认”环节，让使用者标记哪些输出被采纳了、哪些被修改了。积累一段时间的数据后，就能看出哪些技能需要优化。我自己的经验是，一个技能通常需要经过三到五轮迭代才能达到比较稳定的状态，第一版不用追求完美，先跑起来再改。

6.4 技能库的扩展方向

技能库的扩展没有上限，但要有优先级。我的建议是优先扩展高频、高价值、高重复性的场景。高频是指每天都会用到的，比如生成提交信息；高价值是指能避免严重问题的，比如安全检查；高重复性是指每次做法都一样的，比如生成接口文档。这三个条件满足得越多，越值得做成技能。

另外，技能库也可以和项目的持续集成流程结合。比如在提交代码时自动触发代码审查技能，把审查结果作为合并请求的评论附上。这样技能库就不只是个人效率工具，而是团队质量保障体系的一部分。不过这种集成需要对 AI 助手的接口有比较深入的了解，适合有一定工程能力的团队尝试。

注意：技能库扩展时要注意维护成本。每增加一个技能，就多了一份需要维护的定义文件。如果某个技能半年都没人用，可以考虑归档或删除，避免技能库变得臃肿难维护。

7. 一些个人体会和后续可以尝试的方向

我在多个项目里用过 superpowers 这套技能包机制，最大的感受是：它把 AI 助手从“聪明的实习生”变成了“靠谱的同事”。实习生需要你每次交代任务都说清楚要求，而靠谱的同事知道你的规范，你只需要说“帮我审查一下这个模块”，他就能按你期望的方式完成。技能包做的就是这件事，把“说清楚要求”这个步骤提前固化下来。

踩过几次坑之后，我总结出一条原则：技能定义要像写单元测试一样写。单元测试的特点是输入明确、预期输出明确、边界情况覆盖到位。技能定义也应该这样，触发条件明确、执行步骤明确、输出格式明确、异常情况有兜底。按照这个标准写出来的技能，稳定性会高很多。

后续可以尝试的方向，一个是把技能库和项目的代码规范检查工具打通，让 AI 技能和传统静态检查工具互补，AI 负责语义层面的检查，静态工具负责语法层面的检查。另一个是探索技能之间的自动编排，比如根据当前对话上下文自动推荐应该使用哪个技能，而不是完全依赖用户手动触发。这些方向都还在早期，但值得关注。

最后分享一个小技巧：定期回顾技能库的使用情况。我每个月会花十分钟看一下哪些技能调用最多、哪些几乎没被用过、哪些经常被人工修改。调用多的技能可以考虑进一步优化，没被用过的技能要么删掉要么重新设计触发条件，经常被修改的技能说明定义和实际需求有偏差，需要调整。这个习惯让我的技能库始终保持精简和实用，不会变成一堆没人维护的“僵尸技能”。