superpowers技能协议：从Claude Code到可工程化AI工作流-拓冰网站定制

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_schema（JSON 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 abc123），Claude Code就会拦截这条指令，解析参数，找到对应技能，执行skill.sh，捕获 stdout，再把结果 JSON 解析出来，注入回对话流。

注意：Claude Code的--model参数，指定的不是模型本身，而是“模型调用方式”。--model lmstudio表示它会通过 LM Studio 的 OpenAI 兼容 API（http://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。
安装spCLI：cargo install superpowers-cli。注意，不是npm install，也不是pip install。cargo是唯一受支持的安装方式。
VS Code 配置：在 WSL2 里安装 VS Code Server（code .），然后在 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 里打开任意文件，按Ctrl+Shift+P，输入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.md：

name: "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": f"Physics 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": "Newton's 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。
排查路径：
1. 先sp test --skill diplay-github --input '{"repo": "microsoft/vscode"}'，看 CLI 是否同样超时。如果是，问题在技能执行层。
2. 进入diplay-github/目录，手动运行./display.sh microsoft/vscode。如果报curl: (7) Failed to connect to api.github.com port 443，说明 WSL2 网络不通。
3. 检查 WSL2 的 DNS：cat /etc/resolv.conf。Ubuntu 22.04 默认用nameserver 127.0.0.53，这是 systemd-resolved，有时会失效。临时修复：echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf。
4. 如果 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订阅，这个错误就会出现。

解决方案不是“破解”，而是“绕行”：
1. 切换模型后端：在 VS Codesettings.json里，把"claudeCode.model": "anthropic"改成"claudeCode.model": "lmstudio"，彻底脱离 Anthropic 服务。
2. 使用企业级替代方案：如果你的公司有自建的 LLM 网关（如 FastAPI + vLLM），可以在lmStudioUrl里填http://your-company-llm-gateway/v1，Claude Code会无缝对接。
3. 技能降级：对于不需要强推理的技能（如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.md：

name: "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.py"

humanize.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 --arg=value（用了等号），有时是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 Overflow）
stackoverflow_results→skill: summarize-answer（摘要答案）
summary→skill: humanize-text（转成口语）

这个链路，不是写在一个skill.py里，而是由Claude Code的systemPrompt驱动，LLM 决定何时调用哪个技能。你只需要确保每个环节的input_schema和output_schema能对上。组合的自由度，远大于单体的复杂度。这是我三个月后最深的体会：superpowers不是给你一把万能钥匙，而是给你一套标准锁芯和无数把形状各异的钥匙，让你自己组装出最适合那把锁的钥匙串。

资讯详情

superpowers技能协议：从Claude Code到可工程化AI工作流