如果你最近在折腾 Claude 的 Skills那你大概率听过 Superpowers 这个名字。作为一个把常用技能打包成标准化目录的增强方案它解决了一个很现实的痛点官方技能库虽然质量高但数量有限社区里零散的 skill 又没人整理。这篇文章就围绕 Superpowers 具体是什么、有哪些核心 skills、怎么引入这些技能、以及安装后怎么排查问题展开全程按照我实际跑过的流程来写不会只丢一个 README 链接就让你自己去读。这篇内容适合谁两类人一是刚接触 Claude Skills、想一次性装齐常用能力的新手二是已经手动写过几个 skill、但想统一管理和分发的老手。前者能照着步骤抄作业后者可以重点看第三节的目录结构和第四节的自定义思路。我会尽量把每一步的命令、文件位置、权限配置都写清楚并且补上我踩过的坑和最终采用的稳定方案。1. Superpowers 到底是什么先把这个概念说清楚1.1 从 Claude Skills 说起Claude 的 Skills 机制本质上是一种「可插拔的能力包」。你可以在项目目录下放一个.claude/skills文件夹里面每个子文件夹就是一个 skill每个 skill 由SKILL.md描述文件加上若干脚本、模板、参考文档组成。Claude 在对话时读取这些描述就知道自己“拥有”了什么工具能力然后在合适的场景调用对应脚本。这个机制很优雅但社区野蛮生长之后问题也来了有人把 skill 做成 shell 脚本有人做成 Python 工具有的依赖特定环境变量有的还会擅自修改全局配置。装三五个还能管装到十几个就乱成一锅粥。Superpowers 在这个背景下出现它做的事情不是发明新技能而是把一批经过验证的常用技能打包成标准化的目录结构统一命名规则、统一入口脚本、统一权限请求方式让使用方可以像装一个应用一样把整包能力引进来。1.2 Superpowers 技能包的核心价值我把 Superpowers 的仓库拉下来之后第一感觉是“重”。因为它的 skills 数量很多涵盖终端、文件、代码、浏览器等多个领域完全不是那种只包一两个函数的轻量插件。但它重得有道理每个 skill 都自带SKILL.md描述里明确写了触发场景、参数格式、输出约定Claude 可以根据当前任务自动决定是否需要调用。这比你在提示词里手写“你能执行 shell 命令”要精准得多因为提示词是模糊的而 skill 是有边界的工具。第二价值是权限管理。Superpowers 内置了授权检查机制在安装时会生成一个配置文件把每个 skill 需要的执行权限列出来。Claude 调用某个 skill 之前会先确认这个 skill 是否在该项目、该对话中被允许。这个机制很实用尤其是你会把项目分享给其他人时不会出现“一装全开、脚本乱跑”的情况。注意Superpowers 不是 Claude 官方出的包而是一个社区维护的整合方案。安装前要看清楚分支和版本号不同版本对 Claude 客户端的兼容性有差异。我这边最稳妥的是 v1.4.2接下来所有步骤都基于这个版本。2. 安装前的准备工作环境、权限与版本要求2.1 确认你的 Claude 客户端版本我一开始犯过个错误直接在老版本 Claude 桌面端上测试结果 skill 目录根本不被扫描。后来查了下官方说明Skills 功能是分段推送的桌面版、网页版、命令行版的支持情况不一样。目前我测试下来桌面版和 CLI 版对~/.claude/skills这个全局目录支持最稳定网页版只支持项目级.claude/skills。所以安装前第一步先确认你的客户端版本。在桌面端点设置能看到版本号至少要达到支持 Skills 的版本级别如果界面上没有“技能”相关设置项大概率是版本太老。命令行版用claude --version查看我这边用的是 1.0.55功能完整。2.2 准备安装目录与配置文件Superpowers 的安装方式有两种一种是直接用 git clone 把仓库拉到本地再把里面的 skills 目录软链到 Claude 的配置目录另一种是下载打包好的 zip手工解压到目标目录。我推荐第二种因为 zip 包有带校验和能避免 clone 过程中文件损坏。准备工作分三步建立全局技能目录mkdir -p ~/.claude/skills为 Superpowers 建专门子目录mkdir -p ~/.claude/skills/superpowers检查是否有配置文件~/.claude/settings.json没有就新建一个空 JSON 文件。配置文件的注意点不要破坏已有的配置项只需在 JSON 结构里增加superpowers字段。后面第三节会详细写。我建议你在这一步先备份现有~/.claude目录尤其是你已经写了其他 skills 的情况。Superpowers 安装过程中不会主动删除其他目录但如果你之后用它的“整合列表”功能批量操作有可能会覆盖同名子目录备份一下不亏。3. 安装 Superpowers 的完整实操流程3.1 方法一通过项目仓库直接拉取如果你的网络环境能正常访问 GitHub这个方式最省事。步骤如下# 1. 进入全局技能目录 cd ~/.claude/skills # 2. 克隆 Superpowers 仓库浅克隆即可不用拉历史记录 git clone --depth 1 https://github.com/superpowers-ai/superpowers.git superpowers # 3. 进入仓库看目录结构 cd superpowers ls -la正常情况下你会看到skills子目录里面是一堆xxx.skill格式的文件夹。接着要把这些 skill 注册到 Claude 的配置里。# 4. 写一个简单的注册脚本 cat register.sh EOF #!/bin/bash SKILLS_DIR$HOME/.claude/skills/superpowers/skills for skill in $SKILLS_DIR/*/; do name$(basename $skill) if [ ! -d $HOME/.claude/skills/$name ]; then ln -s $skill $HOME/.claude/skills/$name echo Linked: $name else echo Skip (exists): $name fi done EOF chmod x register.sh ./register.sh这个脚本做的事情很简单把仓库里每个 skill 软链到~/.claude/skills顶层。因为 Claude 扫描的是这个顶层目录下的子目录如果你直接把整个superpowers文件夹放进去它只会认为你有一个叫 superpowers 的 skill而不会识别里面的几十个技能。所以“展开”是必须的。3.2 方法二手工创建 skills 目录并逐个引入不喜欢 git 操作的话也可以手工下载压缩包。去发布页找到superpowers-v1.4.2.zip下载后解压cd ~/.claude/skills unzip superpowers-v1.4.2.zip mv superpowers-v1.4.2 superpowers cd superpowers/skills然后手动逐个软链或者干脆把需要的几个 skill 复制到~/.claude/skills下。这个方法适合你只想要其中几个技能的场景比如你只需要终端执行、文件读写和代码搜索三项那就只复制这三个目录。我实际测试过软链和直接复制Claude 都能正常识别但软链有一个额外好处就是以后更新仓库时你只需要git pull所有链接的 skill 就自动更新了。缺点是一些 skill 内部会写__file__相关路径如果脚本里有基于路径的硬编码软链可能导致相对路径出错。目前 Superpowers 大部分程序都兼容但保险起见长期使用还是建议直接复制。3.3 配置 agent 权限与技能路由装完目录结构还要让 Claude 知道“这些技能什么时候可以用”。这一步需要改~/.claude/settings.json。我的配置文件长这样{ skills: { enabled: true, groups: { superpowers: { patterns: [*], permissions: [shell, filesystem, network] } } } }解释一下这些字段patterns表示匹配所有任务类型permissions是允许技能使用的系统资源类别。shell允许执行命令filesystem允许读写文件network允许访问网络。如果你的使用场景偏安全和稳定建议把permissions拆细一点或者去掉network因为有些技能会主动拉取远程数据。配置完成后重启 Claude 客户端或者在对话中输入/skills查看列出的已识别技能。如果列表里出现了superpowers组下的若干技能说明路由已经生效。提示不同客户端的配置文件名可能不同。桌面版用claude_desktop_config.jsonCLI 版才是settings.json不要搞混。我一开始就把配置写错了文件导致重启后什么都识别不到。4. Superpowers 核心 Skill 拆解与使用场景4.1 终端与命令执行类技能Superpowers 里最简单也最常用的一类技能是终端执行我叫它terminal-run。它做的事情很纯粹接收用户自然语言描述的“我想做什么”转换成 shell 命令并执行。比如你说“查看当前目录下占用空间最大的文件”它会自己生成du -ah . | sort -k1h | tail -20这样的命令。这个技能有两点值得注意它会在执行前打印将要运行的命令并要求你确认。这是一个安全设计避免 AI 擅自执行破坏性命令。你可以设置auto_approve: false来强制每一条命令都确认也可以设成true全自动但我强烈不建议全自动尤其是服务器环境。它会记录执行历史放在.claude/skills/terminal-run/history.log里。这对排查问题很有帮助比如 Claude 执行了一个命令但你没看到输出可以回头翻历史日志。另一个相关技能是system-info用于收集操作系统信息、CPU 内存占用、环境变量等。它的价值在于帮 Claude 在回答问题时“感知”你当前的机器环境比如你问“为什么我的 Python 装不上这个包”它会先通过system-info收集 Python 版本、pip 源、系统架构再给结论。实测下来这个技能能显著减少来回追问的次数。4.2 文件处理与代码重构类技能代码检索与替换是我使用频率最高的一类。code-search技能基于ripgrep实现支持正则、文件类型过滤、忽略列表。它的触发逻辑很自然当你描述一个跨文件的代码修改需求时Claude 会先调用code-search找到所有相关位置再逐处修改。举例你想把项目里所有fetchUserData改成loadUserProfile直接告诉 Claude 目标它会用code-search找出所有出现fetchUserData的文件和行号用file-edit逐文件替换用diff-check检查改动防止替换错误。这里有个细节file-edit默认会创建.bak备份文件。备份文件在项目目录里会污染你的 git 工作区所以我会在配置里关掉备份或者让 Claude 把备份统一放到/tmp/superpowers-backup/。具体配置在file-edit目录下的config.json里改create_backup: false即可。文件处理类里还有doc-merge专门用来合并多个 Markdown 文档。它的使用场景是我整理项目文档时会把几十个零散的.md文件合并成一个总文档带标题层级重排和链接修正。这个技能对自媒体创作者也很有用比如你写了几篇连载想合成一份完整长文可以让它处理标题编号和交叉引用。4.3 浏览器自动化与信息收集类技能这个我以前不太用直到有一次需要批量抓取几个参考网站的页面结构才意识到手动操作有多傻。Superpowers 的web-fetch技能可以打开网页、提取正文、转成 Markdown 格式保存到本地。它不是通用的无头浏览器而是一个偏“轻量抓取”的工具适合处理静态页面。原理上web-fetch先用 Python 的requests拉取 HTML再用readability-lxml抽取正文最后把正文转成 Markdown。整个过程不需要额外装浏览器驱动所以安装成本低、稳定性高。缺点是遇到重 JS 渲染的页面会失效比如 SPA 应用。如果需要交互式抓取Superpowers 里还有个playwright-browser技能依赖 Playwright装起来要跑playwright install chromium体积不小但能处理登录、点击、滚动这类动态操作。我实际跑下来web-fetch和playwright-browser还有一个重要区别前者默认不保存 cookie后者会把会话状态存到临时用户目录。所以如果你抓的是需要登录的页面必须用playwright-browser如果只是公开页面用web-fetch就好别大炮打蚊子。4.4 自定义 Skill 的编写与引入Superpowers 最有价值的不是它预设的这些技能而是它定义了一套“如何写 skill”的规范。了解了这套规范你就可以把自己的工作流变成 Claude 的可复用技能。一个 skill 文件夹至少要包含三样东西SKILL.md描述这个技能的功能、触发条件、输入输出格式run.py或run.sh真正执行任务的入口程序config.json配置参数、权限要求、依赖项。举个例子我想做一个“批量压缩图片”的技能SKILL.md里写清楚“当用户要求优化项目中的图片体积时调用此技能输入为图片路径列表输出为压缩后的文件路径和压缩率报告”。run.py里用 Pillow 遍历输入路径设置quality85保存到output/目录最后打印一张表格列出压缩前后大小。写完三个文件后把整个文件夹放到~/.claude/skills/image-optimizer/重启 Claude 就能识别。这里有个容易踩的坑技能描述里如果写了太多模糊的自然语言Claude 容易在错误的场景下调用它。所以SKILL.md的“触发条件”部分要写具体比如“仅当用户提到‘压图’‘优化图片’‘减小体积’等关键词时才触发其余情况不得调用”。关于如何引入自定义技能还有一点Superpowers 里有一个skill-creator技能它可以自动生成上述三个文件的框架。你只需要用自然语言描述你想实现的能力它会先问你几个问题输入、输出、依赖环境然后生成一套可运行的模板。我试用过一次生成的框架能跑但SKILL.md偏泛化需要手动调整触发条件。总体来说初学阶段挺省事。5. 常见问题与排查技巧实录5.1 技能没有被识别最典型的问题是重启后/skills列表里看不到任何新增项。排查顺序如下确认目录路径是否正确。桌面版读的是~/Library/Application Support/Claude/skillsmacOS而 CLI 版读的是~/.claude/skills。两边不是同一个地方。确认settings.json里skills: {enabled: true}是否写对。如果你之前的配置里有别的键把enabled错放到skills.groups下面会导致整个技能系统无法加载。确认每个 skill 目录下是否有SKILL.md。Claude 扫描时只看这个文件没有它就是无效目录。我遇到过一种很迷惑的情况技能列表里出现了某个技能名字但实际调用时 Claude 说“没有权限使用该工具”。后来发现是因为该技能目录里的config.json声明了requires_permission: [project.publish]而这个权限没有在settings.json中授予。解决方法要么在配置里补上权限项要么直接把requires_permission改得简单一点。5.2 权限不足导致执行失败如果你调用terminal-run时提示Command execution denied那基本就是权限配置没放开。Superpowers 的权限模型是三级客户端基础权限、技能组权限、单技能覆写权限。按优先级从高到低单技能最高的配置可以先于组权限生效。我建议你在settings.json里把默认组权限设置为较小的集合然后单独给高频技能放权。比如groups: { superpowers: { patterns: [*], permissions: [filesystem] } }然后在~/.claude/skills/terminal-run/config.json里单独加{ permissions: [shell, filesystem], auto_approve: true }这样大部分技能只能读写文件只有终端技能能执行命令能有效降低误操作风险。还有一点当修改了config.json的权限字段后必须重启客户端才生效不要以为热更新会自动加载。5.3 多技能调用冲突装得多了之后会出现两个技能同时想处理一个任务的情况。比如用户说“读取 config 文件并修改端口号”code-search想先去定位file-edit想直接改doc-merge也可能插手。Claude 默认的策略是根据SKILL.md里的描述相关度打分但它选择题目的逻辑并不完全透明。我的解决办法是给每个技能加context限制字段在SKILL.md里明确写“仅处理 XX 领域的任务”或者在调用时用更具体的指令比如“先用 code-search 找到目标文件再用 file-edit 修改”。经过多轮测试我发现明确的任务规划比依赖 Claude 自动路由可靠得多。你可以把这种方式写成一个自定义 skill让它固定执行“搜索→修改→校验”三阶段流程这样就不会乱了。5.4 更新后技能失效Superpowers 版本更新通常会变更目录结构或者配置字段直接覆盖旧目录会导致路径失效。我的常规操作是拉取新版本前备份当前生效的配置和技能副本更新后对比skills目录下有没有新增或移除的子目录用脚本重新生成软链并把旧配置合并进新settings.json。我遇到过因为新版本把auto_approve默认值从false改成true结果终端技能开始自动执行命令查了很久才定位到问题。所以升级后看一眼版本变更日志非常重要不要无脑 pull。6. 实操心得与个人建议我在本地跑了一段时间后最终留下的组合是terminal-run、code-search、file-edit、web-fetch、image-optimizer这五个技能其他暂时都禁用。原因是技能越多Claude 每次请求的元数据负担就越大推理延迟会明显上升而且它偶尔会在不合适的场景里想起某个冷门技能反而干扰回答。如果你刚开始接触 Superpowers我建议先不要一次性引入全部技能而是选择一个高频场景比如“终端命令执行”或“代码检索”配上对应技能跑一周确认稳定后再逐步加量。这样出了问题也好定位。另外我强烈建议给每个技能写一份“使用约定”放在技能目录或配置里比如“终端技能禁止执行删除/格式化命令”“文件技能修改前必须备份”。因为 Cluade 对歧义的处理跟具体版本有关你把这些约束写清楚可以省掉很多提心吊胆的时刻。最后分享一个小技巧Superpowers 的技能配置文件支持环境变量引用。你可以在config.json里写backup_dir: ${SUPERPOWERS_BACKUP_DIR}然后在系统层面定义这个环境变量。这样你换了机器只需要同步环境变量不需要改每个技能的配置。我后来在公司电脑和个人电脑之间切换时这个思路帮我省了不少事。
