企业官网建设流程全解析

1. 从“superpowers”这个热词说起：它到底指什么

“superpowers”这个词最近在技术社区和效率工具圈子里被反复提及，很多人第一次看到它是在某个开源项目的讨论区，或者是在朋友转发的一条“效率翻倍”的截图里。它不是一个具体的软件名称，也不是某个大厂出品的商业产品，而是一个面向AI编程助手的能力扩展框架——你可以把它理解成给AI助手装上一套“技能包”，让它在处理具体任务时不再只会聊天，而是能按照预设的流程、规范和工具链去真正干活。

我第一次接触这个概念是在一个自动化脚本项目里。当时团队里有人在讨论“怎么让AI助手稳定地按照我们的代码规范生成模块”，有人甩出一个链接说“试试superpowers”。点进去一看，发现它本质上是一组可复用的技能定义文件，每个技能文件描述了一类任务的标准操作流程，比如“如何创建一个符合团队规范的React组件”“如何写一个带完整错误处理的API调用”“如何生成一份结构化的技术文档”。AI助手在接收到任务时，会先匹配对应的技能，然后按照技能里定义的步骤、约束和输出格式来执行。

这解决了一个非常实际的痛点：AI助手的能力上限很高，但下限很不稳定。同一个问题，你换个问法，它给出的代码质量可能天差地别。而superpowers的思路是，把“好”的标准固化下来，变成可加载、可组合、可版本管理的技能模块。这样一来，无论谁来用、什么时候用，只要触发了对应的技能，输出质量就有了基本保障。

适合关注这个内容的人大致有三类：一是日常用AI助手写代码的开发者，想让自己得到的输出更稳定、更符合项目规范；二是技术团队的负责人，在考虑怎么把AI工具纳入团队的标准化流程；三是对AI工作流感兴趣的技术爱好者，想了解当前这个领域里比较前沿的实践方式。不管你属于哪一类，接下来的内容都会从实际使用的角度，把superpowers的安装、配置、核心机制和踩坑经验讲清楚。

2. 安装superpowers之前，先把这几个概念理清楚

2.1 技能文件不是插件，它的运行逻辑和你想的不一样

很多人第一次听到“安装superpowers”，下意识会以为它像装一个VS Code插件或者npm包那样，装完就多了一个菜单、一组按钮。实际不是。superpowers的核心是一组Markdown格式的技能描述文件，它们本身不包含可执行代码，而是用自然语言加结构化标记的方式，告诉AI助手“遇到这类任务时应该怎么做”。

举个例子，一个典型的技能文件可能长这样：开头是技能名称和触发条件，中间是分步骤的操作指引，最后是输出格式要求和检查清单。AI助手在运行时，会把这些内容读进上下文，然后按照里面的指引来生成回复。所以“安装”这个动作，本质上做的是把技能文件放到AI助手能够读取到的目录里，并且在助手的配置中声明这个目录的路径。

这个逻辑决定了几个重要的事实：第一，技能文件是可以随时修改的，改完立刻生效，不需要重新编译或重启什么服务；第二，技能之间可以相互引用，一个技能可以调用另一个技能作为子流程；第三，技能文件的质量直接决定了AI输出的质量，写技能文件本身就是一项需要认真对待的工作。

2.2 为什么是Markdown而不是JSON或YAML

你可能会问，既然是要给机器读的，为什么不用更结构化的JSON或者YAML？我一开始也有这个疑问，后来在实际写了几十个技能文件之后才理解这个选择的合理性。

Markdown的优势在于人和机器都能读。JSON写起来对非程序员不友好，一个括号写错整个文件就废了；YAML虽然可读性好一些，但缩进敏感，复制粘贴时容易出问题。而Markdown的语法足够宽松，AI助手在解析时对格式的容忍度也高，同时人类维护起来几乎没有门槛。更重要的是，技能文件里需要大量使用自然语言来描述“什么情况下应该怎么做”“遇到某种错误时应该怎么处理”，这些内容用Markdown写出来最自然。

另外，Markdown格式让技能文件可以很方便地做版本管理。你可以用Git来追踪每个技能的修改历史，可以对比不同版本之间的差异，可以在Pull Request里讨论某个步骤的措辞是否准确。这些在团队协作场景下非常重要。

2.3 安装前需要确认的环境条件

在动手之前，有几件事需要先确认好，否则后面会反复卡住。

第一，确认你的AI助手支持加载外部技能文件。目前主流的几款AI编程助手都在不同程度上支持这个能力，但具体的配置方式有差异。你需要先查一下你用的那个助手，它的文档里有没有提到“自定义指令”“技能目录”“上下文文件”之类的概念。如果没有，那superpowers这套东西暂时用不了。

第二，确认文件系统的读写权限。技能文件需要放在一个AI助手能够读取的目录里，通常是在用户主目录下的某个隐藏文件夹，或者项目根目录下的特定文件夹。你需要确保当前用户对这个目录有读写权限。

第三，确认你的使用场景。superpowers最适合的是重复性高、有明确规范要求的任务，比如生成特定框架的代码、写符合公司模板的文档、执行标准化的代码审查流程。如果你只是偶尔问一些零散的问题，那装不装superpowers差别不大。

提示：在正式安装之前，建议先在一个测试项目里跑通整个流程，确认技能文件能被正确加载和触发，再推广到正式项目里。

3. 一步步完成superpowers的安装与初始化

3.1 获取技能文件：从官方仓库到本地目录

superpowers的技能文件通常托管在一个公开的代码仓库里。获取方式有两种：一种是直接用Git克隆到本地，另一种是下载压缩包解压。我推荐用Git克隆，因为后续更新技能文件时只需要执行一次pull操作，比重新下载解压方便得多。

克隆命令大致是这样的：

git clone <技能仓库地址> ~/.ai-skills/superpowers

这里把技能文件放在了用户主目录下的.ai-skills/superpowers目录里。这个路径不是固定的，你可以放在任何你觉得合适的地方，只要后面在AI助手的配置里指向这个路径就行。但建议不要放在项目目录里，因为项目目录通常会被Git管理，技能文件混在里面容易造成混淆。

克隆完成之后，你会看到目录里有一系列.md文件，每个文件对应一个技能。可能还有一个README.md说明文件和一个manifest.json清单文件。清单文件里列出了所有技能的元信息，包括技能名称、触发关键词、依赖关系等。AI助手在加载时会先读这个清单，然后按需加载具体的技能文件。

3.2 配置AI助手：让技能目录被正确识别

这一步是整个安装过程中最容易出问题的环节。不同的AI助手有不同的配置方式，但核心逻辑是一样的：告诉助手去哪里找技能文件。

以常见的几种配置方式为例：

• 如果助手支持在设置界面里填写“自定义指令目录”，那就把刚才克隆下来的目录路径填进去。
• 如果助手是通过配置文件来管理的，那就找到对应的配置项，把路径写进去。配置文件通常是JSON或YAML格式，路径要写绝对路径，不要写相对路径。
• 如果助手支持在项目根目录放一个特定名称的文件夹（比如.ai-skills），那就把技能文件复制或软链接到那个位置。

配置完成之后，需要重启助手或者重新加载配置。有些助手是即时生效的，有些需要手动触发一次重载。重启之后，你可以通过问一个测试问题来验证技能是否被加载了。比如，如果有一个技能是“生成React函数组件”，你就问“帮我写一个React函数组件”，看助手的回复里有没有体现出技能文件里定义的规范。

注意：如果助手没有任何反应，先检查路径是否正确、文件是否有读取权限、清单文件是否格式正确。这三个是最常见的失败原因。

3.3 验证安装：用一个最小技能做端到端测试

在正式使用之前，建议先做一个最小化的验证。具体做法是：在技能目录里新建一个最简单的技能文件，比如叫hello-world.md，内容就是“当用户说‘测试技能’时，回复‘技能加载成功’”。然后在清单文件里注册这个技能，重启助手，输入“测试技能”，看回复是否符合预期。

这个测试看起来很简单，但它能帮你确认整条链路是通的：文件放对了位置、清单格式正确、助手能读取到、触发条件能匹配、输出能正确生成。如果这一步失败了，后面更复杂的技能也不可能正常工作。

验证通过之后，你可以把测试用的技能文件删掉，或者保留着作为以后排查问题的参照。

3.4 技能文件的目录结构建议

随着你写的技能越来越多，目录结构会变得很重要。我建议按功能领域来组织子目录，比如：

superpowers/ coding/ react-component.md api-endpoint.md error-handling.md writing/ tech-doc.md changelog.md review/ code-review.md security-check.md manifest.json

这样组织的好处是，当你想找某个技能时能快速定位，也方便在清单文件里按目录来批量注册。另外，建议给每个技能文件起一个能说明用途的名字，不要用skill1.md、skill2.md这种，时间久了根本记不住哪个是哪个。

4. 技能文件到底怎么写才能让AI真正听话

4.1 触发条件的设计：什么情况下该激活这个技能

触发条件是技能文件的第一道关口。写得太宽泛，技能会被频繁误触发，干扰正常对话；写得太窄，该用的时候用不上，等于白写。

一个好的触发条件应该包含三个要素：任务类型、关键词、上下文特征。任务类型是指这个技能适用于哪类工作，比如“创建新文件”“修改现有代码”“生成文档”。关键词是用户可能会说的词，比如“组件”“接口”“测试用例”。上下文特征是指当前对话或项目的状态，比如“当前目录下存在package.json”“用户正在编辑.tsx文件”。

举个例子，一个用于生成React组件的技能，触发条件可以这样写：

当用户要求创建一个新的React组件，且当前项目包含React依赖时，激活此技能。用户可能使用的表述包括“写一个组件”“创建一个React组件”“帮我生成一个组件文件”。

这样写的好处是，AI助手在判断是否激活技能时，有明确的依据，而不是靠模糊的语义相似度去猜。

4.2 步骤拆解：把“怎么做”写到不需要思考的程度

技能文件的核心价值在于把操作步骤标准化。写步骤的时候，要假设读这个文件的人（或者AI）对这个任务完全没有经验，每一步都要写清楚“做什么”“为什么这么做”“做到什么程度算完成”。

以“创建一个符合团队规范的React函数组件”为例，步骤可以这样拆：

1. 确认组件名称。组件名称使用PascalCase，且必须与文件名一致。如果用户没有提供名称，根据功能描述推导一个合适的名称，并向用户确认。
2. 创建文件。文件放在src/components/目录下，文件扩展名为.tsx。如果目录不存在，先创建目录。
3. 写入导入语句。导入React和必要的类型定义。如果组件需要用到状态或副作用，导入对应的Hook。
4. 定义Props类型。使用TypeScript的interface或type来定义，每个Prop都要有注释说明用途。
5. 编写组件函数。使用箭头函数形式，导出方式使用命名导出。
6. 添加默认导出。在文件末尾添加export default 组件名。
7. 自检。检查组件名称、文件路径、导入语句、类型定义、导出方式是否符合上述规范。

每一步都具体到不需要再做决策的程度。这样AI在执行时就不会自由发挥，输出质量自然就稳定了。

4.3 输出格式约束：让结果可以直接用

输出格式约束是很多人写技能文件时容易忽略的部分。如果不加约束，AI可能会在代码前后加一堆解释性文字，或者用不统一的代码块标记，导致你每次都要手动清理。

有效的输出格式约束应该明确规定：代码块的语言标记、注释的风格、是否包含示例用法、是否包含测试代码。比如：

输出时，先给出完整的代码块，语言标记为tsx。代码块之后，用一段不超过三句话的文字说明组件的用途和关键实现点。不要输出额外的示例用法，除非用户明确要求。

这样写之后，AI的输出就会变得非常规整，复制粘贴到项目里就能用，省去了大量清理时间。

4.4 错误处理与边界情况：技能文件里的“如果……就……”

一个健壮的技能文件必须考虑边界情况和错误处理。比如，用户要求的组件名称和已有文件冲突怎么办？用户没有提供必要的Props定义怎么办？项目里没有安装TypeScript怎么办？

这些情况如果不提前写好处理逻辑，AI可能会随机应变，给出不一致的解决方案。正确的做法是在技能文件里用“如果……就……”的句式把这些分支都覆盖到：

如果目标文件已存在，不要覆盖，而是向用户报告冲突并询问是否重命名或覆盖。如果项目中没有TypeScript依赖，改用.jsx扩展名并移除类型定义。如果用户没有提供Props定义，根据组件功能推导一组合理的Props，并在输出中说明这是推导结果。

这些分支写得越全，技能在实际使用中就越可靠。

5. 实际使用中那些文档不会告诉你的坑

5.1 技能冲突：当两个技能同时被触发

这是我在实际使用中遇到的第一个大坑。当时我写了一个“生成API接口”的技能和一个“生成数据模型”的技能，结果有一次用户说“帮我创建一个用户相关的接口和数据模型”，两个技能同时被触发了，AI的回复里一半内容按接口技能的格式来，一半按数据模型技能的格式来，看起来非常混乱。

解决这个问题的办法有两个：一是在技能文件里明确写出优先级，当多个技能同时匹配时，优先级高的先执行；二是在触发条件里加入互斥判断，比如“如果当前对话中已经激活了数据模型技能，则本技能不激活”。

我后来采用的是第二种方案，在触发条件里加了一行：“当用户同时要求创建接口和数据模型时，先激活数据模型技能，完成后再激活接口技能。”这样就把冲突变成了顺序执行，输出就清晰了。

5.2 上下文长度限制：技能文件不是越长越好

刚开始写技能文件的时候，我恨不得把所有的规范、所有的边界情况都写进去，结果一个技能文件写了三千多字。用了几次之后发现，AI在加载这个技能后，处理其他问题的能力明显下降了，因为上下文窗口被技能文件占用了太多。

后来我总结出一个经验：单个技能文件的长度控制在800到1500字之间比较合适。超过这个范围，就要考虑拆分成多个技能，或者把一些不常用的细节移到单独的参考文件里，只在需要的时候才加载。

另外，技能文件里的语言要精炼，不要写大段的背景介绍和原理说明。那些内容可以放在单独的文档里，技能文件只保留“做什么”和“怎么做”。

5.3 版本更新后的兼容性问题

superpowers的技能文件格式并不是一成不变的。官方仓库会不定期更新清单文件的格式、技能文件的元信息字段、触发条件的语法等。如果你直接pull了最新版本，而你的AI助手还是旧版本，可能会出现技能加载失败的情况。

我的做法是：在更新之前先看CHANGELOG，确认有没有破坏性变更。如果有，就先在测试环境里验证一遍，确认没问题再更新正式环境。另外，建议把你自己的技能文件和官方仓库的技能文件分开存放，这样更新官方仓库时不会覆盖你自己的修改。

5.4 技能文件里的“模糊指令”是最大的隐患

什么叫模糊指令？就是那些看起来没问题、但AI理解起来有多种可能的表述。比如“生成一个合理的默认值”“根据情况选择合适的方案”“必要时添加注释”。这些词对人来说很自然，但对AI来说就是不确定的。

我踩过的一个典型坑是：在一个技能文件里写了“如果用户没有指定端口号，使用一个合理的默认值”。结果AI有时候用3000，有时候用8080，有时候用5000，完全看它当时的心情。后来我把这句话改成了“如果用户没有指定端口号，使用3000”，问题就解决了。

所以写技能文件时，要时刻问自己：这句话有没有第二种理解方式？如果有，就把它改到只有一种理解方式为止。

6. 把superpowers用出效果的几个进阶思路

6.1 技能组合：让多个技能串成一条流水线

单个技能解决的是单点问题，但实际工作中往往需要一连串的操作。比如“创建一个新页面”可能涉及：生成组件文件、生成样式文件、生成测试文件、更新路由配置、更新导航菜单。如果每个步骤都是一个独立的技能，那用户需要依次触发五次，效率很低。

更好的做法是定义一个组合技能，它的步骤就是依次调用其他技能。组合技能本身不包含具体的代码生成逻辑，只负责编排流程。这样既保持了单个技能的可复用性，又提供了端到端的便利性。

我在项目里定义了一个“创建新页面”的组合技能，它依次调用“生成组件”“生成样式”“生成测试”“更新路由”四个子技能。用户只需要说一次“创建一个用户列表页面”，剩下的就自动完成了。

6.2 技能继承：在通用规范上叠加项目特定规范

如果你同时在多个项目里使用superpowers，会发现有些规范是通用的（比如代码风格、注释格式），有些是项目特定的（比如目录结构、导入路径别名）。这时候可以用技能继承的方式来组织。

具体做法是：先定义一个基础技能，包含通用规范；然后为每个项目定义一个继承技能，在基础技能的基础上叠加项目特定的规范。AI在加载时，会先读基础技能，再读继承技能，后者可以覆盖前者的某些步骤。

这样你只需要维护一份通用规范，项目特定的部分单独维护，修改时互不影响。

6.3 用技能文件来做代码审查

除了生成代码，技能文件还可以用来做代码审查。你可以写一个“代码审查”技能，里面定义审查的检查项：命名规范、错误处理、边界条件、性能隐患、安全风险等。当用户要求审查某段代码时，AI会按照这个技能里定义的检查项逐条过一遍，输出一份结构化的审查报告。

这个用法的好处是，审查标准是显式定义的，不会因为AI的状态不同而漏掉某些检查项。而且你可以根据团队的实际情况不断补充检查项，让审查越来越全面。

6.4 技能文件的测试与迭代

技能文件写完之后，不是就万事大吉了。你需要像测试代码一样测试技能文件。具体做法是：准备一组测试用例，每个用例包含输入（用户会说的话）和期望输出（符合技能规范的回复）。然后逐个运行，看实际输出和期望输出的差距。

如果发现某个用例的输出不符合预期，就回去修改技能文件里对应的步骤或约束，然后重新测试。这个过程可能需要反复几轮，但每轮都会让技能文件更可靠。

我自己的习惯是，每写完一个新技能，至少跑五个测试用例：一个正常情况、两个边界情况、两个错误情况。全部通过之后，才把这个技能加入到正式使用的技能集合里。

6.5 团队协作中的技能管理

如果是团队使用，技能文件的管理就需要更规范一些。建议的做法是：把技能文件放在一个独立的Git仓库里，团队成员都可以提交Pull Request来修改或新增技能。每次修改都需要至少一个人review，确认修改不会破坏现有技能的行为。

另外，建议给技能文件加上版本号，并且在清单文件里记录每个技能的版本。这样当某个技能的行为发生变化时，可以追溯到是哪个版本引入的。

还有一个实用的小技巧：在技能文件的开头加一个“变更记录”段落，简要记录每次修改的内容和原因。这样新加入团队的成员可以快速了解这个技能的演进过程。

7. 关于superpowers，我踩过的最大的一个坑

说了这么多，最后分享一个我踩过的最大的坑。刚开始用superpowers的时候，我特别兴奋，一口气写了二十多个技能文件，覆盖了各种场景。结果用了一段时间之后发现，AI助手变得越来越“死板”，遇到稍微超出技能定义范围的情况就不知道怎么办了，回复质量反而下降了。

后来我才想明白：技能文件是约束，不是替代。它的作用是让AI在特定任务上表现得更稳定，而不是让AI在所有任务上都按照预设的流程走。如果技能文件覆盖得太广，AI的自由度被过度限制，遇到新情况时就无法灵活应对。

所以我现在遵循的原则是：只给那些高频、高重复、有明确规范的任务写技能文件。对于那些每次都不一样的任务，就让AI自由发挥。技能文件和自由发挥之间的比例，大概控制在三七开比较合适。

另外，技能文件要定期回顾和清理。有些技能可能写完之后就没怎么用过，或者随着项目变化已经不再适用了。这些技能留在目录里，不仅占用上下文空间，还可能在某个时刻被误触发。我现在的习惯是每个季度过一遍技能列表，把不再使用的删掉，把需要更新的更新。

这个坑说到底是一个认知问题：superpowers是一个工具，工具的价值在于解决具体问题，而不是为了用而用。想清楚这一点之后，用起来就顺手多了。