如果你最近在折腾 Claude Code、Cursor 这类 AI 编程工具，大概率刷到过 superpowers 这个词。它不是一个普通插件，也不是某个大模型，而是一整套可以直接装进你 AI 编程环境的 skills（技能）集合，来自开源社区一个挺有人气的项目。简单说，它把程序员日常最常用的工作流——项目规划、任务拆解、上下文记录、灵感暂存、代码地图、技能管理——全部封装成了 AI 能自动识别和调用的标准化技能。这篇文章我不打算给你念官方文档，而是从安装开始，逐个拆解它内置的几大核心技能，告诉你每个技能到底在解决什么痛点，以及我在真实项目里是怎么随手用它的。如果你正想让 AI 助手从“聊天机器人”变成“能干活的项目搭子”，这篇文章应该能帮你省下不少试错的时间。
1. Superpowers 是什么：AI 编程助手里的“技能包”
1.1 为什么需要“技能”而不是“提示词”
先聊一个很多人没想明白的问题：每次用 Claude Code 这类工具时，你都会给它写一大段 system prompt，或者反复把一堆项目说明贴进对话里。这样做最大的问题不是累，而是不稳定。模型每次只拿到你临时塞给它的文字，它不知道你有一个标准化的任务拆解流程，也不知道你希望它用哪种方式来管理上下文。于是同样一句话，今天它给你列三个步骤，明天它能给你展开成一篇论文。
Superpowers 解决的就是这个问题。它把一系列已经被验证过的工作方法论，写成了一组结构化的技能文件。每个技能都有自己的名字、描述、使用步骤和输入输出规范。当你在对话中提到某个关键词，或者你的环境配置让它自动发现当前任务时，AI 就会主动加载对应的技能包，按照里面写好的流程来干活。这就像你给新员工发了一本操作手册，而不是每次临时口述一遍要求。
1.2 它到底包含了什么
这个项目默认自带六个核心技能，分别是 Workbench、Inbox、Timeline、Notebook、Canvas、Library。我先把它们的用途用一张表列出来，后面每一节再单独展开。
| 技能名称 | 核心作用 | 日常类比 |
|---|---|---|
| Workbench | 拆解任务、跟踪执行进度 | 项目管理白板 |
| Inbox | 收集临时想法、待办事项 | 桌面上的便利贴 |
| Timeline | 记录决策历史、恢复上下文 | 会话回放录像 |
| Notebook | 持久化保存关键信息 | 团队共享笔记 |
| Canvas | 梳理代码库结构和依赖关系 | 系统架构图 |
| Library | 管理自定义技能包 | 个人工具箱 |
1.3 适合谁用
我认为这个项目最适合两类人。第一类是深度使用 Claude Code、Cursor、Windsurf 这类 AI 编程工具的开发者，尤其是每天要同时维护多个项目的场景。第二类是团队里承担架构决策、代码评审角色的人，你需要让 AI 在理解项目背景后提供更靠谱的建议。如果你只是偶尔用 AI 写几段代码，那它对你的价值会打折扣——因为技能体系真正发挥作用，依赖长期、连续的使用，它需要积累项目上下文，需要你的工作流和它磨合。
2. 安装 superpowers：从零到真正“引入”这些技能
2.1 环境准备与前置条件
在动手安装之前，先确认你的基础环境。官方推荐的方式是通过 Git 克隆仓库，然后执行项目里的安装脚本。你需要准备两样东西：一个是 Git，另一个是已经装好的 Claude Code 或者 Cursor 这类支持 skills 机制的 AI 编程工具。
这里我想多说一句环境变量的重要性。Superpowers 安装完成后，会有一个CLAUDESKILLS_DIR环境变量指向技能存放目录。很多新手装完发现没有效果，大概率就是环境变量没配好。你在克隆项目之后，应该先把技能目录固定到一个稳定的位置，比如~/.claude/skills或者项目自己的目录，这样后续更新和维护都会方便很多。
2.2 一键安装与手动安装两条路
如果只是个人尝鲜，直接用一键脚本最省事。打开终端，进入到你想存放项目的目录，执行 Git 克隆命令，然后运行项目里的install.sh。脚本会自动把技能文件链接到你的 Claude Code 技能目录，并打印出安装日志。整个过程大概一分钟，不需要手动改配置文件。
但我不建议一上来就走脚本。手动安装虽然多几步，却能让你彻底搞明白技能文件到底放在哪、是怎么被加载的。手动安装的核心就是把仓库里的skills子目录链接或复制到你的CLAUDESKILLS_DIR。在 Linux 或 macOS 上，可以用软链接，这样之后更新只需要git pull就行，不用重复复制。Windows 用户复制目录也没问题，只是后续更新要自己注意同步。
很多博文只教你跑 install.sh，而不告诉你脚本背后干了什么。我在实际装完以后专门去翻了它脚本的逻辑，其实核心就是找 skills 目录、确认目标目录存在、然后建立符号链接。手动操作一遍，你对整个机制的理解会完全不同。
2.3 验证安装是否成功
装完之后，别急着喊“搞定”，先验证一遍。有两个简单的检查方法。第一个是看目录：进入你的CLAUDESKILLS_DIR，用ls列出文件，应该能看到workbench、inbox、notebook这些子目录，每个目录里都有一个SKILL.md文件。这个 SKILL.md 就是技能的定义文档，里面包含技能的名称、描述、使用流程等信息。
第二个方法是直接打开 Claude Code，输入一条和 Workbench 相关的指令，比如让 AI “使用 workbench 来规划这个任务”。如果 AI 能准确说出“好的，我将按照 Workbench 的流程来拆解任务”，并且开始生成结构化清单，就说明技能已经被正确加载了。如果你发现它完全听不懂你在说什么，第一反应应该是检查环境变量和技能目录的层级结构，而不是怀疑这个项目本身有问题。
2.4 一个容易被忽略的加载逻辑
关于这些技能怎么被 AI “看到”，有一个机制你必须理解。AI 编程工具并不是把所有技能内容一股脑塞进每一轮对话，那样窗口早就爆了。它更常见的做法是读取每个技能文件顶部的描述信息，当你的请求命中描述里的关键词时，才动态加载对应的完整步骤。这也是为什么有些人感觉“技能时灵时不灵”——如果你说的话没有触发技能描述，它就真的不会被调用。
想让技能自己浮现，最好的做法是在对话里明确提到技能的名字，比如直接说“用 inbox 记录一下”“用 timeline 保存当前决策”。这算是最直接的触发方式，也符合这类工具当前的主流交互逻辑。
3. 六大核心技能逐个拆解：它们到底怎么用
3.1 Workbench：让 AI 把大任务拆成可执行清单
Workbench 是这套技能里我用得最频繁的一个。它解决的是 AI 编程里最让人头疼的问题：任务太大、太模糊时，AI 会跑偏。比如你让它“优化一下登录模块”，它可以给你改出一整套身份认证体系，也可以只帮你把按钮颜色调了，差距极大。
Workbench 的做法是把任务拆解成工作单元，每个单元有明确的输入、输出和验收标准。实际使用中，我会先给它一段需求描述，然后用“使用 workbench 规划这个需求”这样的指令。它会输出一个任务清单，每个任务都带状态标记，比如未开始、进行中、已完成。这个过程等于把 AI 变成了一个会自动维护 todo list 的协作者，而不是一个只能执行单条指令的终端。
有一点很关键：Workbench 生成清单之后，它会把清单写入一个独立文件，而不是只放在对话里。这意味着即使对话上下文滚动到很远，AI 依然能回去读取这个清单文件，随时确认进度。我自己的习惯是每次开始一个新功能时，先让 Workbench 生成计划，然后把计划文件路径告诉 AI，后续所有对话都绑定这个计划来推进。
3.2 Inbox：临时想法和待办事项的“收集箱”
Inbox 是最容易被低估的一个技能。很多人在开发时会有一种体验：正在写 A 功能的代码，突然想到 B 模块还有个 bug 要修，或者 C 方案值得试一下。你手头没有趁手的记录工具，于是要么切出去开备忘录，要么强迫自己记住，结果五分钟后忘得干干净净。
Inbox 解决的就是这种临时的、不完整的想法收集。它不同于 Notebook，不追求结构化，而是像一个收件箱，什么碎片都先放进来。你只需要对 AI 说“把这个想法放进 inbox”，它就会把内容追加到 inbox 文件里，并加上时间戳。等到有空的时候，你再统一整理这些条目，分门别类地转入 Notebook、Timeline 或者是待办清单。
用 Inbox 有一条我自己的心得：不要在这个阶段做任何分类或加工，最重要的是“先记下来”。任何加工动作都会成为大脑的负担，导致你不想记。AI 帮你记就不一样了，你只管说，剩下的它来做。这个习惯养成了以后，你会发现自己的思维中断率大幅下降，因为你不怕忘记，自然能更专注在当前任务上。
3.3 Timeline：让 AI 的分工有了“记忆回放”
Timeline 是一个让我对这套技能刮目相看的模块。随着项目推进，AI 和我之间聊过很多事：改过哪些接口、放弃过哪个技术方案、为什么决定不用某个依赖库。这些信息一旦淹没在对话历史里，就等于不存在了，因为对话窗口一压缩，AI 就忘了。
Timeline 做的事情，是把这些关键决策按时间顺序记录下来，形成一个可持续回溯的历史。每个记录包含时间、事件类型、相关的文件或任务、以及简短描述。当新会话开始时，我可以让 AI 读取 Timeline，快速恢复项目上下文。它特别适合做代码评审和交接，也适合在自己中断几天后重新捡起一个项目。
不过我必须提醒一句：不要事无巨细都往 Timeline 里塞。它的价值在于“关键节点”，比如架构调整、重大 bug 修复、依赖升级。琐碎的改动记进去只会形成噪音，真正需要回顾的时候反而找不到重点。我一般会按每周两三条的频率来记录，刻意保持精简。
3.4 Notebook：项目知识的“持久化大脑”
Notebook 和 Timeline 经常被混在一起，但它们其实是两回事。Timeline 记录的是“发生过什么”，Notebook 记录的是“我们学到什么以及现在该知道什么”。比如你接手一个老项目，发现某段代码不能随便动，因为里面有隐藏依赖——这种经验就应该进 Notebook，让 AI 在今后的对话中随时参考。
Notebook 最大的优势是持久性。对话会结束，窗口会清空，但 Notebook 内容会一直保留在项目目录里。AI 在每次会话中看到 Notebook 文件时，会把它作为重要背景知识来使用。这相当于你给 AI 建了一个长期记忆库，它不需要每次都从头了解项目。
我建议按主题来组织 Notebook 条目，比如“构建系统注意事项”“遗留代码风险区”“集群环境访问方式”，而不是按时间顺序。这样 AI 在对应场景下读取时，可以快速定位相关条目。如果你用grep看过 Notebook 文件的结构，会发现它比想象中简单，就是一组标题和段落，AI 的语义理解能力足以处理这种松散的格式。
3.5 Canvas：项目结构和依赖关系图
Canvas 是这套技能里帮你建立全局视角的工具。做大型项目的时候，很多问题不是代码写得不好，而是没人说得清整个系统的结构。新模块应该放在哪个目录，这个服务依赖哪些上游接口，改了数据库表会影响哪些下游服务——这些信息通常散落在各人的脑子里。
Canvas 的作用是把你项目里的关键实体、模块关系、数据流向梳理出来，形成一个可查询的结构化描述。你可以让 AI 阅读项目源码生成 Canvas，也可以自己口述补充。最典型的用法是，当你准备做一个跨模块的改动前，先让 AI 读取 Canvas 里的结构信息，它会针对“受影响的文件”给出更精准的判断。
说句实在话，Canvas 不是万能的。对于极大型项目，完全靠 AI 自动扫描生成结构图必然有遗漏，它更擅长处理中小型代码库。但正是因为这样，它才适合用来做“项目地图的起点”。我在新加入一个项目时，会先让它生成 Canvas，然后对照目录结构手工纠正，最终合并成团队内部都能参考的文档。
3.6 Library：管理你自己的技能包
最后一个模块是 Library。前面说的几个技能都是项目自带的，但真实工作中，每个团队、每个开发者都有自己独特的工作方法。比如你可能有一套固定的代码审查清单，或者一组常用的项目初始化命令。这些如果能沉淀为可复用的技能，效率会提升一大截。
Library 就是干这个的。它允许你往技能目录里添加自定义技能，每个技能同样是包含描述和步骤的文档结构。这样一来，你可以把重复性的操作固定下来，让 AI 每次按标准流程执行。比如我给自己写了一个“数据库迁移”技能，规定了迁移脚本生成、本地验证、备份策略、上线步骤的完整流程，每次要动数据库时，一句话就能触发这套流程。
自定义技能的内核并不神秘，本质上就是写好一个 SKILL.md，再把它放进指定目录。难的是你想清楚这个过程做什么、边界在哪、验收标准是什么。我从这个模块学到的最大经验是：好技能一定是窄而深的，一个技能只解决一个问题，啰哩啰嗦写一大堆反而会让 AI 丧失焦点。
4. 实战里踩过的坑与我的日常工作流
4.1 环境变量没生效
我第一次跑完安装脚本后，进入 Claude Code 测试，发现 AI 对我的“workbench”指令毫无反应。排查了十分钟，最后发现是 shell 配置的问题。我的 shell 环境里虽然写了CLAUDESKILLS_DIR=~/.claude/skills，但 Claude Code 启动时的子进程并没有继承这个变量，导致它找不到技能目录。
解决办法很直接：把这个环境变量写入~/.bashrc、~/.zshrc或者你的系统配置文件，并确保用绝对路径，不要用~缩写。改完以后重启终端窗口，再启动 Claude Code。如果你是 macOS 用户，还要留意 launchctl 那套环境变量加载机制，有时候终端里能读到，但桌面应用启动时反而读不到。
4.2 多客户端共享同一套技能
我记得有一阵子同时用 Claude Code 和 Cursor 调试项目，起初分别给它们装了一套技能，结果两边修改不同步，维护成本极高。后来我把CLAUDESKILLS_DIR统一指向同一个目录，两边共享同一份技能文件。Custom skills 和应用自身的那套机制依赖一致，强制改成同一个路径之后并没有出现冲突，使用上顺畅很多。
如果你也打算这么做，记住一个要点：定好谁是“主进程”。比如统一在 Claude Code 里做技能更新和测试，确认没问题之后，其他客户端直接读取同一份文件，不需要重复安装。修改技能内容时，也尽量在统一目录下手动编辑文件，避免某个客户端自动生成内容造成冲突。
4.3 定位问题：AI 没反应不等于技能没装
群里经常有人问“我装了 superpowers 但 AI 完全没有变聪明，是不是没用？”这里有个误解：superpowers 不是给 AI 增加智力，而是给 AI 增加流程认知。如果 AI 没反应，首先要确认你用的工具是否支持 skills 自动加载，其次确认触发词是否准确，最后再检查技能描述文件是否被正确解析。
我会用一个很简单的办法来判断：直接问 AI “你有哪些技能可以调用”。如果它能列出 Workbench、Inbox、Timeline 这些名字，说明技能文件已经被它读到。如果它列不出来，再检查目录层级和文件格式。注意每个技能的 SKILL.md 文件都要有 YAML frontmatter，也就是开头有---包起来的元信息，包含 name 和 description 字段，否则 AI 可能无法解析。
4.4 我的固定开工流程
我现在每天的开发工作基本固定成一个流程。打开新会话之后，先让 AI 读取 Timeline 和 Notebook，恢复项目上下文。然后根据当天任务选择一个 Workbench 计划，可能是新功能，也可能是 bug 修复清单。过程中产生的临时想法喊一声“放进 inbox”，完成一个任务后更新 Workbench 里的清单状态，遇到值得沉淀的经验就写进 Notebook。一天结束后，把关键进展追加到 Timeline。整个过程听起来机械，但胜在稳定。
这一套流程磨合了大约两周，最明显的变化是我不再频繁复制粘贴项目说明到对话里，也不再担心 AI 中途忘事。它记住的东西比我自己记得多。
最后分享一个我的实际操作心得：无需追求一套流程完美无缺才上手，你完全可以只装 Workbench 和 Notebook 两个技能先用起来。用顺手了再慢慢引入其他模块。技能这东西，多一个容易乱，少一个够用就行。你先跑起来，跑一阵子自然会知道缺什么。毕竟工具永远是服务工作流的，不要让工作流反过来被工具绑架。
