企业官网建设流程全解析

其实最开始我对“给AI装技能”这件事是有点不屑的。我日常用的是Claude这类编码助手，平时写代码、改Bug、做Code Review都已经很顺手，为什么要额外折腾一套叫Superpowers的东西？直到有段时间我连续被低效交互折磨：每次开新会话都要重新交代一遍项目背景、编码规范、测试命令；让它去查个官方文档，它要么凭记忆瞎编，要么告诉我没法访问外部网页；明明上个月刚写好的自动化脚本，这个月换个项目目录就完全想不起来。这种“每次从零开始”的感觉，让我意识到问题不在AI的能力，而在于我没有给它一套可复用的“工作记忆”。Superpowers解决的正是在于把那些高频使用的技能、流程和工作流，固化成AI随时可以调用的模块，一次安装、到处复用。

这篇文章会把我的完整实操记录下来：装前准备、核心概念、开箱技能盘点、一个Skill从创建到调用的全流程，以及我踩过的几个真实坑。适合所有用AI辅助开发、但已经厌倦反复重复提示词的开发者。

1. 先从“为什么需要给AI装技能”说起

1.1 AI助手不是能力不够，而是“记忆”太差

我在团队里做过一个实验：让Claude分别在新会话和旧会话里完成同一个任务——写一个带分页和搜索过滤的Python接口。旧会话里它记得我们约定好的项目结构、命名规范、错误处理方式，写得又快又准；新会话里它虽然也能写，但总会问一堆基础问题，甚至默认用上了跟现有代码风格完全不搭的写法。这个差异说明，AI的核心瓶颈往往不是模型本身，而是上下文和流程的可复用性。

Superpowers这一类“技能框架”解决的问题，就是把这个“可复用性”从会话中抽出来，变成一个一个放在磁盘上的技能包。每个技能包含清晰的触发条件、依赖工具、执行步骤，AI识别到对应场景后可以直接加载并执行。你不需要再把半页纸的Prompt复制粘贴进去，只要告诉它“用某某技能处理”就行。

1.2 Superpowers的核心思路：把技能变成文件

如果只记一句话，那就是：Superpowers把技能变成文件，把工作流变成目录结构。它的安装和使用逻辑，跟给编辑器装插件很像。你在自己的用户目录或项目目录下建好技能文件夹，里面放一个Markdown形式的技能说明书，再加上若干可供AI调用的脚本或工具，剩下的事全部交给框架和AI来协调。

这带来一个意外的好处：技能可以跟着项目走，也可以跟着人走。我自己的习惯是，把通用的技能放在全局目录，把跟具体项目强相关的技能放在项目根目录的.superpowers文件夹里，项目成员拉下来代码之后，技能也跟着一起复制过去了。

1.3 它跟一份普通Prompt到底差在哪

很多人会觉得“那我不就是把Prompt存成文件嘛，有什么区别？”区别大了。普通的Prompt是“一次性输入”，而一个结构良好的Skill包含的是四个层次的内容：

• 触发场景：明确说明这个技能在什么情况下应该被自动启动，在什么情况下应该拒绝执行。
• 前置条件：列出执行前需要具备的环境、工具、依赖，AI会主动检测。
• 执行步骤：把任务拆成可验证的中间步骤，每一步都有产出和检查点。
• 脚本与工具：技能可以直接调用预设的Shell脚本、Python脚本，而不只是生成文本。

底层逻辑是：Prompt是给AI看的“建议”，Skill是给AI看的“作业指导书加工具箱”。所以同样一个“写单元测试”的需求，用Prompt让它写，它可能自由发挥；用技能让它写，它会先检查测试框架是否安装、再按项目的测试规范生成、最后自己跑一遍测试并汇报结果。

2. 安装前的准备：环境、版本与网络条件

2.1 环境要求与版本检查

Superpowers依赖Node.js运行时和对应的AI编程助手CLI工具。安装前建议先检查自己的基础环境，避免装到一半才发现版本不对。我现在用的组合是：Node.js 20.x + Claude Code（Bash环境），这个组合下所有功能都能正常跑。

打开终端先敲两行命令确认环境状态：

node -v # v20.11.0（如果低于18，建议先升级） npm -v # 10.2.4

然后确认你的AI编程助手CLI已经登录并能正常对话。不同AI工具的命令略有差别，但思路一样：先让CLI能跑起来，再谈装技能框架。我在macOS的终端里操作，Windows的PowerShell用户需要注意后面会提到的路径差异。

2.2 安装命令与网络注意事项

确认环境无误后，安装过程本身非常快。不同版本的Superpowers安装命令略有不同，我这边用的方式是通过npm全局安装启动器：

npm install -g superpowers-cli

装完之后，在AI编程助手内部再执行初始化命令，让它自动创建技能目录和默认技能包：

superpowers init

这里有一个非常关键的网络问题。npm源、CLI下载依赖包、以及AI工具访问外部文档，都需要一个相对稳定的网络环境。有些同学会在这里卡很久，表现为npm install转几圈就超时，或者init之后技能老是下载不完整。处理方法有两个方向：一是把npm源切到国内镜像（npm config set registry https://registry.npmmirror.com），二是给AI工具配置好系统代理。我不展开讲代理细节，只想说一句：如果init阶段频繁失败，大概率不是工具问题，而是依赖下载被中断，换一个网络环境再试往往就通了。

2.3 装好后先跑一次验证

安装完成后别急着写技能，先跑一遍自带的健康检查。Superpowers一般会提供技能列表命令，你可以在AI对话窗口里输入类似这样的指令：

显示所有已安装技能

正常的话，你会看到一组默认技能，比如我这边默认就带着Web搜索、代码审查、Git工作流这几个基础包。如果列表是空的，或者提示找不到技能目录，那就需要检查一下初始化路径是否正确——这个坑我后面专门讲。

验证还有一招：直接让AI“用Web搜索技能查一下某个框架的最新版本”。如果它能正确调起技能、访问页面并返回带引用的结论，说明整条链路已经通了。

3. 核心概念：Skill、Command和Agent的关系

3.1 三种对象的定位差异

刚开始接触Superpowers的人容易被三个概念绕晕：Skill、Command和Agent。我花了不少时间才把它们彻底分清楚，这里直接给出我的理解：

• Command：最简单的一类，相当于一个“快捷指令”。它是一段预设好的Prompt，AI看到 @命令名 就会按预填内容执行。适合固定话术，比如“帮我把代码格式化成项目规范”。
• Skill：可执行的工作流单元。除了Prompt，还包含前置条件、环境依赖、可调用脚本，它会有真正的“操作”，比如读写文件、运行测试、搜索互联网。
• Agent：由多个Skill组合成的角色化执行体。它更像一个虚拟成员，比如“负责做技术调研的Agent”，内部串联了搜索、阅读文档、写摘要、给建议等多个技能。

日常开发中用到最多的还是Skill。Command适合一次性固定输入，Agent适合复杂的多阶段任务，而Skill是中间那个“既有弹性又能落地”的层面，所以我的实践建议是：优先从Skill入手，等积累够了再组装自己的Agent。

3.2 一个标准Skill的目录与文件组织

每个Skill本质上是磁盘上的一个文件夹，标准结构长这样：

my-skill/ ├── SKILL.md # 技能说明书，AI首先读取这个文件 ├── scripts/ # 可执行脚本，会被AI调用 │ └── check-env.sh └── assets/ # 附带资源，比如模板、配置样例

我最常忽略的是SKILL.md的命名。它必须全大写且精确为SKILL.md，写成skill.md或Skill.md都可能让AI识别不到。这是一个非常容易踩的细节，我有个同事把文件名写成小写，排查了半天才发现问题出在这里。

3.3 SKILL.md的frontmatter与正文写作

SKILL.md是技能的灵魂。它的开头是一段YAML格式的元信息（也就是frontmatter），我通常会这样写：

--- name: web_search version: 1.0.0 description: 搜索指定关键词并返回带来源的摘要结果，用于技术调研和资料核实。 triggers: - 搜索 - 查一下 - 找出最新资料 - find the latest allowed_tools: - shell - python ---

triggers很关键。AI会拿用户输入跟这里的词条做匹配，命中后优先加载这个技能。你写得不全，就会出现“明明装了技能，AI却完全没用它”的情况。我后期把所有自定义技能的triggers都重新过了一遍，每个至少配了5个不同表达。

正文部分我建议用清晰的步骤结构。AI读Markdown的效率很高，按顺序列出步骤它基本能忠实执行。一个常见教训是：不要在正文里写太多模棱两可的形容词（比如“合理”“高质量”），而要写可验证的标准（比如“测试覆盖率不低于80%”“输出必须包含引用链接”）。AI对量化目标的执行力，远比对模糊目标的执行力强得多。

4. 开箱即用的Skills盘点与应用场景

4.1 我把技能分成四个门类

安装Superpowers并初始化之后，系统会自带一批技能。不同版本的默认包有差异，但大体上会覆盖我常用到的几个方面。我个人习惯于把技能分成四个门类，方便按场景取用：

这个分类不是官方分类，是我自己用着方便做的“知识管理”。你完全可以按项目需要调整，重点在于知道默认技能池里有哪些货，别临到用时才发现“原来它还能干这个”。

4.2 高频技能详解

我用得最多的几个技能，值得单独拿出来说说。

Web搜索：这是解决“AI瞎编”的利器。过去让Claude回答“某个库最新版本是多少”，它可能凭训练数据猜一个，而现在它会先调起Web搜索技能，打开搜索结果页面，再返回带参考来源的答案。我实测过精度提升非常明显，至少不会再把两年前的老版本当成最新版了。

代码审查：执行技能后，AI会读取目标代码文件，先检查语法和风格问题，再做逻辑层面的潜在Bug分析，最后会核对项目既有的测试覆盖情况。最妙的是它会输出一份“严重级别排序”的审查报告，把高危问题列在最前面。我把这个技能接入到了提交前检查流程，配合Githook一起使用，效果很稳定。

Git工作流：这个技能解决的是“规范提交信息”的问题。它会先跑git diff和git status查看变更内容，再结合项目约定的提交信息规范，生成符合格式的commit message。我不用再费劲想动词前缀，也不用担心风格不统一。

项目脚手架：输入一个项目描述，技能会自动创建目录结构、生成初始代码文件、配置依赖清单，甚至安装依赖并启动开发服务器。我最近用它搭了三个内部工具的前端项目，整个过程从半小时缩短到五分钟。

4.3 按场景选技能的搭配建议

单个技能好理解，但真正提升效率的是“技能组合拳”。我自己会按项目阶段做搭配：

• 新建项目：项目脚手架 + Git工作流 + README生成。
• 日常开发：Web搜索 + 代码审查 + 单元测试生成。
• 排查线上问题：日志排查 + 数据库Schema分析 + 性能基线检查。
• 提交发布前：代码审查 + Git工作流 + 变更日志生成。

当你发现自己把多个技能轮流调用时，就可以考虑定制一个组合Agent了。这个进阶玩法等你自己跑顺手之后再去尝试，初期不建议一上来就搞复杂的Agent编排。

5. 实操：让一个Skill从安装到调用走完整链路

5.1 第一步：看板与技能列表

先学会“看货”。在AI对话窗口里直接输入查看技能列表的指令，每次我拿到新环境，第一件事就是先看默认技能池。界面会返回一个带说明的技能清单，每个技能的名称、描述、触发方式一目了然。

看到某个技能想要试用，不需要额外安装，直接在对话里给出触发词即可。比如技能描述里写了“搜索”，你就正常说“用搜索技能查一下Vite的最新版本”，AI会自动匹配并执行。整个过程不需要背命令，自然语言就是调用接口。

5.2 第二步：写一个属于自己的Skill

看懂结构之后，真正好玩的开始——自己写一个。我建议从解决自己最痛的场景入手。我写的第一个自定义技能是“生成周报”，因为每周写周报实在太烦了。

先在项目的.superpowers/skills目录下新建一个weekly-report文件夹，然后创建SKILL.md：

--- name: weekly_report description: 根据本周的Git提交记录和TODO清单，生成一份结构化周报。 triggers: - 周报 - weekly report - 总结本周工作 --- # 步骤 1. 运行 `git log --since="7 days ago" --pretty=format:"%h %s (%an)"` 获取本周提交记录。 2. 检查项目根目录是否存在 `TODO.md`，如有则读取未完成项。 3. 按照"本周完成 / 本周进展 / 下周计划 / 风险与阻塞"四个部分组织内容。 4. 输出时保留具体数据（提交次数、解决的问题、模块名称），不要写泛泛而谈的套话。

第一版跑起来之后，我发现它有个问题：只会拿git log的数据，但很多工作是不体现在commit里的，比如开会、评审、排查问题。于是我在第二步又加了一个输入参数，让它允许我补充非代码类的工作内容。迭代后的技能明显更实用了。

5.3 第三步：在对话里调用并验收效果

写完之后不用重启任何东西，直接在对话里说“生成这周的周报”。AI会自动匹配到weekly_report技能，然后按步骤执行。当时它跑出来的周报让我很惊喜，不仅准确提取了commit信息，还把“升级了构建脚本来减少三分之一的打包耗时”这种我早就忘记的细节重新挖掘出来了。

验收技能有一个笨办法：故意给一个不完整的需求，看它是否会主动走前置检查。比如我会说“帮我生成昨天到今天的周报”，正常应有技能启动，并指出可用数据范围有限，会给出建议比如扩大时间范围。如果它什么都没做就直接编内容，说明技能的约束没有生效，需要回头检查SKILL.md里的步骤描述是否足够具体。

5.4 第四步：迭代与版本管理

技能不是一次写好的，我自己每个技能平均改了三遍。建议把技能目录纳入Git版本管理，改动之后提交，方便回滚。对技能做版本更新时，注意同步更新SKILL.md里的version字段，这样即时多人在同一台机器上操作，也知道当前跑的是哪个版本。

我一度偷懒省略了这一步，结果后来出了个诡异问题——同一份技能，我本地跑的结果和同事跑的结果完全不同。最后发现是我改了SKILL.md但没更新版本号，我这边已经是v2逻辑，同事缓存里还是v1的步骤。从那以后，我更新技能的固定动作就是：改内容 + 改版本号 + 提交Git。

6. 排错实录与避坑经验

6.1 安装在用户目录，却在项目里找不到技能

这是我第一次安装时遇到的第一个坑。superpowers init默认把全局技能装到了~/.superpowers目录，而我的项目自己在本地建了一个.superpowers文件夹，两边内容不一致，导致项目里能看到一部分技能、又缺失一部分技能，特困惑。

后来我才想明白，Superpowers在读取技能时是有优先级的：项目目录的.superpowers高于用户级目录的~/.superpowers。同名技能会以项目目录为准。这个机制本身合理，但它意味着你在全局更新了技能，项目里如果存在同名文件，跑的还是旧版本。我的建议是：做一个明确约定——全局目录放通用技能，项目目录放项目专属技能，同名覆盖要有意识，不要靠巧合。

6.2 Skill一直不生效，问题出在缓存

有一次我改了一个技能的前置条件，明明文件改对了，但每次让它执行还是走旧逻辑。一开始怀疑是文件名问题，检查了路径也对，最后才想到缓存。Superpowers为了提升加载速度，会有技能索引缓存，修改SKILL.md后不一定会立刻重建索引。

解决方法很简单，两步：先看有没有类似的刷新命令（不同版本叫法不同，常见是/skills refresh），如果没有就重启AI会话。我当时重启会话立即就好了。后来问了下群里的朋友，他们也遇到过这个情况，甚至有人把一级缓存和二级缓存都列出来了，大意是“改了技能就下意识刷新，别浪费十分钟在这上面”。现在我已经把“刷新技能索引”变成了肌肉记忆。

6.3 权限、路径与Node版本带来的连锁问题

如果技能内部要调用Shell脚本，记得检查执行权限。我写过一个技能，每次运行都报“Permission denied”，明明手动执行脚本没问题。排查后发现是文件没有chmod +x权限位，AI调起脚本时以独立进程运行，不继承我终端会话的便利条件，权限检查比人严格。

还有一个很容易踩的是路径问题。技能脚本里的相对路径，是相对当前工作目录，而不是相对SKILL.md所在目录。这意味着同一个技能，在项目根目录运行和在子目录运行，表现可能完全不同。解决方法是：涉及文件读写的地方，一律用绝对路径或基于项目根目录的路径，不要偷懒写相对路径。

Node版本的问题则更隐蔽。我之前在Node 18环境跑得正常，升级到Node 22之后某个技能开始报“ERR_STREAM_WRITE_AFTER_END”，排查发现是技能内嵌的一个依赖包用了旧版本的stream API。你不需要太理解底层细节，记住一件事就行：当技能突然不工作，而且更新缓存也无效，检查Node版本是否被动更新了。

6.4 关于安全和边界的一点提醒

技能框架给了AI调用Shell、读写文件、访问网络的能力，这个能力是一把双刃剑。我强烈建议你在使用第三方Skill时，先通读一下对方的SKILL.md和里面脚本代码，尤其是脚本部分。注意看几点：脚本是否会往外部服务器发送数据？是否包含可疑的下载加执行链？是否有超出描述范围的敏感操作？

我的安全底线是：自己写的技能也不给最高权限。比如我不会在技能里写入rm -rf类的命令，即使是在清理目录，也会先列出来确认。AI对命令的理解是字面量的，它不知道“这个目录真的很重要”，在技能出错时，一个有保护意识的脚本能避免很多灾难。

我在实践中的最大体会是，Superpowers这类工具，真正的价值不是“装了就变强”，而是逼着你把工作方式想清楚。每写一个技能，都需要把隐性经验显性化：这个任务到底有哪些前置条件？执行步骤能不能拆成机器可理解的指令？质量标准怎么量化？这套思考过程本身就是一种效率提升。等你积累了十几个自己的技能，再回头看那些“每次都从零开始”的日子，你会发现自己的AI助手终于有点像资深员工的干活方式了。