企业官网建设流程全解析

从第一次看到“superpowers”这个项目名，我就觉得它起得特别贴切——它不是给AI助手加一个功能，而是把一堆能大幅提升AI干活效率的能力打包成可插拔的“技能包”。如果你玩过Claude Code、Cursor这类AI编程工具，一定遇到过这种场景：想让AI帮你写测试用例，它写完是写了，但风格和项目里已有的用例对不上；想让它按团队规范生成提交信息，每次都要把规范贴一遍。superpowers解决的问题就是：把这类反复交代的“背景知识”和“操作流程”固化下来，做成一个叫skill的东西，需要的时候直接引入，AI瞬间“觉醒”对应领域的经验。

这篇文章适合正在重度使用AI编程助手、想进一步压榨AI效率的开发者，也适合刚接触“AI技能化”这个概念、想系统了解怎么给智能体装“外挂”的人。我会从技能的原理、安装、现成技能清单、自定义写法到常见坑位，完整走一遍，最后附上我实际踩过的问题和排查思路。

1. 为什么智能体需要一套“技能系统”

1.1 裸用AI助手最大的痛点：没有领域上下文

先聊聊我自己的体会。早期用AI写代码，我大概要花十分钟在提示词里交代“我们这个项目是Go写的”“数据库用的PostgreSQL”“错误处理统一返回JSON”“不要动公共接口”……交代完这些，AI确实能干活了，但换个任务，这些上下文又得重新说一遍。更麻烦的是，同一个项目的不同AI会话之间是相互隔离的，这次教会的知识，下次还得重教。

这就是裸用AI助手的核心痛点：大模型本身有很强的通用能力，但它没有你项目的领域知识，也没有你团队的工程规范。提示词工程能缓解一部分问题，但提示词本身是“一次性”的，没法像代码一样复用、维护、版本管理。你会发现，真正拖慢效率的不是AI写代码的速度，而是你“教会”AI的时间。

1.2 技能的本质：把“喂给AI的边际知识”固化下来

superpowers这类工具的思路很直接：把所有你希望AI具备的特定领域能力，拆成一个一个独立的“技能”文件或目录。每个技能包含两部分：一部分是给模型看的说明性内容（比如工作流程、注意事项、代码风格、领域知识），另一部分是可选的可执行逻辑（比如解析文件、调用接口、运行测试的脚本）。

说得直白一点，传统提示词工程像是“口传心授”，每次靠你现场描述；而技能像“武功秘籍”，把招式写成册子，AI需要用的时候直接翻到对应章节。你不需要每次说“你要注意项目规范”，只要引入teamwork这个技能，AI自动就知道要按规范来。

1.3 对比三要素：可复用、可组合、可分享

为什么说这是一种架构上的升级，而不是换了个提示词模板？核心差异有三个：

• 可复用：一次写好的技能，可以在所有会话、所有项目中反复使用，不用每次复制粘贴。
• 可组合：一个项目可以同时引入多个技能。比如写后端接口时，同时挂上“项目规范技能”“数据库建模技能”“测试用例生成技能”，AI就会综合这几方面的知识来输出结果。
• 可分享：技能以文件形式存在，天然适合放进Git仓库。团队里有人写了一个高质量技能，其他人拉下来就能用，技能本身变成了团队资产。

这三个特性加在一起，意味着你不再和AI“单次对话”，而是在给AI构建一套长期的知识体系。我自己的体验是，引入技能系统后，AI第一次输出的可用率显著提升，返工率至少降了一半。

2. 安装与基础配置：把superpowers跑起来

2.1 环境准备：先确认你的AI工具版本

先说前提。superpowers是给AI编程工具做技能扩展的框架，所以你得先有一个支持技能机制或至少支持自定义指令的AI Coding工具（比如较新版本的Claude Code、Continue等）。不同工具的加载方式略有差异，但总体思路一致：把技能文件放到指定目录，然后通过命令或配置引入。

我以我惯用的环境为例，共分三步。第一步是确认运行环境：需要Node.js 18+，npm能正常用。这个项目本质上是一个命令行工具加一组约定目录结构，对系统依赖很少，macOS、Linux、Windows的WSL环境都能跑。

2.2 安装命令与目录结构

安装方式通常是拉取仓库然后链接全局命令，或者直接用包管理器安装。以仓库安装为例：

git clone https://github.com/你的源/superpowers.git cd superpowers npm install npm link

装完以后，执行superpowers --version能看到版本号，说明安装成功。

然后初始化技能目录：

superpowers init

这条命令会在你当前项目下生成一个.superpowers目录，里面按类型分了几个子目录。

.superpowers/ ├── skills/ # 存放技能包 │ ├── code-review/ # 代码审查技能 │ ├── test-writing/ # 测试编写技能 │ └── ... ├── config.json # 技能开关配置 └── logs/ # 运行日志

提示：建议把.superpowers目录纳入Git版本管理，但把logs/加进.gitignore，日志文件很容易膨胀，没必要入库。

2.3 引入技能的两种方式

使用技能有两种路径，对应两种使用习惯。

第一种是全局引入：用superpowers use命令把技能注册到当前AI会话的上下文中。比如想引入代码审查技能：

superpowers use code-review

这条命令会把code-review技能的内容注入到AI的system prompt里，之后这个会话里的AI就有了代码审查者的角色意识。全局引入适合你明确知道接下来要做哪类任务的情况。

第二种是自动匹配：很多技能带有关键词描述，当你的指令中提到特定任务关键词时，AI会自动联想并加载对应技能。比如你写“帮我审查一下这个PR”，AI如果检测到code-review技能声明了相关触发词，就会自动按技能里的流程工作。这种方式用起来最省心，但依赖技能定义时的触发词写得好不好。我个人的建议是，关键任务用显式引入，日常小任务靠自动匹配，两者搭配效率最高。

2.4 验证安装是否成功

装完别急着用，先跑一次自检：

superpowers list

这个命令会列出当前已加载的所有技能。如果是首次安装，看到的应该是空的或只有内置的几个基础技能。接着用一个简单的技能做验证，比如：

superpowers test hello-world

如果终端输出了一组测试通过的日志，说明整个链路是通的——技能目录能被找到、注入逻辑能执行、内容能正确传给AI。这一步排障很重要，很多新手上来就写自定义技能，结果发现AI根本没按技能工作，最后排查了半天发现是目录路径配错了。

3. 有哪些现成技能：常用技能包清单与能力拆解

3.1 技能目录里的“常备军”

superpowers默认提供了一批针对开发场景的高频技能，我按用途分成四类，分别是：代码类、文档类、分析类和流程类。

代码类是我用得最多的。code-review技能会给AI一套审查标准：先读改动、再找逻辑漏洞、最后按严重程度输出问题列表。test-writing技能则要求AI先理解被测函数的所有分支，再按边界值和异常路径生成用例，而不是简单生成几个Happy Path就交差。还有一个refactoring技能，用于老代码改造，它内置了“小步重构、每步保持测试绿”的原则。

文档类里，readme-generator负责写项目说明文档，它会先扫描项目结构、读关键文件，再按“项目简介、快速开始、API说明、常见问题”的结构输出。changelog技能可以从Git提交记录中整理变更日志，并且会自动过滤掉“fix typo”这类噪音提交。

分析类技能偏向于辅助决策。dependency-audit会检查依赖版本并给出升级建议，它会对比主版本间的破坏性变更，而不是简单告诉你“有更新”。perf-analysis技能用于代码性能分析，它能让AI以性能工程师视角审视热点代码，给出具体的优化建议。

流程类技能解决的是“怎么干活”的问题。比如git-workflow技能封装了一整套Git协作流程：先同步主干、再开分支、提交信息按Conventional Commits规范、最后发起PR。我引入这个技能之后，团队的新人再也没交过乱七八糟的提交信息。

3.2 技能的核心文件结构

为什么一个技能能给AI注入“角色感”？因为每个技能目录下都有一个SKILL.md文件，这个文件就是整个技能的“大脑”。我拆开看一个典型技能的结构：

code-review/ ├── SKILL.md # 技能说明书，告诉AI这个技能是什么、怎么用 ├── rules.md # 审查规则集，按严重程度分级 ├── templates/ │ └── review.md # 审查报告输出模板 └── scripts/ └── diff-stats.sh # 辅助脚本，统计改动范围

SKILL.md里最关键的几个字段包括：技能名称和一句话描述、适用场景、触发关键词、工作流程步骤、以及引用其他文件的指令。

注意：SKILL.md的编写质量直接决定AI会不会真的按这个技能干活。写得越具体，AI的执行越稳定；写得笼统，AI大概率会忽略它。我见过不少人的技能文件只有一句“你是代码审查专家”，这种基本等于没写。

3.3 技能文件里的“角色设定”怎么写

拿一个SKILL.md的实际片段来说明，写清楚比写长更重要：

# Skill: code-review ## Description 以资深代码审查者身份审查变更代码，发现逻辑漏洞、安全隐患和风格问题。 ## Trigger 当用户说“审查代码”“review PR”“帮我看看这段代码”时，自动激活本技能。 ## Workflow 1. 先用 `git diff` 获取变更内容，明确改动范围。 2. 逐个文件阅读，重点关注错误处理、边界条件和资源释放。 3. 按 Severity（Critical/Major/Minor）输出问题清单。 4. 每个问题必须给出：问题位置、原因、修改建议。 5. 最后用模板 `templates/review.md` 输出完整报告。 ## Rules - 只审查当前变更，不做全量代码评审。 - 不空泛地说“代码质量有待提升”，每个结论必须有据可依。 - 如果发现问题，直接给出修复后的代码片段。

关键就在Workflow和Rules这两块。Workflow告诉AI“先做什么、后做什么、最终产出什么”，Rules用来约束AI的行为边界，避免它跑偏。技能之所以比提示词稳定，就是因为它把工作流拆成了可验证的步骤。

4. 具体使用实战：技能在不同场景下怎么发挥价值

4.1 场景一：用代码审查技能做PR自检

我在实际项目里用得最多的就是代码审查。以前提PR之前，自己总得先过一遍代码，但人看自己写的东西容易有惯性盲区。现在我的流程是：

superpowers use code-review

然后让AI审查当前的改动分支。它会先调用git diff获取变更列表，再按技能里定义的规则逐条核对。有一次我故意写了一个多余的空指针判断，AI直接标了“Major：冗余判断掩盖了上游数据校验缺失，建议在入口统一校验”。这个结论质量已经接近我团队里资深同事的评审水准了。

这里必须提醒一点：技能内置的代码审查不是万能的，它对跨文件的数据流分析仍然较弱。我的使用原则是：用它做第一轮自检，抓逻辑漏洞和低级错误，细节的架构问题还得靠人工把关。

4.2 场景二：测试生成技能的实战效果

团队一直要求新代码必须有单测，但让AI直接写测试，默认效果经常是“对着快乐路径一顿输出”。引入test-writing技能以后就不一样了。这个技能要求AI先列出被测函数的所有分支，包括正常分支、异常分支、边界值、空值、超大值，然后一个分支一个分支生成用例。

实际跑下来，测试覆盖率从原来的65%提到了89%。更重要的是，AI会主动生成边界测试，比如数组长度为0、字符串超大、接口超时这类情况，这些恰恰是手动写测试时最容易遗漏的。

4.3 场景三：自定义工作流技能替代人工检查清单

除了官方技能，superpowers给人最大的想象力在于：你可以把自己平时按部就班做的事，固化成技能。举个我的例子，每次发布版本之前，我都要手动检查一堆事项，现在写成了一个release-check技能：

• 检查版本号是否正确递增。
• 检查CHANGELOG.md是否更新。
• 检查依赖锁文件是否与package.json同步。
• 检查CI配置是否改动过。
• 输出检查报告，标明每项的通过状态。

每次发版前，我只需要敲一句“执行发布检查”，AI就按流程跑一遍。这个技能把团队里的隐性知识显性化了，任何人接手发版工作都不会再漏步骤。

4.4 技能组合：多技能协同才是终极玩法

单个技能解决单点问题，组合起来才能发挥指数级效果。我现在做新功能的标准流程是：先用spec-writer技能写技术方案，然后挂上code-review技能边写边审，写完用test-writing生成单测，最后用changelog技能更新变更记录。

技能之间基本没有冲突，因为每个技能只负责自己的环节，输出结果刚好是下一个技能的输入。这种流水线式的配合，让AI从“单点工具”变成了“完整工作流执行者”，这是我在引入superpowers之前完全没体验过的。

5. 自定义技能编写：从零开始做一个属于自己的技能

5.1 确定技能边界：别把技能写成万能药

技能最容易犯的错是贪多。新手上来就想写一个“全栈开发技能”，结果里面既包含代码规范、又包含部署流程、还包含数据库设计……最后AI什么都吸收一点，什么都不精。我建议一个技能只解决一个明确问题，比如“生成符合团队规范的提交信息”或“检查Dockerfile的安全性”。

技能边界划得越清楚，AI执行越稳定。如果一个技能里有超过七八条规则，就应该考虑拆分成两个。

5.2 动手写一个最小技能

下面我带大家走一遍完整的创建流程，目标技能功能是“为项目生成规范的README”。

第一步，创建目录和文件：

mkdir -p .superpowers/skills/readme-gen touch .superpowers/skills/readme-gen/SKILL.md

第二步，编写SKILL.md：

# Skill: readme-gen ## Description 根据项目代码自动生成结构化README文档。 ## Trigger 当用户说“写README”“生成项目文档”“补充readme”时，自动激活。 ## Workflow 1. 扫描项目根目录，读取 `package.json` 或 `pyproject.toml` 等配置文件。 2. 获取项目名称、依赖、脚本命令等元信息。 3. 遍历 `src/` 或 `lib/` 目录，整理公开的API或模块。 4. 按固定模板输出README，包括：项目简介、功能特性、安装方式、快速开始、API列表、常见问题。 5. 若原有README存在，则在原基础上补充缺失章节，不重复生成。 ## Rules - 所有命令示例必须可执行，不能凭空编造。 - 输出语言与项目注释语言保持一致。 - 遇到无法确定的内容，标注“待补充”而不是猜测。

第三步，测试技能是否生效：

superpowers use readme-gen

然后在AI对话框输入“帮这个项目写一份README”。此时AI应该按Workflow里的步骤，先读配置文件再生成文档，而不是直接凭感觉写。我把这一步叫“有流程的生成”，它和裸用的最大区别在于，输出的内容结构和信息密度是受控的。

5.3 给技能加上辅助脚本

有些技能光靠说明书不够，还需要实际执行逻辑。比如dependency-audit要读取依赖锁定文件做版本对比，这不是靠大模型“想象”能完成的，它需要脚本实际跑一遍。

技能目录里可以放scripts/子目录，在SKILL.md里用相对路径引用脚本。AI可以执行脚本并把输出结果拿来做分析。这相当于给技能装上了“手”，能真正操作环境，而不只是“动嘴”。

注意：给技能配脚本时，务必在SKILL.md里写明脚本的输入输出格式和运行环境，否则AI调用时不知道传什么参数，很容易报错。

5.4 调试自定义技能的正确姿势

写完技能不代表万事大吉。我自己调试技能时有一套标准动作：

• 先检查SKILL.md语法和引用路径，确认引用的每个文件都存在。
• 然后跑一次superpowers list，看技能是否被正确加载。
• 再用一个最小化指令测试，比如只触发核心Workflow，观察AI是否按步骤执行。
• 最后逐步增加任务复杂度，直到覆盖技能的完整流程。

如果AI执行结果偏离预期，大部分时候不是模型问题，而是你的技能描述有歧义。把模糊的表述改具体，再测一遍，基本能解决。

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

6.1 五个高频问题速查表

我把自己和身边人用过superpowers之后踩过的坑整理了一下，做成一个速查表，大家按图索骥：

6.2 排查思路：从日志找线索

遇到问题别靠猜。superpowers会记录每次技能加载的日志，在.superpowers/logs/目录下。当技能没有按预期生效时，第一件事是打开对应时间段的日志，看技能文件是否被成功解析、注入的指令是否包含SKILL.md的内容。

我能找到的排查路径是：先确认技能被list识别，再确认日志里注入了内容，最后才怀疑是模型执行的问题。按这个顺序排查，90%的问题都能定位到前面两步。

6.3 我踩过的三个坑，你们别再踩了

第一个坑是技能目录层级放错了。官方示例里技能是skills/技能名/SKILL.md，我之前图省事直接放在skills/根目录下，结果怎么加载都不生效。查了半天日志才发现是路径不对。

第二个坑是触发词写得太泛。我给一个技能写了“代码”作为触发词，结果AI看到任何和代码有关的任务都会尝试激活这个技能，反而干扰了正常对话。后来我把触发词改成更精确的短语，比如“按XX规范生成代码”，问题立刻消失。

第三个坑是技能规则太多导致AI“选择性遗忘”。早期我写技能总想把所有细节都写进去，一个SKILL.md长到两千多字，结果AI执行时经常忽略后半部分内容。后来我把长技能拆成“主技能+子技能”，主技能负责触发和工作流，子技能承载具体规则，执行稳定性明显提升了。

6.4 技能维护：定期清理和归档

技能不是写完就完事了，它们需要维护。我习惯每个月过一遍技能目录，把不用的技能归档到skills_archive/，把使用中产生的新规则合并回技能文件。这个过程和代码重构很相似，目的都是保持技能库的健康度。

一个常见判断标准是：如果一个技能你连续两周没有触发过，就该考虑是删除、归档还是调整触发词。技能库不是越壮越好，保留的都是高频有用的，才不会在加载时拖慢上下文、稀释有效指令。

最后再分享一点我自己的体会

用superpowers这段时间，我最深的感受是：它真正改变的不是AI的能力，而是你组织知识的方式。以前我积累的工程经验散落在笔记、文档和聊天记录里，现在它们变成了结构化的技能文件，跟着项目走，团队里每个人都能用。这种“把个人经验沉淀成团队资产”的过程，带来的效率提升远超多写几段提示词。

如果你刚上手，我的建议是先别急着造轮子。装好工具，把官方技能和社区技能跑一遍，熟悉技能的工作机制，再动手写自己的第一个技能。写的时候认准“一个技能解决一个问题”，从简单的开始，比如版本发布检查、提交信息生成这种流程固定、规则明确的场景，最容易获得成就感。等你熟练了，自然会琢磨出更多适合自己工作流的技能组合。

说到底，superpowers告诉我的道理其实很朴素：AI再强，也需要一套体系来组织和发挥这些能力。把知识固化、流程化、可复用，这是工具带来的最大价值，也是我们这些天天和AI打交道的人最值得投入的方向。