1. 这个项目到底解决什么问题如果你经常用 Claude 这类 AI 助手处理日常任务一定遇到过同一个问题——它很强但它记不住你的习惯。每次让它写日志、做周报、给变量命名、按你的风格检查代码它都像第一次见你一样从头开始“猜”。你可能试过把规则写进 System Prompt结果越堆越长改起来一团乱麻模型还容易在长上下文里把规则忘掉。Superpowers 解决的就是这个痛点。简单说这是一个开源的 AI 助手技能集项目让你通过一个干净的目录结构把零散的指令、规则、工作流打包成一个个“技能”Skills。每个技能就是一组 Markdown 文件里面写清楚模型的职责边界、工作流程、输出格式和校验标准。把它挂到你的 AI 应用或工作环境里Claude 就能在特定场景下自动调用对应技能行为稳定、风格统一不再每次从零发挥。项目关键词是 superpowers、skills、怎么引入、怎么安装所以这篇博文我按自己的实操顺序来写先拆解项目设计思路再讲完整安装流程然后挑几个最常用的技能做实战演示最后把我在真实工作中遇到的坑和排查方法整理成速查表。无论你是刚接触 AI 编程工具的新手还是已经在用 API 做自动化流程的老手都可以照着这份文档把技能集跑起来。我为什么强调“稳定”和“统一”因为我踩过太多次坑了。你会发现AI 助手在单次对话里表现得很好可一旦跨对话、跨项目、或者换了上下文窗口它就开始“失忆”。这不是模型变笨了而是你没有给它一套可复用的“行为准则”。Superpowers 的思路就是把“行为准则”文件化、模块化让它跟着项目走而不是藏在某段聊天记录里。2. 项目设计思路拆解为什么是“技能包”而不是“提示词”2.1 技能集与传统 Prompt 的本质区别很多人第一次看到 Superpowers 的目录会觉得“这不就是一堆 Markdown 吗”是的但这一堆 Markdown 的摆放方式、命名规则和内容结构决定了它和普通 Prompt 有本质区别。传统 Prompt 是“一次性”的你把规则写进 System Prompt模型每次都要处理这坨越来越大的文本上下文中有效信息被稀释而且你很难单独更新某一条规则而不影响其他内容。Superpowers 的做法是“模块化”——每个技能独立成一个文件夹里面一般包含 SKILL.md 作为主文件再带上 references 子目录放辅助资料。模型在对话过程中根据用户意图判断该激活哪个技能然后只把那个技能的内容加载到上下文里用完就释放。这个设计解决了三个实际问题。第一上下文窗口不再被一堆无关规则占用模型在关键时刻能专注在当前任务上回答质量明显提升。第二更新某条规则时只改对应的技能文件不会牵连其他模块版本管理也清晰git 记录干净回溯问题方便。第三技能可以跨项目复用我这边的项目是写博客和数据分析换个朋友的项目是做前端开发同一套技能包拿过去改改就能用。我自己刚开始用的时候是把它当“更聪明的提示词文件夹”来理解的用了一阵子之后才意识到它真正改变的是你和模型协作的“接口”——你不再依赖临场发挥的文字描述而是通过一套标准化的文件约定让模型知道自己什么时候该干什么、干到什么程度算完。2.2 官方目录结构里藏着什么以官方主分支的目录布局为例你会看到一堆按功能命名的文件夹整体上可以分为三类。第一类是“金丝雀检查”这类基础技能作用是让模型在做任何有风险或有副作用的操作前先自我检查和自我修正相当于给模型装了一个“动手前先刹车”的机制。第二类是日志、时间追踪、核心记忆这类效率向技能偏日常工作和信息管理。第三类是偏编程的比如写正则表达式、做实时调试、技能编写等。这个分层思路很值得借鉴。它不是把所有规则扔在一起而是按“任务类型”拆开让模型在处理某类任务时只加载最相关的上下文。整包引入当然也行但如果你只想要其中几项完全可以做减法只保留自己真正用得上的部分。使用效果上最直观的感受是模型“有边界了”。以前我让它分析一段代码它可能洋洋洒洒写几百行分析看起来专业其实一半是套话。现在如果激活了调试技能它会先复述问题和目标然后按步骤做边界测试最后直接给我结论和修复建议不再说一堆正确的废话。2.3 为什么这套方案适合个人开发者和小团队个人开发者和小团队是 Superpowers 最典型的受众原因有两个。其一我们没有专门的人维护 Prompt 工程需要一个低维护成本的方案文件即规则改起来直观不需要懂复杂的 Agent 框架。其二我们通常跨多个项目、多个技术栈技能包的可移植性正好匹配这种流动的工作方式。以我自己为例我日常用到 AI 的场景包括写技术博客、分析用户反馈数据、写疲惫之余的小工具脚本、以及帮我审查 pull request。以前这四个场景需要四套不同的“调教话术”现在我把它们对应成四个技能文件需要哪个就触发哪个行为一致性高了不少。小团队还可以把技能包放进 git 仓库全员共享新同事入职直接拉下来就能用不用再靠口头传递“你得这样提示 AI 才靠谱”的经验。如果你对这套设计思路感兴趣我建议你先不要急着改别人的技能而是原封不动用一周感受一下哪些场景真的顺了、哪些场景还是别扭然后再根据自己工作流的特点做裁剪和扩展。一上来就大改往往改完发现不如原版顺手。3. 安装与引入两种方式跑通 Superpowers3.1 方式一直接把官方仓克隆到本地最直接的安装方式是把官方仓库克隆到本地再把技能目录放到你的 AI 应用能读取的位置。以我常用的 Claude 桌面版为例操作路径是这样# 进入你的 AI 应用配置目录 cd ~/.claude # 克隆技能仓库 git clone https://github.com/obra/superpowers.git skills # 确认目录结构 ls skills克隆完成后你会看到一个名为 skills 的文件夹里面就是各个技能的子目录。Claude 会读取这个目录里的技能元数据在合适的对话场景中自动激活。如果你用的是其他客户端原理是一样的路径换成你的应用对应的配置目录即可。需要注意两点一是如果你的配置目录里已经有同名文件夹先备份再替换别直接覆盖二是克隆之后建议把仓库固定到你验证过没问题的那次提交避免后续上游更新产生你不想要的行为变化。# 进到目录里固定到某个版本 cd ~/.claude/skills git checkout commit-id我自己的习惯是每两周拉一次上游更新然后跑一遍我在用的几个核心技能确认没有行为倒退再继续用在日常工作中。技能更新不像软件更新那么直观有时候上游改了一句引导语模型行为就可能有大变化所以我的态度是“勤更新但每次更新都要验”。3.2 方式二按需打薄只引入你需要的技能官方仓库里有不少技能但坦白说不是每个人都用得上全部。比如我一开始全量引入结果发现模型在对话里频繁被我根本不需要的技能干扰反而增加了不必要的触发噪声。后来我做了一次“打薄”只保留四个高频技能日常体验立刻干净了。打薄的操作不复杂把 skills 目录里不需要的文件夹删除只留下要用的。但为了将来能恢复我更推荐把官方仓库 fork 一份到自己名下在 fork 里删减然后把自己 fork 的版本克隆到本机。这样一来你既有自己的精简版又能随时从上游合并新改动。# 在自己的GitHub账号下fork官方仓库然后克隆自己fork的版本 git clone https://github.com/你的用户名/superpowers.git skills # 删除不需要的技能目录 rm -rf skills/用不上的技能名 # 以后想同步上游改动 git remote add upstream https://github.com/obra/superpowers.git git fetch upstream git merge upstream/main这里想给个比较个人的建议不要一开始就追求精简到极致。先全量用两周记录哪些技能你从没触发过、哪些技能触发后却帮了倒忙再动手删。只凭目录文件名判断“这个我用不上”很容易误删一个实际场景里很好用的技能。3.3 环境变量与程序化引入方案如果你不只是用桌面应用而是通过 API 或编程方式调用模型那你需要把 Superpowers 变成可程序化读取的规则集。官方仓库直接规定了这些技能应该被安装在何处以主流工具为例但你也可以按自己的需要通过环境变量指定技能目录路径# 通过环境变量指定技能目录位置 export SKILLS_PATH/path/to/your/superpowers/skills设置完成后你在语言模型 API 的 client 配置里加载这个路径让它在系统提示中引用对应技能文件。大致思路是把技能目录里的 SKILL.md 内容和模型当前任务拼接在一起实现按需加载。我这里给一段示例代码用 Python 写一个简单的加载器核心逻辑是从技能目录里读取主文件注入到 messages 里import os from pathlib import Path skills_dir Path(os.environ.get(SKILLS_PATH, ./skills)) def load_skill_context(skill_name: str) - str: skill_file skills_dir / skill_name / SKILL.md if not skill_file.exists(): return return skill_file.read_text(encodingutf-8) # 使用示例调用模型前把所需技能的上下文拼接到系统消息后 skill_text load_skill_context(writing-plans) system_prompt f 你是一个严格按照技能规范工作的AI助手。 当前技能规范如下 {skill_text} 这段代码只是一个雏形但思路是对的通过环境变量控制技能目录位置通过技能名按需加载内容然后拼接进 prompt。你完全可以根据自己的调用框架封装成更优雅的方式。4. 核心技能逐个拆解从日志到代码怎么用才有效4.1 日志记录技能逼着 AI 先理清“发生了什么”排查问题的第一件事永远是搞清楚发生了什么。很多 AI 对话里模型直接开始分析原因可它连完整的事件链都没梳理清楚给出的结论自然不靠谱。Superpowers 里的日志记录技能logging就是专门治这个毛病的它要求模型在处理问题前先把相关日志、错误信息、操作步骤完整复述一遍确认自己掌握的事实没有遗漏。实际触发时模型会先提取关键信息并整理成结构化摘要再基于摘要展开分析。你会发现它不再从一堆原始文本里“硬猜”而是先建立一份可信的“事实清单”。这套逻辑不仅对代码调试有效对任何需要溯源的场景都通用——运营分析、用户反馈排查、跨系统问题定位都适合先做事实清单。我用这个技能最深的体会是它治好了我“着急要答案”的毛病。以前我习惯直接把异常堆栈扔给模型追着问“哪里错了”它也能答但有时答非所问。现在它会先问我要完整上下文或者让我确认几个关键事实最后给出来的结论明显靠谱。4.2 时间追踪与核心记忆让 AI 拥有跨对话的连续性Superpowers 里有几项关于追踪和记忆的技能这可能是整个项目里最有“颠覆感”的设计。它用了一个很简单的机制在对话过程中模型按照技能要求把重要的信息、决定、待办事项写入对应的 markdown 文件。下次对话开始时模型读取这些文件就相当于“想起了”上一次的内容。机制本身没有任何魔法但它解决了一个真实痛点AI 对话的上下文不连续。以前我用 Claude 推进一个项目每天都要重新交代背景“我是谁、项目在做什么、现在卡在哪”这几十行话术浪费了大量 token 不说还常常说得不够完整导致它误解我的意图。用了记忆技能后这些背景都写进了我的记忆文件每次开工前我只需要说一句“先读一下记忆”它就能无缝接上进度。使用上的小技巧是记忆文件也要定期整理。技能虽然会不断往里写信息但它不会自动判断哪些已经过时了。我自己的节奏是每周抽十分钟看一眼记忆文件删掉已经完成的任务、更新仍然有效的目标。这十分钟换来的是后面几十次对话都基于准确的信息展开。4.3 正则表达式技能专业到你不需要背语法正则表达式是很多人的老大难问题我属于那种每次写正则都要查文档的人。Superpowers 的正则技能正则编辑改变了这个体验。它的核心逻辑是让模型把自然语言需求“翻译”成正则表达式然后通过多轮验证来保证准确性和边界情况。用一句大白话说你不需要亲手写正则你只需要清楚地告诉模型你想要匹配什么、排除什么、处理什么特殊情况。模型会基于你的描述生成表达式并配上测试用例做验证。比如我想从日志里提取用户 ID 和操作类型只需要把原始日志样例贴给它说清楚提取目标它就能生成一段可靠的正则和提取代码。但对这个技能我也有一点保留意见它虽然能写出准确的正则但如果你想长期维护这段代码你最好还是理解它的匹配逻辑。我的习惯是让模型在生成正则的同时给每一部分加注释这样下次维护时扫一眼注释就知道它在干什么不用重新猜。4.4 写计划与技能编写给自己的 AI 定义新能力Superpowers 中还有一项能力让我觉得拓展性很强让模型按照技能的结构化模板去编写新的技能文件。也就是说这个项目不只是给你一堆现成技能它还给了你一套“元技能”——教会模型怎么把你日常的高频操作沉淀成一份标准化的技能文档。实践下来想定义一个新技能你只需要描述这个技能的适用场景、工作流程、输入输出要求让它参考已有技能的格式生成 SKILL.md。生成后放到技能目录里下次对话就能自动触发。整个过程大概十几分钟比我以前写一套完整 Prompt 还要高效而且生成的质量更稳定。有一件事我要特别提醒技能文件不是越详细越好。拿到一份刚生成的技能文档先看看它是不是写得像“说明书”——如果是那大概率有问题因为真实可用的技能文件应该更像“操作约束”而不是“知识讲解”。我见过一些用户把技能文件写成了几千字的百科词条结果模型每次加载都会消耗大量上下文但行为却没有明显改善。好的技能文件一句话能约束模型行为的绝不用三句话描述。5. 真实使用中的高频问题与排查技巧5.1 技能不生效怎么办这是高频问题里最让人头疼的一个。你明明把技能目录放到了正确位置但跟模型对话时它就是不按技能要求来。我的排查顺序是先确认技能目录路径没错再确认文件名是 SKILL.md 不是 skill.md最后确认技能内容里的触发条件写得是不是太苛刻了。路径和文件名是新手最容易踩的坑。大小写、拼写、目录层级任何一处不对AI 应用都可能扫描不到到这个技能。触发条件的问题更隐蔽——如果技能文档里写了太多前置条件模型判断不满足条件时就不会激活它。我建议初始阶段把触发条件写得宽泛一些等确认技能能正常激活再逐步收紧。比如我最初用日志技能时它总不触发检查之后发现触发描述里写了“当出现日志或错误信息时”但实际对话里的错误信息没有“日志”两个字模型就不认为命中。我把描述改成“遇到任何异常、错误或不符合预期的现象时”触发就立刻正常了。5.2 模型行为“过度跟随”怎么调整技能生效了但模型的某些行为跑偏了。比如用了正则技能之后它连我随口问的一句话都要先建测试用例显得很啰嗦。这种情况不是技能本身的问题是技能描述和真实场景的匹配度不够。解决的方法很直接回到技能文件检查它定义的“触发条件”和“工作流程”。把只适用于复杂场景的步骤标注为“仅在必要时执行”把简单场景对应的快速路径写进去。模型是按照技能文件的引导来行动的你调整文件内容它的行为就会跟着变。这个特性也是技能系统比纯 Prompt 更让我喜欢的原因——调整是可预期、可回溯的。5.3 技能间互相干扰的处理技能多了之后可能会遇到两个技能同时想控制模型行为的情况。比如日志技能让它先列事实清单计划技能又让它直接输出步骤模型夹在中间不知道该听谁的。这种冲突在初始使用阶段不算少见本质是技能职责边界没划分清楚。我的处理思路是给技能划分“层级”如果某个技能是基础通用技能比如日志记录我就在其他技能文档里加一句约束——当该技能被激活时应遵循基础的日志事实确认流程如果两个技能属于平行关系则判断哪个技能更贴近当前对话的核心意图优先激活它。这个调整没有标准答案主要看你的工作流特点。我自己的经验是冲突往往意味着你的技能切分粒度不对——把两个高度相关的流程拆成了两个技能。可以考虑合并成一个在技能内部做分支比两个技能抢控制权要稳得多。5.4 典型问题速查表我把最常遇到的几类问题整理成了速查表方便你排查时快速定位症状可能原因解决动作技能从未触发目录路径错误或文件名大小写不对检查技能路径和 SKILL.md 文件名技能偶尔触发触发条件描述过于苛刻放宽技能场景关键词技能触发后行为不精准SKILL.md 工作流程描述模糊细化流程步骤加入检查清单两个技能行为冲突多个技能同时匹配当前场景明确技能优先层级或合并技能上下文占用过多技能文件被写成了百科说明书精简技能文件只留行为约束和边界条件跨对话记忆丢失记忆文件路径未固定或未读取确认记忆文件写入位置并在新对话中主动读取这几类问题在我实际使用 SUV 技能集的过程中都遇到过大多能在几分钟内解决。真正让我耗费时间最多的是“行为不精准”这一项——因为模型行为是否精准往往要多轮对话才能确认很难一步到位。好在这套系统的修复路径是确定性的改文件观察行为再改再观察。6. 进阶玩法自己动手写一个技能并纳入日常流程6.1 从痛点反推技能需求当你用熟了现成技能自然会冒出“要是它能这样就好了”的想法。这时候你就该自己动手写技能了。我建议的切入点不是凭空想一个技能而是从你日常高频且重复的场景里反推。举个实际例子。我经常需要把一段调研资料整理成结构化笔记以前每个项目都要手写一遍笔记格式要求——哪些信息要保留、哪些要舍弃、结构如何组织。后来我把这个场景写成技能里面定义了笔记的五段结构、信息来源标注位置、以及“不添加原文没有的信息”这一条约束。从那以后我整理笔记的效率提升非常明显而且每篇笔记的格式整齐划一。这个技能的定义过程大致是把“你希望它在什么场景下被激活”写清楚把“它按照什么步骤工作”写具体最后把“什么不能做”写明确。从痛点出发定义技能你写的技能天然贴合真实需求维护起来也有动力。6.2 一个极简技能模板和验收标准如果你想自己写一个技能这份极简模板可以直接拿来用# 技能名称 ## 触发场景 当用户提到……时自动激活本技能。 ## 职责与边界 - 本技能负责…… - 本技能不负责…… ## 执行流程 1. 先…… 2. 再…… 3. 最后…… ## 输出格式 - 结构…… - 长度…… - 语气…… ## 禁止事项 - 不能…… - 不能……写完之后拿三个问题来验收第一技能文件是否能在一分钟内读完第二覆盖的是行为规范而不是知识灌入第三边界是否清晰用户明确说“今天不按技能来”时模型能不能跳出规范。三个问题都过了这个技能就可以投入使用了。6.3 日常使用中的最佳实践最后分享三个我日常使用中验证过的最佳实践。第一技能文件建议纳入版本管理。我自己的技能目录本身就是一个 git 仓库任何修改都有记录出了问题随时回滚。第二坚持“每个技能都是独立的模块”思维。即使两个技能之间高度相关也保持目录独立通过相互引用来关联而不是把内容堆在一起。第三定期清理和复盘。每隔一段时间把没触发过的技能删掉把触发过但效果差的技能重写保持技能集的高信噪比。我看到很多用户把这个项目当成“装了就完事”的工具装完不再管过了一段又嫌不好用。实际上技能集更像是一个需要持续投入治理的“规则体系”它的价值上限取决于你对它的打磨程度。你花越多时间理解它的工作机制、调整它的行为边界它在实际工作中能帮你的就越多。我自己的做法是在每个项目结束或每个里程碑达成后花一点时间复盘 AI 在这个项目中的表现把“下次一定要让它注意”的点子写进技能文件。这样每一轮项目结束我的技能集都会比上一轮更贴合我的工作方式。这大概是我用 superpowers 这么久最受益的一条实践经验。