企业官网建设流程全解析

大概一年前我刚开始接触superpowers这个名字时，以为又是一个营销味很重的效率课程。真正把仓库拉下来、把 skills 目录接进 Claude Code 之后，我才意识到这是给 AI 编程助手配了一套可复用技能包体系——用 Markdown 定义一个技能，助手就能在对话里随取随用，不需要每次把长篇大论的 Prompt 重新敲一遍。这篇文章我就围绕「superpowers 具体怎么用、有哪些 skills、怎么引入这些技能、以及安装过程中容易翻车的点」展开，把我从零搭到稳定使用的完整过程写下来，给想折腾这套东西的人铺条路。

我默认你和我一样，日常主力是 Claude Code / Cursor 这类支持 skills 机制的 AI 编码助手。如果你用的是其他工具，思路也能照搬，只是技能加载的目录约定和触发语法会有差异。先说清楚 big picture：superpowers 不是一个帮你写代码的插件，而是一套「助手能力扩展框架」。它提供了一批写好的技能文件，也允许你自己往仓库里塞新技能。装好之后，助手不仅会用你的对话历史来理解问题，还会根据当前任务自动去读对应的技能定义，再按定义里的步骤执行。打个不严谨的比方：普通 Prompt 像你每次进厨房都重新背一遍菜谱，superpowers 则是把菜谱做成抽屉里的卡片，抽出来就能照着做。

1. 为什么需要「技能包」而不是更长的 Prompt

很多人刚开始会有个疑惑：我直接把流程写在 Prompt 里不就行了吗？为什么还要搞一套 skills 体系？

关键在于上下文占用和复用成本。一段精细化的流程说明，动辄几百上千字。如果你同时需要设计拆解、代码审查、文件合并、SVG 生成这几类任务，全塞进系统 Prompt 里，还没开始干活，上下文窗口已经被吃掉一大块，留给真正任务的生成空间就少了。而 skills 是按需加载的：助手先根据对话内容判断「这个用户现在想干的事情是不是匹配某个技能」，匹配才把对应的技能定义读进来。平时技能文件安静地躺在仓库里，不占任何上下文资源。

第二点是稳定性和可迭代性。写Prompt的人都有体会，同一个流程今天写和明天写，细节常常不一致；多轮对话之后你甚至会忘了自己之前给过什么要求。技能文件把流程固定成一个版本化的 Markdown 文档，改一处，全项目所有对话都能用到最新版。你不需要重新解释「上次那个要求是……」，也不用担心不同会话里执行标准漂移。

第三点是团队协作。我会在后面专门讲怎么自定义技能，这里先说一句：当你的技能文件存放在 git 仓库里，团队里每个人git pull就能同步同一套工作流定义。新人上手时不需要你口口相传各种 do's and don'ts，AI 助手自己就会按技能定义执行。这套东西本质上是把「经验」从人脑里搬进了代码仓库。

我个人的体会是，project 里同时存在的技能数量到一定程度后，这种「定义与调用分离」的设计会带来质变。前期你可能只觉得省了一点打字量，到后期会发现整个工作方式都变了，你会开始思考「这个流程能不能也封装成一个技能」，这就进入了正向迭代状态。

2. 从零安装 superpowers：初始化命令与环境检查

安装这件事看似就一条命令，实际跟你的终端环境、Node 版本、以及助手工具的配置方式都有关系。我先给一条完整路线，再标出我踩过最深的几个坑。

2.1 前置环境：Node.js、git、以及支持 skills 的助手工具

superpowers 本体是一个以 Markdown 文件为主的技能仓库，但它带的初始化脚本由 Node.js 编写，所以你机器上要有一个能跑 Node 的环境。建议 Node 版本不低于 18，太老的版本跑 bootstrap 脚本时会出现一些莫名的语法报错。

助手工具方面，我以 Claude Code 为主要示例。Cursor 和其他兼容工具在对话内触发技能的方式不完全一样，但技能文件的读取路径基本都兼容.claude/skills这种目录约定。你只需要保证手头有一个能识别 SKILL.md 文件的工具就行。

2.2 拉取仓库与跑通初始化脚本

我当时的做法分四步，每一步都验证过：

# 1. 找个合适的工作目录，把仓库克隆下来 git clone https://github.com/obra/superpowers.git # 2. 进入仓库目录，查看 README 里的安装说明 cd superpowers # 3. 运行初始化脚本 ./bin/bootstrap

这里要给个提醒：网络搜索 behaviorial 告诉我，不同时间点的仓库结构会有差异，bin/bootstrap是我用过的常见入口，你实际拿到的最新代码可能改了脚本名，也可能增加了交互式安装流程。所以第一步git clone拿到仓库后，不要闷头跑命令，先花 30 秒看 README 和bin目录里有什么文件，再选择对应的初始化方式。

跑完初始化脚本之后，脚本通常会做三件事：把技能文件软链到你的助手工具能识别的技能目录（比如~/.claude/skills或者项目内的.claude/skills）；生成一份 CLAUDE.md 或在已有配置里追加 superpowers 的加载说明；在项目里创建一个superpowers缩写引用方便你后续启动技能。如果你的脚本没有自动完成这些步骤，也可以手动做，后面会写到手动配置的方式。

2.3 验证是否安装成功：直接问助手「你有哪些技能」

安装完成别急着干活，先做一次验证，确认技能已经成功挂载。最简单的方式是打开 Claude Code，在对话里输入：

/skills

或者直接问一句：

你现在加载了哪些可用的技能？

如果安装成功，你会看到一串技能名称，像artifacts-builder、decide、first-principles、task-mapper这些。看到列表出来，才说明软链路径和配置文件都对。列表为空的话，大概率是技能目录没放在正确位置，或者 CLAUDE.md 里少了技能加载的声明。

我碰到过一种很隐蔽的情况：技能列表能正常显示，但对话里明确调用某个技能时，助手却回复说不知道怎么执行。后来发现是技能文件的 YAML frontmatter 里的name字段和实际目录名不一致，导致助手在匹配时出现了偏差。这种问题不是安装脚本能检测出来的，只能靠手动检查目录结构。

2.4 手动配置方式：当初始化脚本不好使的时候

初始化脚本偶尔会因为权限、路径包含空格、或助手工具版本太旧而失败。这时候别慌，手动配置只需要三步，本质就是让助手知道「技能文件在哪儿、什么时候应该加载」。

第一步，把技能文件放到助手默认扫描的目录。以 Claude Code 为例，项目级技能目录是项目根目录下的.claude/skills，全局技能目录是~/.claude/skills。你可以直接把 superpowers 仓库里的skills目录原样放进去，也可以用软链，这样后续git pull更新技能时不用重复拷贝：

ln -s /绝对路径/superpowers/skills ~/.claude/skills

第二步，在CLAUDE.md里加一段加载说明。很多技能框架的默认 prompt 里并没有强制要求读取 skills 目录，所以你要显式告诉助手：当任务内容与某个技能文件的描述匹配时，应当读取该技能文件并严格按里面的步骤执行。

第三步，重启你的助手工具进程，让它重新读取配置。不要小看这一步，我改完配置后常常忘了重启会话，然后对着空气白折腾十分钟。

3. 内置 skills 全景盘点：哪些技能值得立刻用起来

superpowers 仓库里带着一批写好的技能，质量参差不齐，有些我天天用，有些装完再没碰过。下面按我的实际使用频率和适用场景分一下类，给你一个选型参考。

3.1 设计与可视化类

这类技能我使用频率最高，代表性的是artifacts-builder、excalidraw和subway-map。

artifacts-builder用来构建 Web 原型，适合你有一个模糊的界面想法，想快速看到一个可以点击的 HTML 页面。它内部会引导助手先拆解设计目标，再逐步生成可运行的前端代码，而不是一次性甩一个几百行的单文件出来。用几次之后你会发现，它输出的页面结构比空口让 AI 写页面要规整得多。

excalidraw能把文字描述转换成 Excalidraw 格式的绘图文件，画架构图、流程图、线框图都可以。我一般在设计系统交互、梳理模块依赖时用，把乱糟糟的脑内想法导成图形，后面开会讲方案时直接拿图说事。

subway-map是个冷门但很有趣的技能，它可以把任务拆解信息渲染成地铁线路图风格的视觉稿。说实话日常开发用不上，适合做汇报总结或者团队看板的时候图一乐。

3.2 工作流与决策类

这一组是我认为 superpowers 最核心的价值所在：first-principles、decide、goal-identification和task-mapper。

first-principles从第一性原理出发拆解问题，专门对付「感觉哪儿不对，又说不出为什么」的模糊场景。它会引导助手别急着给方案，先问清楚问题背景、约束条件、以及你到底想达成什么结果。这个技能在项目早期需求调研时特别好用。

decide是一个决策框架技能，适合在多个方案之间取舍。它会让助手列出选项、评估标准，然后逐个打分对比，最后给出建议。我用它来对比技术选型、要不要重构某段代码、以及两个方案哪个更符合当前阶段目标。

goal-identification会帮着把宏大的、说不清的目标拆成可执行的小目标序列。很多时候你只知道自己「想做个东西」，但做完是什么样、第一步干什么完全不明确。触发这个技能后，助手会扮演提问者的角色，一步步把目标收敛出来。

task-mapper是把目标映射成具体任务列表，衔接在goal-identification后面用效果最好。它会结合当前仓库的技术栈和已有代码结构，把任务细化到可以照着写代码的程度。

我个人建议：如果你只打算尝试三个技能，优先试goal-identification、task-mapper和decide。这三个组合起来覆盖了「厘清目标 → 拆解任务 → 做出决策」的完整前置流程，非常适合需求不清晰时的冷启动。

3.3 内容生成与格式转换类

write-a-story是写故事、写营销文案、写场景描述用的；markdown-converter能把混乱格式的文本整理成规整的 Markdown；memes会生成梗图文字，适合给团队群提提氛围。

还有一个容易被忽略的txt-to-svg，它能把文字描述转成 SVG 图案。这个技能我推荐设计同学重点试，画 ICON、做装饰图形、生成背景纹理，效率比手绘快很多，而且输出是矢量格式，后续直接改参数调样式。

3.4 文件与工程效率类

这组属于「用了就回不去」的类型：combine-files、bulk-rename、open-a-file和zip。

combine-files能把多个文件内容合并成一个文件，适合在需要把一批代码喂给 AI 分析时用。以前我需要把十几个分散文件的内容贴进一个对话里，手动复制粘贴费时费力还容易漏，现在一句话就能生成一个合并文件。

bulk-rename批量重命名文件，这个技能对于一整个目录的命名规范化非常有用。open-a-file强调「以大纲或用户指定方式打开文件」，适合快速跳转到项目里某个文件。zip则是在命令行里生成压缩包，不需要额外记忆 zip 命令参数。

4. 把技能变成自己的：自定义 skill 的编写方法与目录规范

内置技能再丰富，也不可能覆盖你团队的私有流程。真正让这套体系起飞的，是你能把自己经常重复的操作固化成新技能。下面讲编写一个 SKILL.md 的核心要点。

4.1 SKILL.md 的基本结构：frontmatter + 正文指令

每个技能对应一个目录，目录里放一个SKILL.md文件。文件的开头是一段 YAML frontmatter，包含name、description、when_to_use这几个关键字段，然后正文是实际的指令内容。

name需要和目录名保持一致，表达要简洁清晰，比如combine-files；description要写清楚这个技能解决什么问题，尽量覆盖关键词，因为助手就是靠它去判断要不要加载这个技能的；when_to_use给出触发条件的典型场景，这一步很多人会忽略，但它直接决定技能是否会被在正确的时机调用。

正文部分才是核心。你可以把助手需要执行的操作步骤、要遵循的原则、输出格式、以及「绝对不能做的事」写清楚。Markdown 里支持列表、表格和代码块，写这些指令时大胆用，结构化的指令比一段话更容易被执行。我还会在正文末尾加一个简单的示例，告诉助手「用户说类似这句话的时候，你应该走到哪一步」。

4.2 一个极简自定义技能示例

假设我想把「给新模块写测试用例」这件事标准化。项目里经常出现测试风格不统一、覆盖重点跑偏的问题，我就写了这样一个小技能：

--- name: write-tests description: 为新增模块生成单元测试与集成测试用例，处理好外部依赖的 mock 策略。 when_to_use: 用户要求补充测试、提交代码前检查测试覆盖、或明确提出需要测试用例时。 --- # 步骤 1. 先阅读目标模块的源码，列出所有公共函数和类方法。 2. 按 正常路径 > 边界条件 > 异常输入 的顺序设计用例。 3. 外部依赖一律 mock，不发起真实网络请求。 4. 测试文件放在与源码同目录的 __tests__ 文件夹下。 5. 完成后用覆盖率工具跑一遍，报告需要覆盖到关键函数。 # 输出格式 返回测试文件路径、测试项列表、覆盖率结果，并用简短段落说明是否还有遗漏风险。 # 反例 不要在测试里写 slept 等待，优先使用显式等待。

你可能会说，这些东西写进 CLAUDE.md 不也行吗？行，但区别在于，CLAUDE.md里的内容是每轮对话都生效、时刻占用上下文的；而技能文件只有在用户请求匹配到when_to_use时才会被读取。考虑到上下文预算，常用公共指令进 CLAUDE.md，低频且场景明确的任务进 skills，这是比较合理的分界线。

4.3 技能触发的边界判断

写完技能后，最大的变数是「助手会不会在正确的时机主动加载它」。我实际用下来的经验是，description和when_to_use两个字段写得越具体、越贴近用户可能的自然表达，触发率越高。你可以在 desc 里放几个典型说法，比如「用户说 帮我写测试 / 补一下测试 / 测试覆盖率不够」都算作匹配信号。

另外一个没人明说的技巧：技能文件不要太长。超过 300 行的技能，即使触发了，助手也会抓大放小，忽略掉一些细节指令。我自己的准则是，一个技能只解决一个核心问题，全部内容压在一屏左右读完。想覆盖多个场景？拆成多个技能，让助手自己去组合。

5. 实际使用中的踩坑与效率心得

下面是踩坑环节。这些都是我实操中真实遇到过的，不是文档里会告诉你的东西。

5.1 技能加载失败的第一排查链路

症状是：明明技能列表里有decide，但是对话里说「帮我做个决策」时，助手就是不读技能，反而常规回答。我的排查顺序是：

先看 frontmatter 的name和目录名是否一致。不一致时助手可能在目标匹配阶段直接跳过；再看description里有没有覆盖用户当前的自然语言表达。如果描述太泛泛，比如只写「提供决策建议」，用户说「这两个方案我选哪个」时，匹配模型可能认为不相关；最后确认 CLAUDE.md 里加载声明是否有效。有些工具升级后，默认的加载策略会变，需要在配置文件里重新声明读取 .claude/skills 下的技能并优先执行。

这套排查看似简单，但能解决八成加载问题。剩下的两成，基本就是助手工具版本本身的 bug，升级版本后自愈。

5.2 路径里有中文或空格带来的诡异问题

初始化脚本软链时，如果仓库路径或项目名里带中文、空格，脚本拼接路径时很可能拿到一个残缺的目录，技能列表时好时坏，或者干脆查不到技能。解决办法很粗暴：把 superpowers 仓库放到一个纯英文路径下，例如/home/me/dev/superpowers，然后重新软链。你可能会觉得这不是大问题，但在国内开发环境里，用户名是中文拼音缩写、桌面路径含中文的情况还挺常见的，值得提前避雷。

5.3 上下文膨胀问题：技能不是越多越好

你可能觉得技能越多越好，实际恰恰相反。技能列表太长会在匹配时增加噪声，助手偶尔会搞混相近技能，而且每次聊天记录里会带上大量的技能摘要，挤占上下文。我现在生产环境只保留 8-10 个核心技能，其他技能放在备份目录，需要时才临时启用。

具体做法是维护两层目录：~/.claude/skills里只放常用技能；~/skills-archive放不常用但有价值的技能，用软链或复制的方式在使用时临时挂载。这样既不影响日常任务，也保住了所有可复用资产。

5.4 多个技能同时被触发时的指挥冲突

有时候一个问题既匹配first-principles又匹配goal-identification，助手会纠结到底读哪个，或者连续读多个技能，然后无所适从。解决方式是我在 CLAUDE.md 里加了一段优先级说明：明确「如果多个技能同时匹配，优先读取task-mapper；若目标是拆解任务而不是探索路径，直接加载task-mapper」。这个做法等于是给助手定了一套技能的仲裁规则，很管用。

5.5 从个人使用到团队共享的迭代节奏

最后聊点非技术层面的体会。superpowers 这种结构化的技能，最大的价值其实是把「我个人会怎么做」变成了「团队默认该怎么做」。我发现最好的迭代节奏是：每完成一个重复过三次以上的流程，就把它写成一个新技能；每个技能至少实际使用两周后才放进正式目录，太早固化容易把错误习惯也存进去。团队里可以设置一个skills-review的机制，定期讨论哪些技能需要升级、哪些技能没有人用直接下架。技能库和代码库一样，只有持续维护才不会被废弃。

我的真实感受是，superpowers 这套东西的门槛不在安装，而在意识和习惯。安装它只需要十分钟，把「可复现的工作流封装成技能，让 AI 按你的标准执行」这个观念融进日常，才是真正拉开效率差距的地方。如果你也打算入坑，我的建议是从三个以内的小技能开始，跑通整个流程，再慢慢扩展。别一上来就追求技能数量，先把一两个核心场景打透，你会很快体会到这套体系的妙处。