1. 先搞清楚superpowers到底是什么1.1 从一个“多余的问题”说起前两周有个技术群里有人问大家都在说superpowers这到底是装了个什么插件我当时的回答很简单——它不是某一个具体工具而是 Claude 在 Agent Skills 机制下诞生的一套“技能体系”而社区里最出圈的那个实现就是 GitHub 上托管的superpowers-skills/claude-code仓库。这里面的技能包skills覆盖了文档处理、浏览器自动化、数据分析、编码辅助等大量高频场景装好之后能让 Claude Code 自动获得一批“随叫随到”的专项能力。很多人第一次听到“技能”这个词会觉得抽象其实理解它最好的方式是想一下你用 ChatGPT 或者 Claude 网页版时每次都要在提示词里反复交代“你是专家”“请用 Python 处理”“请遵循某某格式”。可问题是交代得再细下次对话模型照样忘得一干二净哪怕同一段任务隔天再做你还得重新描述一遍。Agent Skills 干的事情就是把这种“一次性提示词”变成了“永久可复用的能力模块”装进 Claude 的工作区之后模型会自己判断什么时候该用哪个技能不需要你把背景知识塞进每一轮对话里。这个机制之所以叫 superpowers是因为它确实改变了 AI 助手的定位你装的技能越多它能独立完成的事就越复杂你不再需要一步步手把手告诉它该怎么操作。我自己的体会是从“跟 AI 对话”变成“给 AI 配技能包”这是一种思路上的跨越。下文会先把这套机制的原理讲透再带你从零走一遍安装、使用、自建技能包的完整流程最后把实战中容易踩的坑逐个拆开。1.2 Skills 的底层工作原理要理解 Skills关键要抓住三个东西SKILL.md、技能目录、渐进式披露Progressive Disclosure。SKILL.md是这个技能包的“说明书”有点像一个职位的岗位描述。它不是给你看的是给模型看的。里面用 YAML frontmatter 声明技能的name和description再用正文写清楚这个技能能做什么、不能做什么、典型用法长什么样。模型在对话过程中会读到这批技能的元信息当任务匹配某条 description 时它就会加载对应的技能包执行。技能目录则是技能的实体一般放在项目的.claude/skills/下或者全局的~/.claude/skills/下。每个技能一个独立文件夹里面除了SKILL.md通常还有scripts/放可执行脚本、reference/放参考资料、assets/放静态模板。这种“说明脚本参考”分离的结构是我觉得整套设计最聪明的地方——模型不需要一次性读完所有材料而是按需读取这就是渐进式披露先看摘要需要细节时再展开具体文件。我拿一个实际例子说明。假设你装了一个处理 PDF 的技能它的SKILL.md里 description 写着“适合将 PDF 文档转换为 Markdown、提取表格、合并拆分页面”。当你丢给 Claude 一个 PDF 文件说“帮我把里面的表格提出来”模型会识别这个任务匹配了该技能于是加载技能文件夹里的 Python 脚本按脚本规定的参数执行最后把结果返回给你。整个过程看起来像 AI 自己“学会了”PDF 处理实际是脚本和参考文件给了它具体方法。这套机制解决了传统提示词的两个核心痛点一个是能力不可沉淀换个对话就没了另一个是上下文污染你不想让模型每次处理 Excel 时都先读一遍“Excel 处理十大注意点”但现在这些注意点放在技能包里只在需要时才调出来对话的上下文窗口就清爽得多。1.3 资料来源与生态定位如果你上网搜“superpowers”大多数结果会指向一个名为superpowers-skills/claude-code的开源仓库。它本质上是社区驱动的技能合集收录了从文档转换、网页抓取、数据可视化到编码脚手架生成的一批高质量技能包。这个仓库的定位相当于 npm 之于 JavaScript、Homebrew 之于 macOS它未必是官方出品但在生态里已经成为事实上的“技能应用商店”。还有一点必须说明Claude 官方提供的技能创建与使用能力Agent Skills是这套生态的底层土壤。也就是说你既可以完全不用社区仓库自己从零写技能也可以直接把别人写好的技能包克隆下来用。官方机制负责“运行”社区仓库负责“供给”两者配合才能形成完整的体验。了解这个关系你就知道为什么“安装 superpowers”在网络上有各种不同教程本质都是在往skills目录里铺技能包而已。提示如果你是第一次接触这个概念不要一上来就研究仓库里每一个技能。把安装流程跑通再挑两三个高频技能用熟远比囤积大量技能更有效。技能多了确实能办事但初期会增加模型判断的负担和调试难度。2. 安装和引入技能其实就三步2.1 明确你要装到哪一层在开始动手指之前先搞清楚“安装位置”这个概念因为很多人错就错在这。Claude Code 的技能目录分两种项目级和用户级。项目级目录是你的项目/.claude/skills/这个目录下的技能只有在你进入这个项目时才会被 Claude 加载。它的优点是隔离干净适合给特定项目定制能力比如你的电商项目只需要订单分析和库存预测那就只在这放这两个技能其他项目完全不受影响。用户级目录是~/.claude/skills/不管你打开哪个项目只要是用同一个用户身份跑的 Claude Code这些技能都会被自动加载。适合放那些跨项目通用的能力比如 PDF 转换、Excel 处理、浏览器自动化这类“什么时候都可能用到”的技能。我的建议是通用技能放用户级专用技能放项目级。这个分法和编程里依赖管理讲究 devDependencies 与 dependencies 分离是同一个道理——明确边界后面维护起来才不会崩溃。2.2 上手安装的三种常见姿势安装 superpowers 技能包我试过比较可靠的三种方式这里按推荐程度排个序第一种是直接使用 Claude Code 的插件市场机制。目前 Claude Code 支持通过对话里的/plugin命令管理插件你可以先把superpowers-skills/claude-code仓库添加到插件市场再从中浏览并安装需要的技能包。装完它会自动落到正确的 skills 目录里不需要手工复制文件。第二种是从 GitHub 克隆整个仓库再手动复制需要的技能文件夹。这个方法最朴素也最不容易出问题。命令大概是git clone https://github.com/superpowers-skills/claude-code.git cd claude-code cp -r skills/pdf ~/.claude/skills/注意这里我把仓库地址写成了示意路径实际操作时以仓库 README 为准。复制过去之后再检查一下目录结构确保~/.claude/skills/下是“以技能命名的文件夹”而不是把整个仓库目录直接塞进去。第三种是只用单个技能如果你只需要其中一个技能也可以把那个技能文件夹单独下载下来放到指定目录。GitHub 网页端支持直接下载某个子目录的 zip 包或者用svn export这类工具单独拉取子目录。这种方式适合磁盘洁癖用户但说实话用起来和复制整个仓库差别不大看个人习惯。2.3 安装后的环境检查装完不等于能用我强烈建议你做一次“环境体检”。打开 Claude Code输入下面这条命令/skills如果环境正常你会看到一个已安装技能列表每个技能对应它的名字和简介。如果列表里什么都没有大概率是路径错了或者 SKILL.md 文件没有被正确解析。还有一个更快的验证方式直接给 Claude 一个匹配场景的任务比如装了 PDF 技能就丢给它一个 PDF 文档让它提取内容它如果主动调用技能说明安装成功如果它无视技能、用普通对话方式处理那你要检查 description 是否写得足够触发。我之所以强调环境体检是因为很多人辛辛苦苦装了一大堆目录但模型一点反应都没有最后发现只是文件路径放错层级或者技能文件夹里缺少 SKILL.md。这些问题一开始不查清楚后面排查起来相当浪费时间。注意不要同时放两个 description 高度相似的技能到同一个目录比如一个“PDF 转 Markdown”和一个“PDF 内容提取”它们的触发描述互相重叠模型就会陷入选择困难甚至随机调用一个不合适的。初期装技能尽量保证功能垂直不重叠。3. 几个值得装的技能拆开看3.1 文档处理的实战价值Superpowers 仓库里最受欢迎的技能之一就是 document skills包括 PDF、DOCX、XLSX 的处理。这类技能的本质不是“让 AI 懂文档格式”而是提供一个写好解析脚本的脚手架让模型按固定流程操作文档。拿 PDF 技能举例。它的目录里一般会有scripts/convert.py和scripts/extract_tables.py。当你说“帮我把这个 PDF 转成 Markdown”Claude 会读取 SKILL.md 中对应场景的用法说明然后调用 convert.py 脚本脚本内部无非是pypdf或pdfplumber这类库在做底层转换但关键点是——你不用在提示词里写“请安装 pypdf”“请写一个提取表格的脚本”技能包把这些都包好了。这个技能的实际场景有多广呢我手里的一个客户每周都要把十来个 PDF 格式的报价单统一转成结构化 Excel。以前靠人工复制粘贴要半下午现在把 PDF 全丢给 Claude Code让它跑一遍技能流程二十分钟输出一张规整表格。误差肯定有但排错成本远低于纯手工。DOCX 和 XLSX 技能同理。处理 Word 时它可以帮你批量调整格式、提取批注处理 Excel 时它可以把一堆 Sheet 合并、按规则清洗数据、生成汇总透视表。这些任务如果直接扔给模型它会因为不知道用哪个库、要不要保留原格式而反复试探有技能包之后就变成了“照着脚本执行”的确定性流程输出质量稳定得多。3.2 浏览器自动化的本质是“把规则交给脚本”另一个容易被忽视但实际使用率很高的技能是 browser 自动化技能。我看到不少开发者对它有误解以为它是“用自然语言让 AI 浏览网页”这其实只说对了一半。它真正的价值是让你可以用自然语言去驱动一套浏览器自动化脚本而这套脚本操作浏览器的方式跟我们平时手写的 Playwright 或 Puppeteer 测试代码没有本质区别。它的核心机制通常是基于 Chrome DevTools ProtocolCDP让 Claude Code 能够操控一个真实浏览器实例。你告诉它“打开某网页找出所有文章标题抓取并汇总成 Markdown”它会访问页面、等待渲染完成、提取 DOM 节点数据最后输出结果。我实际测试过用这套技能做“每日竞品价格监控”让 Claude Code 定时打开竞品页面把价格信息抓取下来写入表格。这个需求以前我得自己写脚本、维护选择器还容易因为页面改版而失效。有了技能包改版后只需要告诉 Claude“选择器失效了帮我重新定位价格元素”它就能基于新的页面结构自动调整代码。这种“可维护的自动化”让浏览器技能的实用性比大多数人想象中高很多。做自动化有个绕不开的问题网站登录态。技能包通常不会帮你处理登录你需要提前用浏览器登录并保持 session或者把 cookie 导出成文件让脚本读取。第一次用浏览器技能时我建议先跑一个简单任务比如抓取一个无需登录的静态页确认环境配置无误再去碰需要登录的站点这个循序渐进能省掉大量定位问题的时间。3.3 数据分析技能帮你省掉“导入导出的等待”还有一类技能值得专门说说——数据分析类。超级技能仓库里有不少和 pandas、matplotlib 相关的包它们的作用不是让模型去“画图”而是把数据分析变成一套标准化流程读取数据 → 清洗 → 统计 → 出图 → 输出结论。我最常用的一个场景是 CSV 文件快速探索。以前拿到一个新的 CSV我总得先写脚本跑df.describe()或者df.info()再手动看看有哪些列、哪些空值、哪些异常分布。现在直接丢给 Claude Code“用数据分析技能帮我看看这个文件总结字段含义、空值比例、异常值和分布特征。”它就会跑一段探索性数据分析脚本把结论用自然语言组织回来效率高不止一个量级。需要注意的是这类技能对数据文件的大小和格式有要求。超大 CSV好几个 GB直接跑脚本容易把内存撑爆技能包本身对这种场景的优化也有限。如果你要处理的是大规模数据还是老老实实先做采样或分块把数据切到合理规模再交给技能处理。另一个常见坑是编码问题很多业务系统导出的 CSV 是 GBK 编码技能包默认可能按 UTF-8 读这时候你要在任务描述里明确提一句“这个 CSV 是 GBK 编码”模型就会自动调整读取参数。3.4 技能能力对比速查技能类别典型场景底层核心依赖使用门槛推荐理由PDF/文档处理格式转换、表格提取、合并拆分pypdf、pdfplumber、python-docx低高频刚需安装即用浏览器自动化网页抓取、自动化操作、价格监控Playwright / CDP中替代写死的爬虫脚本可维护性高数据分析数据探索、清洗、可视化pandas、matplotlib低自然语言替代重复性数据探索代码编码辅助脚手架生成、批量重构、测试生成各类语言工具链中适合作为团队工作流的一部分这个表格只是我按自己的使用频率做的粗略划分。Superpowers 仓库本身持续在更新隔一段时间就会冒出新技能所以真要决定装哪个核心标准还是回归你自己的场景需求。别为了“酷”去装你用不上的技能每多装一个模型在判断触发时就要多一次匹配运算——这个成本虽然不大但代码库整洁性也是专业度的一部分。4. 自己写一个技能没有那么玄4.1 从“脚本”到“技能”的转换思路很多人一看 SKILL.md 的 YAML frontmatter 就头大觉得这是某种高深的配置语言。其实你完全可以先不碰 YAML从一段已经跑通的 Python 脚本开始慢慢把它“包装”成一个技能。我自己第一次写技能就是从一段处理 Excel 的 Pandas 脚本起步的。脚本功能很简单读入一个销售明细 CSV按月份汇总销售额输出一张新的汇总表。以前我每次都要从历史代码里翻这段脚本粘贴过来改几个路径参数再跑。后来想通了何不让 Claude 自己记住该怎么做于是我做了一个技能文件夹结构大概是这样sales-summary/ ├── SKILL.md └── scripts/ └── summarize_sales.pyscripts/summarize_sales.py就是我那段已经跑通的脚本稍微改造成接收命令行参数的形式python scripts/summarize_sales.py --input sales.csv --output summary.csvSKILL.md 里则写清楚当用户给出销售数据文件时运行这个脚本做月度汇总并解释输出结果。就这么简单。这里有一个核心思路值得强调先有脚本再有技能。脚本是可验证的跑通了才谈得上让 AI 调用。很多人一上来就想让 AI “凭空学会一个多复杂的任务”这是对技能机制的错误理解——技能不是让模型变聪明而是给它一个可靠的执行路径。4.2 SKILL.md 该怎么写才容易被模型调用SKILL.md 的写法基本决定了这个技能会不会被模型在关键时刻想起来。最容易踩的坑是 description 写得像产品宣传稿比如“帮助用户高效处理数据”——这话没有任何触发价值因为“处理数据”这个描述可以匹配到几乎任何对话。我总结了一条有效的描述公式任务类型 触发条件 限制词。举个例子比起“处理销售数据”更好的写法是description: 当用户提供销售明细 CSV至少包含日期和金额列并要求按月汇总分析时使用。不适用于非表格类数据分析请求。这样写的好处是给模型划清了明确的触发边界什么样的输入进来该用你这个技能什么样的不该用。模型在每轮对话里都要做一次调用决策描述写得越清晰决策准确度越高。正文部分我还会写一节“执行步骤”比如先检查输入文件是否存在、再运行脚本、最后总结输出。有时候我还加“注意事项”把这脚本的已知边界写清楚比如“该脚本只能处理 GBK 或 UTF-8 编码其他编码会报错”。这些信息会让模型在异常情况下有据可依而不是茫然地输出一段错误日志。4.3 渐进式披露是最容易忽略却最重要的设计我见过不少人写技能时把 2000 字的详细操作手册直接塞进 SKILL.md。这个做法短期内看起来没问题但它会让每次对话都要读一遍这 2000 字哪怕这次任务根本不需要涉及操作细节。如果你装了 20 个技能每个都这么干模型光读取元信息就能消耗相当一部分上下文窗口。渐进式披露的设计原则概括成一句话就是SKILL.md 里只放摘要和入口详细内容放在 reference 目录按需读取。我实际的做法是——SKILL.md 只保留三部分frontmatter 元信息、一段概述、三到五个最常用的使用示例。然后我在reference/下放一个implementation.md里面写完整的参数说明、脚本细节、调试指南。当任务深入时模型会自己决定要不要去读implementation.md。这样做的收益在你同时装了大量技能时会非常明显。输入给模型的原始 token 变少了、模型“想”得更准了、而且每个技能的维护也变得简单——改细节只需动 reference 文件SKILL.md 的触发逻辑完全不用变。提示写完技能后一定要实测三到五个不同表述的任务。你写 description 时用的词和用户实际表达的词往往有差异。比如你写的是“月度汇总”用户可能会说“统计一下这个月的情况”模型能不能把这两者关联起来是最值得反复验证的点。5. 使用中踩过的坑和排查方法5.1 技能装好了就是不生效问题出在哪最让我头疼的安装问题不是报错而是“一切正常但模型就是不调用技能”。这通常有三种原因我按出现频率排一下第一种是 description 写得太宽泛。比如形容一个 PDF 技能时写了“处理文档”结果对话里用户让 AI 写一篇 Word 文档模型觉得这个技能也能干就错误加载了。反过来如果你把 description 写得特别窄用户换个说法表达同一个需求模型又认不出来。所以 description 要反复校准“宽度”和“锐度”得同时兼顾。第二种是技能目录位置不对。项目级技能放在.claude/skills/全局技能放在~/.claude/skills/这两个路径我都见过有人放反。更隐蔽的问题是技能文件夹套了一层多余的父目录导致 SKILL.md 不在技能文件夹的直接子级模型扫描的时候根本找不到。第三种是 Claude Code 版本过低。技能机制上线后经历过几次迭代早期版本对 frontmatter 的解析兼容性不好。升级到最新版本多数兼容性问题会自行消失。5.2 上下文膨胀和权限问题技能装多了之后下一个容易遇到的坑是上下文开销变大。虽然渐进式披露能缓解但我见过一个极端案例有人的技能包里光是 description 加起来就有一千多 token。这种情况下每轮对话模型都要把这堆 description 过一遍浪费明显。排查方法很简单/skills命令看一眼加载信息如果元信息总量过大就要精简 description或者删掉极少用到的技能。权限问题也很常见主要体现在脚本执行失败。技能脚本通常需要读取文件、运行 Python 或 NodeClaude Code 对脚本执行是有权限管理的。如果你遇到“脚本被拒绝执行”之类的提示去确认一下 Claude Code 的权限设置给技能目录或脚本执行授信。还有一个我印象深刻的坑不同技能的脚本互相污染。比如两个技能文件夹里都scripts/helper.py但内容不同模型在某个场景下加载了错误的 helper。这种问题在自建技能时尤其容易发生。规避办法是一个技能一个独立目录脚本命名带上技能前缀例如sales_summary_tool.py不要所有技能都用通用名。5.3 版本更新和团队协作时的维护经验Superpowers 仓库和 Claude Code 本身都在快速迭代。我的经验是不要用“装完不管”的心态对待技能。每隔一两周去仓库看看有没有更新更新时注意技能包的 breaking change 说明很多技能改版后参数结构会变SKILL.md 里的示例可能也需要同步调整。如果团队里多人使用同一套技能我更推荐用 Git 管理技能目录把~/.claude/skills/做成一个独立仓库或者至少写一个 bootstrap 脚本一键克隆并安装所有技能。这样新同事入职时不需要一个个技能手动装跑一遍脚本就全齐了。配合代码评审技能更新也能留下痕迹出了问题方便回溯。问题现象可能原因快速排查路径技能安装后列表为空路径不对 / SKILL.md缺失检查目录层级确认文件在技能文件夹直接子级模型从不调用已装技能description 太泛或太窄重新打磨描述用至少三条不同表述实测技能偶尔加载错误多个技能 description 重叠删掉低价值技能或细化触发条件拆开边界脚本执行报权限错误Claude Code 脚本权限受限检查权限配置对技能目录或脚本目录授信上下文消耗异常增大SKILL.md 内容过长 / 技能过多把细节移到 reference精简 description技能更新后行为异常参数或目录结构变更到仓库看 changelog同步更新 SKILL.md 示例写在最后的一点实际感受从第一次接触 superpowers 到现在我最大的感受是它的价值不在于某一个技能有多厉害而在于它把“给 AI 加能力”这件事变成了一个工程化的流程。以前我遇到重复性任务第一反应是写脚本脚本写完还要维护现在我会先想有没有现成技能没有的话就写一个技能包让它替我记住怎么做。这个转变本质上是从“教 AI 做事”到“给 AI 配工具”的思维升级。如果你准备开始尝试我给的建议很简单先选一个最常遇到的重复任务比如 PDF 转表格或销售数据汇总照着上面的流程装一个技能或自己写一个用一周时间看它是不是真的帮你省了时间。用顺了再逐步扩展技能库。一开始别贪多把两三个高频技能用透比装二十个吃灰技能有价值得多。这套机制还在快速进化现在积累的实践到后面大概率都能复用得上。