1. 项目概述当“187K star”的超级能力撞上真实工作流你点开 GitHub看到那个标着187K star的superpowers仓库心里一热——这不就是传说中能自动写代码、读文档、调 API、甚至帮你写周报的“AI 工具链”标题里写着“我用了三个月”语气还带点调侃“没你想的那么香”。这不是营销号这是个真正在一线用它改需求、修 Bug、赶 Deadline 的人写的实话。我就是那个“我”。过去三个月我把superpowers拆开揉碎装进自己每天打开十几次的 VS Code 里配到本地跑着 Llama-3-70B 的 LM Studio 上连上公司内网的 Confluence 和 Jira也试过在 Ubuntu 22.04 的 CI 服务器上静默运行它。结果它确实能干很多事但不是靠魔法而是靠你亲手拧紧每一颗螺丝。核心关键词就三个superpowers、Claude Code、skill——它们不是并列关系而是一套分层结构superpowers是骨架Claude Code是驱动引擎skill是可插拔的肌肉。你搜到的那些热词——“skill 编码247”、“diplay github”、“claude code 调用 lmstudio 的本地模型”、“vscode 配置 claude code”——全都是这个结构里某一颗螺丝松动时发出的异响。这篇文章不教你“三步安装”而是带你回到那个最朴素的问题当你把一个 star 数破十万的开源项目放进真实工作流它到底在替你做什么又在悄悄要求你付出什么适合谁看如果你是刚听说superpowers想试试水的前端新人或是被老板催着“搞点 AI 效率工具”的技术负责人又或是像我一样在skill目录里删了又建、建了又删、反复重写SKILL.md的实践者这篇就是为你写的。它不承诺“开箱即用”但保证让你在动手前看清所有接口、依赖和隐藏成本。2. 核心架构拆解superpowers 不是软件是协议层2.1 为什么说 superpowers 本质是“协议”而不是“应用”很多人第一次点开superpowers仓库主页第一反应是下载 ZIP 包或git clone。错了。superpowers本身没有可执行二进制文件不提供图形界面也不绑定任何特定语言运行时。它是一个高度抽象的技能协议规范Skill Protocol Specification。你可以把它理解成 USB 接口标准USB-C 插口长什么样、电压多少、数据怎么握手这些是协议而你的移动电源、显示器、扩展坞才是按协议实现的“设备”。superpowers定义的就是“一个 AI 技能该长什么样、怎么被发现、怎么被调用、怎么传参、怎么返回结果”的一套最小公约数。它的核心文件只有三个SKILL.md技能的“身份证”。必须包含name、description、input_schemaJSON Schema、output_schema、entrypoint执行命令。它不写代码逻辑只写契约。skill.sh或skill.py真正的“肌肉”。按SKILL.md里约定的input_schema接收 JSON 输入处理后按output_schema输出 JSON。它可以是 Bash 脚本调curl可以是 Python 脚本跑pandas也可以是 Go 程序连数据库。.superpowers.yml技能的“部署说明书”。声明它依赖什么环境requires: [node, python3.11]需要哪些系统权限permissions: [network, filesystem]是否需要后台常驻daemon: true。提示superpowers仓库里那个examples/目录下的hello-world技能就是最简协议实现。它SKILL.md里写input_schema是{ name: string }skill.sh里就只有一行echo {\greeting\: \Hello, $1!\}。你删掉SKILL.md它就不是superpowers技能你把skill.sh换成skill.js只要输入输出格式不变它还是合法技能。协议的生命力正在于此。2.2 Claude Code协议的“翻译官”与“调度器”superpowers协议再优雅也需要一个“翻译官”来把它和人类语言、AI 模型连接起来。这就是Claude Code的角色。它不是另一个大模型也不是代码补全插件。它是superpowers生态里的运行时环境Runtime。它的核心工作有三件解析SKILL.md读取所有已注册技能的元数据构建本地技能目录树。它知道git-diff-summary技能接受一个commit_hash字符串返回一个summary字段的 JSON 对象。桥接 LLM 输入当你在 VS Code 里选中一段代码右键选择 “Ask Claude: Summarize this function”Claude Code并不直接把代码喂给模型。它先查技能目录发现code-summarizer技能匹配于是把选中的代码按input_schema封装成 JSON再把这个 JSON 作为上下文的一部分拼接到 LLM 的 prompt 里。调度与执行LLM 的输出如果包含明确的技能调用指令如RUN_SKILL: git-diff-summary --commit abc123Claude Code就会拦截这条指令解析参数找到对应技能执行skill.sh捕获 stdout再把结果 JSON 解析出来注入回对话流。注意Claude Code的--model参数指定的不是模型本身而是“模型调用方式”。--model lmstudio表示它会通过 LM Studio 的 OpenAI 兼容 APIhttp://localhost:1234/v1/chat/completions发请求--model anthropic则走 Anthropic 官方 API。它本身不加载模型权重只是一个智能代理。2.3 Skill可组合、可验证、可审计的原子单元skill是整个链条里最务实的一环。它把模糊的“AI 能力”转化成确定的、可测试的、可版本控制的代码片段。热词里反复出现的 “skill 编码247”、“skill 编码193”指的就是SKILL.md文件里input_schema的 JSON Schema 版本号。这不是随意编号而是语义化版本控制SemVer的实践。比如skill 编码247可能定义input_schema: { type: object, properties: { repo_url: { type: string, format: uri }, branch: { type: string, default: main } }, required: [repo_url] }而skill 编码193可能是旧版repo_url只是普通字符串没有format: uri校验。当你升级一个技能superpowersCLI 会强制校验新SKILL.md是否向后兼容。这解决了 AI 工具链里最头疼的问题不可预测性。一个git-status-summary技能无论你用 Claude、Gemini 还是本地 Llama只要输入是合法的 Git 仓库路径输出就一定是{ staged: 3, unstaged: 1, untracked: 2 }这样的结构。你可以用superpowers test --skill git-status-summary写一个test.json输入文件断言输出字段把它放进 CI 流水线。这才是工程化的起点。3. 实操落地全流程从零配置到生产级集成3.1 环境准备避开 Ubuntu 和 Windows 的经典陷阱别急着npm install -g superpowers。superpowers的 CLI 工具sp是用 Rust 写的官方只提供预编译的 Linux/macOS 二进制。Windows 用户必须用 WSL2这是硬性前提。我在 Windows 11 上踩的第一个坑就是试图在 PowerShell 里直接运行sp init结果报错exec format error——因为下载的是 Linux ELF 文件。正确路径是WSL2 安装在 Microsoft Store 里装 Ubuntu 22.04启动后sudo apt update sudo apt upgrade -y。Rust 环境curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh然后source $HOME/.cargo/env。安装spCLIcargo install superpowers-cli。注意不是npm install也不是pip install。cargo是唯一受支持的安装方式。VS Code 配置在 WSL2 里安装 VS Code Servercode .然后在 Windows 端的 VS Code 里安装 Remote-WSL 扩展。所有后续操作都在 WSL2 的 VS Code 环境里进行。实操心得Ubuntu 22.04 自带的curl版本太老rustup安装会失败。必须先sudo apt install curl升级。这个细节官网文档没写但社区 issue #427 里有 37 个用户踩过。另外sp init生成的默认配置会把技能存到$HOME/.superpowers/skills但 VS Code 的Claude Code插件默认只扫描工作区根目录下的skills/文件夹。你得手动在.superpowers.yml里加一行skills_path: $HOME/.superpowers/skills否则插件根本看不到你装的技能。3.2 引入第一个技能以diplay github为例的深度拆解热词里高频出现的diplay github指向的是shihabal3amri/diplay这个仓库。它不是一个独立应用而是一个superpowers技能集合。我们把它引入不是为了“下载”而是为了“注册”。克隆到本地技能目录mkdir -p $HOME/.superpowers/skills cd $HOME/.superpowers/skills git clone https://github.com/shihabal3amri/diplay.git diplay-github注意目录名diplay-github这是技能 ID必须小写、短横线分隔不能有下划线。检查SKILL.md合法性diplay-github/SKILL.md里关键字段是name: GitHub Repository Display description: Fetch and display basic info (stars, forks, description) for a GitHub repo input_schema: type: object properties: repo: { type: string, description: Full repo name, e.g. microsoft/vscode } required: [repo] output_schema: type: object properties: name: { type: string } stars: { type: integer } forks: { type: integer } description: { type: string } entrypoint: ./display.sh这里entrypoint指向display.sh它内部用curl调 GitHub API。但问题来了GitHub API 有速率限制60次/小时未授权display.sh默认没带 token。所以这一步必须改。注入认证凭据 在diplay-github/display.sh开头加两行#!/bin/bash GITHUB_TOKEN$(cat ~/.github_token 2/dev/null) curl -H Authorization: token $GITHUB_TOKEN https://api.github.com/repos/$1 | jq {name: .name, stars: .stargazers_count, forks: .forks_count, description: .description}然后echo your_personal_access_token_here ~/.github_token chmod 600 ~/.github_token。这是superpowers设计的精妙之处技能本身不硬编码密钥而是由运行时环境你的 shell提供。Claude Code插件在执行display.sh前会自动把~/.github_token加载为环境变量。注册并测试sp register diplay-github sp test --skill diplay-github --input {repo: microsoft/vscode}如果返回{name:vscode,stars:152000,forks:38000,description:Visual Studio Code}说明成功。此时在 VS Code 里打开任意文件按CtrlShiftP输入Superpowers: Run Skill就能选到GitHub Repository Display输入microsoft/vscode立刻得到结果。3.3 配置 Claude Code让本地大模型真正“听懂”技能Claude Code插件的核心配置在 VS Code 的settings.json里。热词里“vscode 配置 claude code”、“claude code 调用 lmstudio 的本地模型”关键就在这几行{ claudeCode.model: lmstudio, claudeCode.lmStudioUrl: http://localhost:1234/v1, claudeCode.lmStudioModel: TheBloke/Llama-3-70B-Instruct-GGUF, claudeCode.skillPath: /home/yourname/.superpowers/skills, claudeCode.enableSkills: true, claudeCode.systemPrompt: You are an expert developer assistant. When a user asks for something that can be done by a registered skill, you MUST output the exact RUN_SKILL command in this format: RUN_SKILL: skill_id --arg1 value1 --arg2 value2. Do not explain, do not add text before or after. }这里有几个致命细节lmStudioUrl必须是http://localhost:1234/v1不是/v1/chat/completions。Claude Code会自动拼接 endpoint。lmStudioModel的值必须和 LM Studio UI 里“Loaded Model”显示的完全一致。Llama-3-70B 的 GGUF 文件名可能是llama-3-70b-instruct.Q4_K_M.gguf但 LM Studio 加载后显示的 model name 是TheBloke/Llama-3-70B-Instruct-GGUF。输错一个字符就会报model not found。systemPrompt是灵魂。它强制 LLM 的输出格式。没有这句LLM 会说“好的我来帮你查一下 GitHub”而不是输出RUN_SKILL: diplay-github --repo microsoft/vscode。Claude Code只识别RUN_SKILL:开头的行。实测对比用官方 Claude API响应快但贵用 LM Studio 本地 Llama-3-70B首字延迟 3 秒但无限次调用。我做了个测试对同一个git diff输出让两者都生成总结。Claude 的总结更简洁但漏掉了两个关键的测试文件修改Llama-3-70B 的总结啰嗦但列出了所有 7 个变更文件包括那两个测试文件。本地模型胜在“不遗漏”云端模型胜在“不废话”。选哪个取决于你的场景代码审查要精度日常问答要速度。3.4 构建自己的 Skill从book-to-skill到可复用的备课助手热词里有book to skill、ai备课skill这正是superpowers最闪光的应用场景把领域知识固化为可调用的技能。假设你是中学物理老师想把《高中物理必修一》PDF 里的公式自动提取成技能。创建技能目录mkdir -p $HOME/.superpowers/skills/physics-formula-extractor cd $HOME/.superpowers/skills/physics-formula-extractor编写SKILL.mdname: High School Physics Formula Extractor description: Extract key formulas and their explanations from a physics textbook PDF page input_schema: type: object properties: pdf_path: { type: string, description: Absolute path to the PDF file } page_number: { type: integer, description: Page number to extract from (1-indexed) } required: [pdf_path, page_number] output_schema: type: array items: type: object properties: formula: { type: string, description: LaTeX representation of the formula } explanation: { type: string, description: Plain text explanation } context: { type: string, description: Surrounding text snippet for reference } entrypoint: ./extract.py实现extract.py核心逻辑#!/usr/bin/env python3 import sys, json, fitz # PyMuPDF import re def extract_formulas(pdf_path, page_num): doc fitz.open(pdf_path) page doc[page_num - 1] # Convert to 0-indexed text page.get_text() # Simple regex for common physics patterns (in practice, use ML model) formula_pattern r([FmaE\-\*\/\d\.\s])\s*([\d\.\s\\-\*\/a-zA-Z\{\}\[\]\(\)]) results [] for match in re.finditer(formula_pattern, text[:500]): # First 500 chars formula match.group(1).strip() rhs match.group(2).strip() # Find surrounding context start max(0, match.start() - 50) end min(len(text), match.end() 50) context text[start:end].replace(\n, ) results.append({ formula: f${formula} {rhs}$, explanation: fPhysics law relating {formula.split()[0]} and {rhs.split()[0]}, context: context }) return results if __name__ __main__: input_json json.loads(sys.stdin.read()) pdf_path input_json[pdf_path] page_num input_json[page_number] output extract_formulas(pdf_path, page_num) print(json.dumps(output))注册与使用sp register physics-formula-extractor # 在 VS Code 里右键 PDF 文件 - Superpowers: Run Skill - 选这个技能输入 {pdf_path: /path/to/book.pdf, page_number: 42}结果会是[{formula: $F ma$, explanation: Physics law relating F and a, context: Newtons Second Law states that...}]。这个技能可以被任何 LLM 调用也可以被你写个 Bash 脚本批量处理整本书。4. 真实世界问题排查那些热搜词背后的血泪教训4.1 “github打不开”、“github下载加速镜像源”不是网络问题是技能依赖问题搜索热词里大量出现github打不开、github镜像站很多人以为是网络问题去配代理、换 DNS。但在superpowers场景下90% 的情况是技能本身依赖 GitHub API而 API 调用失败了。典型案例如diplay-github技能。现象在 VS Code 里运行GitHub Repository Display等 30 秒后报错Failed to fetch from GitHub API: timeout。排查路径先sp test --skill diplay-github --input {repo: microsoft/vscode}看 CLI 是否同样超时。如果是问题在技能执行层。进入diplay-github/目录手动运行./display.sh microsoft/vscode。如果报curl: (7) Failed to connect to api.github.com port 443说明 WSL2 网络不通。检查 WSL2 的 DNScat /etc/resolv.conf。Ubuntu 22.04 默认用nameserver 127.0.0.53这是 systemd-resolved有时会失效。临时修复echo nameserver 8.8.8.8 | sudo tee /etc/resolv.conf。如果 CLI 测试成功但 VS Code 插件失败检查Claude Code的skillPath设置是否指向正确的绝对路径。相对路径./skills在插件里会解析失败。注意github镜像站对superpowers技能无效。因为技能代码里写死的是https://api.github.com不是https://github.com。镜像站只加速网页访问和 Git clone不代理 API。真正有效的“加速”是给display.sh加上GITHUB_TOKEN把速率限制从 60 次/小时提升到 5000 次/小时。4.2 “your organization has disabled claude subscription access for claude code 路”权限隔离的必然结果这个错误信息直指企业环境的核心矛盾。Claude Code插件在连接 Anthropic 官方 API 时会发送一个x-anthropic-clientheader其中包含你的组织 ID。如果你的公司管理员在 Anthropic 控制台里禁用了该组织的claude-code订阅这个错误就会出现。解决方案不是“破解”而是“绕行”切换模型后端在 VS Codesettings.json里把claudeCode.model: anthropic改成claudeCode.model: lmstudio彻底脱离 Anthropic 服务。使用企业级替代方案如果你的公司有自建的 LLM 网关如 FastAPI vLLM可以在lmStudioUrl里填http://your-company-llm-gateway/v1Claude Code会无缝对接。技能降级对于不需要强推理的技能如git-status-summary直接在SKILL.md里把requires: [python]改成requires: [bash]用纯 Shell 实现完全不调用 LLM。4.3 “claude code如何直接执行终端命令”安全边界的严肃讨论热词里有“claude code 如何直接执行终端命令”这触及了superpowers的安全红线。Claude Code绝不会、绝不应该允许 LLM 直接执行任意rm -rf /或curl http://malicious.site。它的设计哲学是“技能即沙盒”。正确路径你要执行终端命令必须封装成一个skill。创建skills/terminal-executor。SKILL.md的input_schema明确限定可执行的命令白名单input_schema: type: object properties: command: { type: string, enum: [git status, git log -n 5, ls -la, df -h] } required: [command]skill.sh里用case语句严格匹配case $1 in git status) git status ;; git log -n 5) git log -n 5 ;; *) echo {error: Command not allowed} 2; exit 1 ;; esac为什么不能跳过技能层LLM 的输出是概率性的。今天它输出git status明天可能因温度参数变化输出git reset --hard HEAD。superpowers的价值正在于用SKILL.md的enum和required字段把这种不确定性锁死在确定性的边界内。4.4 “去ai味的skill”让技能输出更“人味”的实操技巧热词里“去ai味的skill”反映了一个普遍痛点LLM 生成的文本太“AI”缺乏人的语气、习惯和上下文感知。superpowers的解法是“技能后处理”。案例ai备课skill生成的教案开头总是“本节课的教学目标是...”太教条。我们加一个post-processor技能skills/humanize-text的SKILL.mdname: Humanize Text description: Rewrite AI-generated text to sound more natural and conversational input_schema: type: object properties: text: { type: string } tone: { type: string, enum: [teacher, student, colleague], default: teacher } output_schema: type: object properties: humanized: { type: string } entrypoint: ./humanize.pyhumanize.py用规则模板if input_json[tone] teacher: replacements { 教学目标是: 咱们这节课重点搞定这几件事, 学生将能够: 学完这个你就能, 综上所述: 一句话总结就是 } # ... apply replacements print(json.dumps({humanized: processed_text}))链式调用在Claude Code的systemPrompt里可以写“如果输出是教案必须先 RUN_SKILL: humanize-text --tone teacher再返回最终结果。” 这样技能链就形成了LLM - ai备课skill - humanize-text输出自然多了。5. 经验沉淀与避坑指南三个月踩出的七条铁律5.1 铁律一永远不要在SKILL.md里写业务逻辑只写契约我最初写git-diff-summary技能时在SKILL.md的description字段里写了大段 Python 伪代码以为这样能“指导” LLM。结果Claude Code完全忽略它只认input_schema。SKILL.md是给机器读的契约文件不是给人看的说明书。业务逻辑只存在于skill.sh或skill.py里。description字段的唯一作用是让Claude Code的技能列表里显示一个友好的名字。把它当成数据库表的COMMENT而不是存储过程。5.2 铁律二superpowers test是你的第一道防线不是可选项sp test --skill xxx命令会做三件事1) 校验SKILL.md的 YAML 语法2) 校验input_schema和output_schema的 JSON Schema 有效性3) 用你提供的--inputJSON实际执行entrypoint断言 stdout 是合法 JSON。我曾因跳过这一步在 CI 里部署后才发现skill.py里少了个import json导致整个技能链崩溃。现在我的工作流是写完skill.py→sp test→git commit→sp register。sp test的执行时间不到 0.1 秒但它省下的调试时间是以小时计的。5.3 铁律三WSL2 的文件系统性能是隐形瓶颈在 WSL2 里访问 Windows 文件系统/mnt/c/Users/xxx比访问原生 Linux 文件系统/home/xxx慢 5-10 倍。superpowers技能如果要处理大文件如 PDF、视频必须把文件放在 WSL2 的 home 目录下。我试过让physics-formula-extractor直接读/mnt/c/Users/Me/book.pdf耗时 12 秒移到/home/me/book.pdf后耗时 1.3 秒。Claude Code插件在 VS Code 里调用技能时路径是 Windows 格式所以必须在skill.py里做一次os.path.join(/home/me, os.path.basename(input_path))的转换。5.4 铁律四Claude Code的systemPrompt必须用英文且精确到标点中文systemPrompt会导致 LLM 输出格式混乱。我试过写“请务必输出 RUN_SKILL: xxx --arg value 格式”LLM 有时会输出RUN_SKILL: xxx --argvalue用了等号有时是RUN_SKILL: xxx --arg value空格Claude Code只认后者。最终稳定方案是英文 prompt并用正则强调You MUST output EXACTLY ONE line in this format: RUN_SKILL: skill_id --arg_name arg_value. No other text, no explanation, no markdown, no quotes around values.多一个空格多一个句号都可能导致解析失败。5.5 铁律五技能的permissions字段不是摆设是安全锁superpowersCLI 会检查permissions字段。如果你的skill.sh里有curl但SKILL.md里没写permissions: [network]sp register会报错。这不是 bug是 feature。它强迫你在设计阶段就思考“这个技能需要什么权限” 我曾写过一个backup-to-s3技能忘了加permissions: [filesystem, network]sp register失败后才意识到它既要读本地文件又要上传到 S3。这个检查避免了技能在生产环境里因权限不足而静默失败。5.6 铁律六skill目录的结构决定了你的维护成本superpowers允许你把所有技能放在一个skills/目录下但三个月后你会有 50 个技能。我的经验是按领域分组用子目录。skills/ ├── dev-tools/ # git, docker, npm 相关 ├── docs/ # PDF, Markdown, Confluence 相关 ├── infra/ # AWS, Kubernetes, Terraform 相关 └── personal/ # 备课、日程、笔记相关然后在.superpowers.yml里用skills_path: [$HOME/.superpowers/skills/dev-tools, $HOME/.superpowers/skills/docs]。这样sp list输出的技能列表是分组的sp test也能指定--path dev-tools只测试开发工具类技能。结构清晰胜过千行注释。5.7 铁律七放弃“一个技能解决所有问题”的幻想拥抱组合superpowers的威力不在于单个技能多强大而在于多个技能如何组合。热词里“workbuddy skill”、“狗头军师skill”本质上都是技能链。比如“狗头军师”user_input→skill: extract-keywords从用户输入里抽关键词keywords→skill: search-stackoverflow用关键词搜 Stack Overflowstackoverflow_results→skill: summarize-answer摘要答案summary→skill: humanize-text转成口语这个链路不是写在一个skill.py里而是由Claude Code的systemPrompt驱动LLM 决定何时调用哪个技能。你只需要确保每个环节的input_schema和output_schema能对上。组合的自由度远大于单体的复杂度。这是我三个月后最深的体会superpowers不是给你一把万能钥匙而是给你一套标准锁芯和无数把形状各异的钥匙让你自己组装出最适合那把锁的钥匙串。