企业官网建设流程全解析

1. 从“超能力”到可落地的技能系统：我为什么盯上了 superpowers

第一次看到 “superpowers” 这个词，是在一个开发者社群里有人问：“有没有那种能让日常工作效率直接翻倍的工具集？”底下有人回了一句：“你去看看 superpowers，装完就像给自己开了挂。”说实话，这种描述放在以前我是不信的，毕竟“开挂”这个词被用烂了。但当我真正花了一个周末把 superpowers 从安装到实际跑通、再到拆解它内部的 skills 机制之后，我承认这个名字起得确实不夸张。

superpowers 本质上是一套面向 AI 编程助手（尤其是 Claude Code 这类终端里的智能体）的技能扩展框架。它做的事情，简单说就是：把你平时反复要跟 AI 解释的“工作规范”“操作流程”“领域知识”，提前打包成一个个可复用的 skill（技能模块），让 AI 在需要的时候自动加载、按你的规矩干活。它解决的核心痛点是——AI 每次对话都像失忆，你得反复交代背景、反复纠正格式、反复提醒它别乱改代码。而 superpowers 通过一套结构化的技能注入机制，让 AI 在特定场景下自动“想起”该怎么做。

这套东西适合谁？我梳理了一下，大概三类人最该关注：第一类是每天用 AI 写代码、但被 AI 的“自由发挥”折磨到崩溃的开发者；第二类是想把团队内部规范沉淀下来、让 AI 自动遵守的技术负责人；第三类是对 AI 工作流感兴趣、想搞明白“技能注入”到底怎么实现的技术爱好者。哪怕你只是刚接触 AI 编程助手，只要你能照着步骤操作，也能在半小时内把基础框架跑起来。

我写这篇东西的出发点很简单：网上关于 superpowers 的中文资料太碎了，要么是几句安装命令，要么是截图堆砌，没人把“它为什么这么设计”“skills 到底怎么写”“引入技能时踩了哪些坑”讲透。我把自己从零搭建、调试、再到实际项目里用起来的完整过程整理出来，包括那些官方文档里不会写的细节。你照着做，能少走至少两天的弯路。

2. 核心机制拆解：superpowers 到底是怎么“注入技能”的

2.1 技能不是插件，而是“按需加载的上下文”

很多人第一次接触 superpowers，会下意识把它理解成“插件系统”——装一个功能就多一个按钮。但实际用下来你会发现，它的设计哲学更接近上下文注入。每个 skill 本质上是一个结构化的 Markdown 文件（通常叫SKILL.md），里面写清楚了：这个技能叫什么、什么时候触发、触发后 AI 应该遵循哪些步骤、有哪些注意事项、输出格式是什么样。

当你在终端里跟 AI 对话时，superpowers 会根据你当前的任务描述，去匹配已安装的 skill。匹配上了，就把这个 skill 的内容作为额外上下文塞给 AI。AI 看到的不再是干巴巴的用户提问，而是“用户提问 + 这个场景下的操作手册”。这就是为什么装完 superpowers 之后，你会感觉 AI “突然懂规矩了”——不是模型变聪明了，而是你提前把规矩写好了。

这种设计的好处非常明显。传统做法是你每次都要在 prompt 里写一大段“请按照以下规范……”，又长又容易漏。而 skill 是持久化的、可版本管理的、可分享的。你写一次，以后每次触发都自动生效。更关键的是，skill 文件是纯文本，你可以用 Git 管理，可以团队共享，可以随时改。这比把规范写在某个文档里然后指望大家自觉遵守，靠谱太多了。

2.2 一个 skill 的标准结构长什么样

我拆了几个官方和社区里质量比较高的 skill，发现它们基本都遵循一个相似的结构。虽然不强制，但按这个结构写，AI 的识别率和执行准确率明显更高。我把它总结成下面这张表：

我一开始偷懒，只写了 name 和 steps，结果 AI 经常在边缘情况下跑偏。后来补上 constraints 和 examples，稳定性肉眼可见地变好。特别是 constraints，你一定要把“不要做什么”写清楚。AI 的默认倾向是“尽量帮忙”，你不告诉它边界，它就会过度发挥。

2.3 技能匹配的底层逻辑：关键词、语义与优先级

superpowers 匹配 skill 的方式，我实测下来是关键词命中 + 语义相似度的混合策略。它不是简单地看你这句话里有没有某个词，而是会综合判断。举个例子，你写了一个叫code-review的技能，触发条件里写了“审查代码”“检查代码质量”“review”。当你说“帮我看看这段代码有没有问题”时，虽然没有完全命中关键词，但语义上很接近，它也能匹配上。

但这里有个坑：如果你装了很多技能，有些技能的触发条件写得太宽泛，就会互相抢。比如一个技能写“任何时候都可以用”，那它几乎会污染所有对话。我的做法是给每个技能的when_to_use加上限定词，比如“当用户明确提到‘部署’且涉及服务器配置时”。限定得越清楚，误触发越少。

另外，superpowers 支持给技能设置优先级。当多个技能同时匹配时，优先级高的先加载。这个机制在团队协作场景里特别有用——你可以把公司强制规范设成高优先级，个人偏好设成低优先级，冲突时以公司规范为准。

2.4 为什么是 Markdown 而不是代码

这个问题我一开始也没想明白。按理说，技能逻辑用代码写不是更灵活吗？后来用久了才体会到，Markdown 的优势在于人和 AI 都能读。你用代码写逻辑，AI 得先理解代码再执行，中间多了一层翻译。而 Markdown 本身就是自然语言，AI 直接读直接执行，路径最短。

更重要的是，Markdown 让非程序员也能参与技能编写。我们团队里有个产品经理，他不懂代码，但他能把自己那套需求评审的流程写成 skill。写完之后 AI 就能按他的流程走，他特别有成就感。如果技能必须用代码写，这件事就跟他没关系了。所以这个设计选择，表面看是技术决策，实际上是在扩大使用者的范围。

3. 从零安装到跑通第一个技能：完整实操记录

3.1 安装前的环境确认与依赖检查

在动手之前，你得先确认自己的环境。superpowers 主要是配合终端里的 AI 编程助手使用的，所以你的机器上得先有对应的运行环境。我当时的配置是 macOS，Node.js 版本 18 以上，终端用的是 iTerm2。Windows 用户用 WSL 或者 PowerShell 都可以，但路径处理上会有些差异，后面我会提到。

第一步，确认 Node.js 和包管理器是否就绪。打开终端，跑这两条命令：

node -v npm -v

如果版本号正常输出，说明基础环境没问题。Node.js 建议 18 LTS 或更高，太低版本有些依赖装不上。我有个朋友用 Node 14 折腾了半天，最后升级到 20 才顺利跑通。

第二步，确认你的 AI 编程助手已经安装并可以正常对话。superpowers 本身不是一个独立的 AI，它是给现有助手加技能的。所以你得先有一个能用的助手环境。这部分每个人的情况不一样，按你平时用的来就行。

第三步，找一个合适的目录存放技能文件。我建议单独建一个目录，比如~/superpowers-skills/，不要跟项目代码混在一起。原因是技能文件需要长期维护和版本管理，混在项目里容易误删，也不方便跨项目复用。

提示：如果你在公司网络环境下操作，先确认包管理器的源是可访问的。我遇到过因为源配置问题导致安装卡住的情况，换成默认源就正常了。

3.2 安装 superpowers 框架的三种方式与选择建议

superpowers 的安装方式，我试过三种，各有适用场景。下面这张表是我实测后的对比：

我个人的选择是全局安装 + 项目本地技能目录的组合。框架全局装一份，技能文件放在项目里用 Git 管理。这样框架升级不影响技能，技能变更也能被团队看到。

安装命令跑完之后，用下面这条命令验证是否成功：

superpowers --version

能输出版本号就说明框架就位了。如果提示命令找不到，大概率是全局 bin 目录没加到 PATH 里。macOS 和 Linux 下通常是/usr/local/bin或~/.npm-global/bin，Windows 下是 npm 的全局目录。把这个路径加到环境变量里再试。

3.3 初始化技能目录与配置文件

框架装好之后，需要初始化技能目录。superpowers 默认会去几个固定位置找 skill 文件，你也可以通过配置文件指定自定义路径。我建议第一次用的时候，先跑初始化命令：

superpowers init

这个命令会在当前目录下生成一个.superpowers/文件夹，里面包含skills/子目录和一个config.json。skills/就是你放技能文件的地方，config.json控制加载行为。

打开config.json，你会看到类似这样的结构：

{ "skillsDir": "./skills", "autoLoad": true, "priority": { "default": 5 }, "maxSkillsPerTurn": 3 }

几个关键参数我解释一下。skillsDir是技能文件目录，可以改成绝对路径。autoLoad控制是否自动匹配加载，设成false的话就得手动指定用哪个技能。maxSkillsPerTurn限制单次对话最多加载几个技能，这个很重要——加载太多会稀释 AI 的注意力，我实测下来 3 个是比较舒服的上限，超过 5 个效果反而下降。

注意：maxSkillsPerTurn不要设太大。我一开始图省事设成 10，结果 AI 经常把不相关的技能内容也带进回答里，输出变得又长又乱。后来降到 3，精准度明显提升。

3.4 写第一个 skill：从“代码审查”开始

理论说再多不如动手写一个。我选“代码审查”作为第一个技能，因为这个场景高频、需求明确、容易验证效果。在skills/目录下新建一个文件夹code-review，里面创建SKILL.md，内容如下：

--- name: code-review description: 对用户提供的代码进行结构化审查，输出问题清单和改进建议 when_to_use: 当用户说“审查代码”“检查代码”“review”“看看这段代码有没有问题”时触发 priority: 7 --- ## 审查步骤 1. 先通读代码，理解整体意图，不要急着挑毛病 2. 按以下维度逐项检查： - 正确性：逻辑是否有漏洞，边界条件是否处理 - 可读性：命名是否清晰，结构是否合理 - 性能：是否有明显的低效操作 - 安全性：是否有输入未校验、敏感信息硬编码等问题 3. 每个问题标注严重程度：阻塞 / 建议 / 提示 4. 给出具体的修改建议，不要只说“这里不好” ## 约束 - 不要直接重写用户的代码，除非用户明确要求 - 不要对代码风格做主观评价，除非违反了明确的规范 - 如果代码片段不完整，先指出缺失部分，再审查已有部分 ## 输出格式 ### 问题清单 | 位置 | 问题 | 严重程度 | 建议 | |------|------|----------|------| ### 整体评价 一段话总结代码质量，指出最需要优先处理的问题

写完保存，然后在终端里跟 AI 说一句“帮我审查一下这段代码”，后面贴上任意一段代码。如果配置正确，AI 的输出应该会严格按照你定义的格式来，先出表格再出总结。我第一次看到这个效果的时候，确实有点惊喜——以前得反复交代的格式，现在一句话就自动生效了。

3.5 验证技能是否生效的三种方法

写完技能不代表就生效了，得验证。我用三种方法交叉确认：

第一种，直接触发法。用when_to_use里列出的原话去问 AI，看它是否按 skill 的格式回答。这是最直观的。

第二种，调试模式。superpowers 有个--debug参数，加上之后会输出技能匹配的详细日志，告诉你哪个技能被命中、匹配分数是多少。命令是：

superpowers --debug

日志里会显示类似matched skill: code-review (score: 0.87)的信息。如果分数很低或者没匹配上，说明你的when_to_use写得不够准，得回去改。

第三种，冲突测试。故意说一句模糊的话，看会不会误触发。比如你说“帮我看看这个东西”，如果code-review被触发了，说明它的触发条件太宽，需要加限定词。

我建议每次写完新技能，这三种方法都跑一遍。特别是冲突测试，能帮你提前发现技能之间的干扰问题。

4. 技能体系进阶：怎么组织、复用和团队共享

4.1 技能分类的三种思路与我的选择

当你写到第五个、第十个技能的时候，就会面临一个现实问题：怎么组织？全堆在一个目录里，找起来费劲，匹配也容易乱。我试过三种分类思路，最后选了第三种。

第一种是按功能分，比如coding/、writing/、ops/。这种分法直观，但边界模糊——一个“写技术文档”的技能，算 coding 还是 writing？

第二种是按触发频率分，高频的放一起，低频的放一起。这种分法对性能优化有帮助，但维护起来很别扭，因为你很难判断一个技能到底算高频还是低频。

第三种是按工作流阶段分，比如planning/、implementation/、review/、deployment/。我最后选了这个，因为 AI 的工作场景本身就是按阶段走的，按阶段分，匹配时的上下文更一致，误触发也少。

具体目录结构大概是这样：

skills/ ├── planning/ │ ├── requirement-analysis/ │ └── task-breakdown/ ├── implementation/ │ ├── code-review/ │ └── refactor-guide/ ├── review/ │ └── security-check/ └── deployment/ └── release-checklist/

每个阶段下的技能，触发条件都限定在对应阶段，互相干扰的概率大大降低。

4.2 技能复用的两个实用技巧

写多了之后你会发现，很多技能之间有重复内容。比如好几个技能都需要“先确认用户意图再动手”这一步。如果每个技能都抄一遍，改的时候就得改好几处。我用了两个技巧来解决。

第一个技巧是公共片段抽取。superpowers 支持在 skill 文件里引用其他文件，语法是{{include: common/confirm-intent.md}}。你把公共步骤写在一个单独文件里，各个技能按需引用。改一处，全部生效。

第二个技巧是技能继承。你可以定义一个基础技能，然后让其他技能继承它。比如定义一个base-coding技能，包含所有编码类技能的通用约束，然后code-review和refactor-guide都继承它。继承的语法是在 frontmatter 里加一行extends: base-coding。

这两个技巧我是在写到大概十五个技能的时候才开始用的。前期技能少，重复就重复了，没必要过度设计。但一旦超过十个，不抽公共部分，维护成本会指数级上升。

4.3 团队共享技能库的落地方式

一个人用和团队用，完全是两码事。团队用的核心挑战是：怎么保证大家用的是同一套技能，怎么处理个性化需求，怎么更新。

我的方案是三层结构：

• 基础层：公司或团队强制规范，放在一个独立的 Git 仓库里，所有人必须引用。这层技能优先级最高，不允许个人覆盖。
• 项目层：跟项目代码放在一起，随项目走。项目特有的流程、约定放这里。
• 个人层：每个人自己的目录，放个人偏好。优先级最低，冲突时让位于前两层。

superpowers 的配置支持指定多个技能目录，并且可以设置加载顺序。在config.json里这样写：

{ "skillsDirs": [ "/path/to/team-skills", "./.superpowers/skills", "~/my-personal-skills" ], "priority": { "team-skills": 10, "project": 7, "personal": 3 } }

这样配置之后，团队规范永远优先，个人习惯只在没有冲突时生效。我们团队用这套结构跑了三个月，基本没出现过“AI 按某个人的习惯乱来”的情况。

提示：团队技能库的更新要有流程。我们的做法是走 Pull Request，至少一个人 review 通过才能合并。技能文件虽然简单，但它直接影响 AI 的行为，改错了影响面不小。

4.4 技能版本管理与回滚策略

技能文件是纯文本，天然适合 Git 管理。但有个细节容易被忽略：技能的行为会随 AI 模型版本变化。同一个技能，在模型 A 上表现很好，换到模型 B 可能就触发不准了。所以版本管理不能只管文件，还得记录“这个技能在哪个模型版本下验证过”。

我的做法是在 skill 的 frontmatter 里加两个字段：

tested_with: claude-sonnet-4 last_verified: 2025-01-15

每次模型升级或者技能大改，都更新这两个字段。如果发现某个技能突然不灵了，先看last_verified是不是太久没更新，大概率是模型行为变了，需要重新调触发条件。

回滚策略也很简单：技能库用 Git 分支管理，主分支是稳定版，开发在 feature 分支。出问题了直接git revert或者切回上一个 tag。我建议每次批量更新技能前打个 tag，方便回退。

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

5.1 技能不触发或误触发怎么办

这是最高频的问题，没有之一。我整理了一个排查流程，按顺序走基本都能定位：

我踩过最坑的一次是 frontmatter 里的name用了中文，结果匹配一直失败。debug 日志里显示技能被扫描到了，但就是匹配不上。后来改成英文就好了。所以命名这块，老老实实用英文小写加连字符，别图省事。

还有一个隐蔽问题：如果你的 skill 文件编码不是 UTF-8，中文内容会乱码，AI 读到的就是乱码，自然匹配不上。保存文件时确认编码格式，这个细节很容易被忽略。

5.2 技能加载后 AI 输出变慢或变啰嗦

加载技能会往上下文里塞额外内容，塞多了自然影响输出。我遇到过两种情况：一种是加载了太多技能，AI 把每个技能的内容都复述一遍；另一种是单个技能写得太长，光读技能就花掉大量 token。

解决办法有两个。第一，控制maxSkillsPerTurn，我前面说了，3 个是上限。第二，精简技能内容。skill 文件不是越长越好，能一句话说清就别写三段。我现在的标准是：单个 skill 文件控制在 200 行以内，超过就拆成多个技能或者抽公共片段。

另外，steps部分尽量用短句，别写长段落。AI 读短句的效率比读长段落高，执行也更准。我做过对比，同样一个技能，步骤写成短句列表比写成段落，AI 的执行准确率大概高两成。

5.3 多个技能冲突时的优先级处理

冲突的表现是：AI 同时遵循了两个技能的矛盾要求，输出变得四不像。比如一个技能说“输出用表格”，另一个说“输出用列表”，AI 可能给你来个“表格里套列表”。

处理原则是明确优先级 + 消除矛盾。首先在config.json里给不同目录设不同优先级，团队规范最高。其次，如果两个技能确实会在同一场景触发，就得在其中一个里加约束，明确“当 X 技能也适用时，以 X 为准”。

我还会定期做一次“冲突审计”：把所有技能两两组合，看触发条件有没有重叠。重叠的要么合并，要么加互斥条件。这个工作有点繁琐，但做一次能管很久。

5.4 技能更新后行为不一致的排查

技能改了之后，AI 的行为跟预期不符，这种情况多半是缓存或者加载顺序的问题。superpowers 会缓存已加载的技能，改完文件后可能需要重启会话或者跑一下superpowers reload才能生效。

如果重启后还是不对，检查是不是有同名的技能存在于多个目录。比如团队目录里有个code-review，你个人目录里也有一个，加载时可能加载了你不想要的那个。debug 日志里会显示实际加载的是哪个路径的文件，对着看就能发现。

还有一种情况是技能内容里有语法错误，导致整个文件被跳过。superpowers 遇到解析失败通常会静默跳过，不会报错。所以改完技能后，最好用superpowers validate命令校验一下，确保文件能被正确解析。

5.5 我的独家避坑清单

最后分享几条我踩坑踩出来的经验，都是文档里不会写的：

• 技能名不要用保留字。我试过用help当技能名，结果跟系统命令冲突，一直出问题。避开help、init、config这类词。
• 触发条件里别写太泛的词。“帮我”“看看”“处理一下”这种词几乎每句话都有，写进去等于没写，还会导致误触发。
• 先写约束再写步骤。我现在的习惯是先想清楚“这个技能绝对不能做什么”，把约束写好，再补步骤。这样写出来的技能边界清晰，AI 不容易跑偏。
• 每个技能都要有反例。在examples里放一个“不该触发”的例子，能显著降低误触发率。
• 定期清理僵尸技能。用不上的技能及时删掉，留着只会增加匹配干扰。我每个月清理一次，保持技能库精简。
• 技能文件加注释。Markdown 里可以用<!-- -->写注释，给自己留点说明，比如“这个条件是为了避开 XX 场景”。过两个月回来看，你会感谢自己。

这套东西我从零摸索到跑顺，大概花了一个多月。现在团队里每个人都有自己的技能库，AI 干活的规矩统一了，返工率明显下降。如果你刚开始接触，别想着一次写完美，先写一个最简单的跑通，感受到效果之后再慢慢加。技能这东西，用起来比写起来重要得多。