企业官网建设流程全解析

从第一次在同事的终端里看到“superpowers”这个项目，到我自己把它完整接入日常开发流程，中间踩了不少坑，也摸清了不少门道。今天不写那种照抄 README 的流水账，就从一个实际使用者的角度，聊聊这个项目解决的是什么问题、技能包到底怎么组织、安装和引入过程中最容易在哪几个环节翻车，以及最后我自己沉淀下来的一套造技能的方法论。

先说结论：如果你经常跟代码协作助手打交道，或者团队里多人共用一套自动化工作流，这个项目值得花半小时认真看一下。它能把你散落在各种文档、提示词、脚本里的“经验碎片”统一成一个个可安装、可复用的技能包，让工具真正知道“在你的项目里该怎么干活”。

1. 先搞清楚这个项目解决的是哪类痛点

1.1 你大概率也遇到过：每次进项目都要重新调教一次

我最早接触这类技能管理工具，起因是一个很现实的麻烦：同时维护三四个项目，每个项目的技术栈、代码规范、提交规范、测试约定都不一样。A 项目要求 Conventional Commits，B 项目要求单测必须跑完整套才能提 MR，C 项目甚至规定所有配置文件里不能出现绝对路径。

问题是这些约束写在哪？一部分在 README，一部分在团队 Wiki，一部分在某个同事的聊天记录里。结果就是每次切换项目，我都要把这些规则重新“喂”给工具一遍，而且喂的方式还是复制粘贴。项目一多，粘贴错误、版本过期、口径不一致的情况层出不穷。

superpowers 这类项目解决的第一层问题，就是把“约束上下文”从人脑和散落文档里抽出来，变成项目目录下一个结构化的技能包。工具读到这个包，就知道当前项目的规矩是什么。这套思路跟很多编辑器的 rules 机制类似，但更强调的是“可安装、可复用、可分享”。

1.2 第二层痛点：流程型操作没有统一编排

除了知识约束，日常开发里还有一类工作是“流程型”的。比如：提交代码前要跑 lint、更新 changelog、检查敏感信息；发布版本前要打 tag、生成 release notes、同步文档。

以前我做这些事靠的是自己写的一堆 shell 脚本，再配合手打的命令序列。脚本一多，管理起来很痛苦：有的脚本只服务于特定项目，有的脚本又跟版本库绑定，换台机器就找不到。

superpowers 把这类流程也封装成了技能。一个技能包可以描述“当用户触发 xxx 时，依次执行哪几步，每一步用什么工具，产生什么中间结果”，这样操作就从“靠记忆拼命令”变成“触发一个标准动作”。

1.3 这个东西不是什么：不是编程语言，也不是自动化平台

需要先泼盆冷水。superpowers 不是让你用一套新语言写业务代码，也不像 Jenkins 那种重量级流水线工具。它更像是给“工具 + 人的协作过程”做了一个轻量级的标准化外壳。

我见过不少人第一次接触这个概念，下意识把它想复杂了。其实核心模型非常简单：技能 = 一段结构化描述 + 若干资源文件。描述里写清楚触发条件、执行步骤、输入输出；资源文件里放模板、提示词片段或脚本。工具负责识别、加载、按规则执行。理解到这个粒度，后面所有的安装和排障都顺了。

2. 核心设计拆解：技能包到底长什么样

2.1 一个技能包的文件构成

先看目录结构。拿我项目里一个用于规范 Git 提交信息的技能举例：

superpowers/ └── skills/ └── git-commit-standard/ ├── skill.yaml ├── SKILL.md └── templates/ └── commit-message.md

三个核心文件各司其职：

• skill.yaml 是元数据文件，声明技能的 id、名称、版本、适用场景、所需依赖。
• SKILL.md 是主体说明文件，用自然语言加少量标记描述这个技能的使用方式、约束条件和执行步骤。
• templates 目录放配套资源，可以是消息模板、配置文件模板，也可以是小型脚本。

这个设计的妙处在于，它同时照顾了两种读者。工具能读 skill.yaml，把技能登记到索引里；人或者协作助手能读 SKILL.md，理解技能的业务逻辑。资源文件则保证了技能的“自包含性”，换环境不会丢东西。

2.2 技能的分类：知识型、流程型和工具型

使用了一段时间后，我把自己用到的技能分成了三类，分类决定了怎么撰写 SKILL.md：

知识型技能最简单，本质上是给工具喂上下文；流程型技能需要精确描述步骤，不能有歧义；工具型技能最考验鲁棒性，因为外部命令的失败分支你必须预先想到。

我的建议是，新手从“知识型”开始练手。第一条技能就做一个简单的、记录团队编码规范的知识包，跑通整个安装和引入链路后，再碰流程型和工具型，这样心智负担最小。

2.3 为什么选择 YAML 而不是其他格式

用过一段时间后，我越来越认可项目采用 YAML 做元数据的决定。JSON 太啰嗦，写几行就想加注释但没法加；INI 虽然简洁，但表达不了分层结构。YAML 的缩进语法在描述嵌套结构时非常舒服，而且支持注释，这个对团队协作来说太重要了。

skill.yaml 我通常这么写：

id: git-commit-standard name: Git Commit 规范 version: 1.2.0 description: 检查并生成符合 Conventional Commits 规范的提交信息 tags: [git, commit, workflow] triggers: - commit - commit-message templates: - templates/commit-message.md

这里有个细节要注意：id 一旦定下来，尽量别改。工具加载技能时通常用 id 建立索引，你改了 id，旧索引会变成死链接。版本号可以升，id 要稳定。

3. 安装与引入：从零到第一条技能

3.1 安装核心：快、静、无多余依赖

这是我当时很满意的一点：superpowers 的核心运行环境安装起来非常轻。它本质上是一个用脚本实现的加载器，不依赖特定的编程语言运行时，也不要求你装额外的守护进程。

以我熟悉的环境为例，安装步骤只有三步：下载核心脚本、赋予执行权限、设置环境变量。没有编译过程，也不会往系统目录里塞一堆乱七八糟的东西。装完后执行初始化命令，它会在当前用户目录下生成一个配置文件夹，默认结构如下：

~/.superpowers/ ├── config.yaml ├── skills/ │ └── builtin/ └── registry/

看到没，即使你没主动创建任何技能，它也会自带一组 builtin 技能，用来演示基本能力。我建议新手先别删，拿它们对照理解“一个技能包到底应该怎么写”。

3.2 引入一个现成技能：以社区技能包为例

引入技能有两条路径：从 Git 仓库直接拉取，或者复制到本地技能目录。以拉取一个社区通用的代码评审辅助技能为例，命令大致长这样：

superpowers install git@github.com:example/code-review-skill.git

执行后，工具会克隆仓库，把 skill.yaml 里的 id 登记进 registry，并自动做一次完整性检查。检查项包括：必要文件是否齐全、元数据是否能正常解析、声明的模板文件是否存在。

如果你的网络环境不方便走 Git，还有更笨但稳定的办法：直接把技能文件夹复制到 ~/.superpowers/skills/ 下，然后执行扫描命令。工具会扫描目录，自动把新技能加入索引。两种方式我都用过，个人推荐优先用 Git 方式，因为后续拉更新会更舒服。

3.3 在会话中真正“用”起来

安装只是前提，关键是引入。在支持技能语法的前端里，引入方式通常是斜杠命令。比如我装完 git-commit-standard 后，提交代码前直接输入：

/use git-commit-standard

工具解析到这条指令，会做三件事：读取 skill.yaml、把 SKILL.md 的内容注入当前协作上下文、根据 triggers 里的定义挂载相关的自动触发规则。

这里有一个我初期没意识到、后来觉得特别重要的机制：技能不仅可以手动触发，还可以按条件自动触发。当你把 commit 这个动作写进 triggers 后，只要检测到提交意图（比如你打开了提交信息编辑界面），相关技能就会自动被拉取。这个进一步减少了“我忘了用技能”的可能。

3.4 两条我认为最实用的引路建议

第一条，引入完技能后一定先检查状态。一条命令就能看到技能列表、版本、启用状态。别相信“应该装好了”，要眼见为实。

superpowers list

第二条，技能之间允许有依赖关系。如果你的工作流技能 A 依赖 B 的输出，那要在 skill.yaml 里声明 dependency。第一次引入时漏掉声明，运行到一半报错“找不到 B 技能的输出”，这是很多人踩过的坑。养成先看依赖、再引入的习惯，能帮你省很多事。

4. 实操排查：最容易翻车的五个环节

4.1 装了但发现不了：目录扫描和命名规范

先讲最频繁的问题：技能明明放进目录里，superpowers list就是扫不到。

我之前排查过一次，折腾了快半小时，最后发现是文件夹命名问题。我建了个目录叫git_commit_standard，下划线风格。工具的扫描器默认匹配 kebab-case（短横线风格），也就是git-commit-standard才符合规范。下划线命名的目录会被当作非标准目录忽略掉。

这不是 bug，是约定。技能的 id 和目录名最好都遵循 kebab-case，不用下划线，不用驼峰。解决办法也简单：改名，重新扫描。

4.2 路径含空格或特殊字符

操作系统的路径问题几乎人人都遇过。有一次我把技能仓库 clone 到一个带空格的目录里，比如/Users/my name/work/...，结果技能装载时资源文件路径解析失败，模板永远找不到。

排查思路：先看 registry 里登记的路径，再对比实际路径，大概率发现空格没转义。轻量框架不会把这种问题都替你处理掉，所以在路径安全这件事上，最好自己动手规避：技能仓库统一放在无空格、无中文、无特殊符号的路径下。这不是歧视，是省事。

4.3 多个技能相互覆盖：优先级冲突

当你的技能越来越多，优先级问题就暴露了。比如我同时装了团队内部的代码风格技能和社区的通用代码规范技能，两个技能都声称对“代码风格”这个场景有发言权，后加载的往往覆盖先加载的。

官方的设计里，技能的优先级由加载顺序决定，后加载的优先级高于先加载的。听起来简单，但如果你通过不同入口先后加载了一堆技能，很容易眼前一团乱。

我的建议是：能力相近的技能不要重复装。一个场景精挑细选保留一个技能，比装五个冲突技能再花时间调整优先级要高效得多。真到了必须调整优先级的场景，可以改配置显式声明依赖和冲突关系，别依赖隐式顺序。

4.4 模板变量不生效：转义和注释

技能里带模板文件时，变量替换是常见的失效点。比如我在 commit-message.md 模板里写了{{branch_name}}，结果引入时工具没做替换，原样把大括号输出到了提交信息里。

原因通常是模板引擎的注释符号和变量分隔符冲突。修改模板时不小心把变量部分注释掉了，或者用了中文全角括号替代英文半角括号，都会导致解析失效。

这种问题不好直接报错，因为模板语法本身合法，只是匹配不上。所以我自己给模板文件下了条死规矩：所有变量必须集中写在模板顶部，并在底部附带一份示例值，每次改模板都跑一次渲染测试验证变量确实被替换。这条纪律帮我省掉了无数隐蔽的小问题。

4.5 权限和跨平台问题

最后说一个典型的 Linux/Mac 环境下的坑：技能里的可执行脚本没有执行权限。工具型技能经常要调用辅助脚本，如果 clone 下来后脚本权限位不对，运行时会直接提示 “Permission denied”。

我之前有一次给团队分发技能包，大家同步了同一个仓库，Windows 上跑得好好的，同事在 Mac 上跑就报权限错误。排查到最后，是 git 拉取时丢失了可执行位。

解决分两步：本地提权，chmod +x scripts/xxx.sh；根上解决，在仓库里显式设置文件模式，并在安装文档里写清这一步。千万别假设大家的 git 配置都正确。

补充一个综合排查速查表，遇到问题先按这个顺序过一遍：

5. 自己造技能：一套值回票价的方法论

5.1 从需求到技能包：我的一次完整实践

安装和引入熟练之后，造技能是绕不开的一步。因为别人的技能永远不可能完全匹配你的项目场景。拿我最近做的“发布前置检查”技能举例，走一遍完整的设计流程。

当时的需求：每次发版前要检查版本号是否提升、CHANGELOG 是否更新、配置文件里是否有调试残留。以前靠手工检查，效率低且容易漏。

第一步，我把这个需求拆成一个“流程型”技能。它需要三步：读取当前版本号、比对上一版本、生成检查报告。每一步之间都有明确的输出和判断。

第二步，确定边界。它不该做什么？不负责真正执行发布，只做检查并给出结论。边界清晰，技能才不会被滥用。

第三步，写 skill.yaml 和 SKILL.md。我先把整个流程逻辑写在 SKILL.md 里，用 Markdown 的列表语法描述顺序，配合if-else形式的自然语言说明分支处理。接着写一个辅助脚本，单独负责版本比对，输出统一格式的结果。

5.2 我对 SKILL.md 内容组织的坚持

写说明文件这件事，看似简单，其实是整个技能包质量的分水岭。我自己有个固定的写作模板：

# 技能名称 ## 使用场景 （什么时候该用，什么时候不该用） ## 执行步骤 1. 2. 3. ## 输入 （需要哪些参数或上下文） ## 输出 （会产出什么结果） ## 异常处理 （哪些失败情况需要中止/告警）

最核心的是“执行步骤”和“异常处理”两块。执行步骤要用断言式的语言，比如“检查版本号是否大于仓库内最新标签”，而不是“看看版本号变了没”。后者太模糊，不同执行者理解可能完全不一样。

异常处理要覆盖常见失败分支，比如版本比较脚本因为格式不一致无法解析时，宁可中止并提示，也不要静默通过。静默失败是技能里最害人的东西。

5.3 完整示例：一个最小可用的技能包

写一个最小示例，方便你在 10 分钟里跑通全流程。建文件夹：

skills/ └── check-version-bump/ ├── skill.yaml └── SKILL.md

skill.yaml：

id: check-version-bump name: 版本号变更检查 version: 0.1.0 description: 检查当前版本号是否在上一版本基础上合规递增 triggers: - pre-release

SKILL.md：

# 版本号变更检查 ## 使用场景 发布预览前执行，确认版本号已更新，且更新符合 SemVer。 ## 执行步骤 1. 从 package.json 或项目配置中读取当前版本号。 2. 对比仓库内最新 git tag 的版本号。 3. 用 SemVer 规则比较新旧版本，确认递增且非降级。 4. 将结果写入检查结论，存在问题时标记为失败。 ## 输入 当前项目根目录配置。 ## 输出 一个状态结果：通过或失败，附两个版本号。 ## 异常处理 - 无法读取当前版本号：中止，提示缺少版本配置文件。 - 无历史 tag：跳过对比，但提示这是首次发布场景。

放到技能目录后，superpowers list能扫到它，/use check-version-bump就能引入。这整套链路走完，你对“技能到底怎么运作”的体感会比读十篇文档都深。

5.4 造技能的三个进阶心法

第一个心法：先服务自己，再考虑通用性。我见过团队里一上来就要求每个人都用它，结果推进困难。自己先用起来，在真实项目里暴露问题、不断迭代，版本稳定了再推广，阻力会小很多。

第二个心法：保持技能的单一职责。一个技能解决一件事，是底线。把“代码检查 + 自动修复 + 生成报告 + 通知群消息”全塞进一个技能里，表面看很全，实际上是维护灾难。拆成多个互相配合的小技能，反而容易维护。

第三个心法：版本号要严肃对待。技能会迭代，旧版本的使用者可能需要平滑升级。我给自己定了个规范：破坏性变更升主版本，新增功能升次版本，修小问题和文档升补丁版本。这样才能让使用者一眼看出风险等级。

5.5 技能包应该放在哪里：仓库内还是全局

最后聊一个策略问题。技能有两种持久化位置：全局用户目录和项目仓库内。全局技能适合个人通用的工作流，比如提交信息规范；项目仓库内的技能适合绑定项目特有约束，比如和某个服务架构相关的代码生成规则。

我的建议是“项目优先”。技能如果和业务紧密相关，就往项目仓库放，跟着代码走，新成员 clone 下来就能用。全局技能只放那些不管在哪个项目里都用得上的通用能力。两者职责分明，才不会出现“这台机器上有这个技能，那台机器上没有”的割裂感。

6. 一些使用体会和最后的提醒

我的切身感受是：这类技能管理工具的价值不是“装一次爽一次”，而是积累得越多，你的工作流越标准化，越不依赖某个人的记忆。一开始数据看起来麻烦，等你有了几十个技能包，它们相互支撑、彼此调用，整个开发流程会变得异常稳定。

当然也别忘了它只是工具，核心还是你定义规则的能力。技能包永远不能代替你自己思考，它更像是把你最靠谱的那套做法固化下来，关键时刻不用脑子也能执行到位。

如果只给一条最实用的建议，我会说：现在就给自己建一个最简“知识型”技能，哪怕内容只有几句代码规范。跑通从安装、引入、使用到排查的完整循环，后面的一切都顺理成章。以后你回顾这个过程就会发现，真正稀缺的从来不是工具，而是把经验变成可复用资产的习惯。