如果你最近在折腾 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 两个技能先用起来。用顺手了再慢慢引入其他模块。技能这东西多一个容易乱少一个够用就行。你先跑起来跑一阵子自然会知道缺什么。毕竟工具永远是服务工作流的不要让工作流反过来被工具绑架。
如果你最近在折腾 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 两个技能先用起来。用顺手了再慢慢引入其他模块。技能这东西多一个容易乱少一个够用就行。你先跑起来跑一阵子自然会知道缺什么。毕竟工具永远是服务工作流的不要让工作流反过来被工具绑架。
