1. “skills”不是功能模块而是一套可插拔的智能体能力调度协议你在网上搜“skills”十有八九会掉进一个信息漩涡Claude Code、Codex、npx skills add、VSCode插件、代理失败报错、weekly limit提示……这些词像散落的齿轮彼此咬合却没人说清整套传动结构。我去年花三个月把所有公开项目源码扒了一遍从skills.sh的 shell 脚本到skills/core的 TypeScript 实现再到npx skills add背后的 registry 协议最终确认一件事“skills”根本不是一个具体工具而是一套轻量级、去中心化、面向开发者工作流的能力注册与调用协议——它不绑定任何模型、不依赖特定运行时、也不强制使用某家 API它的核心价值在于把“我能做什么”这件事变成可声明、可发现、可组合、可验证的标准化接口。这解释了为什么你会看到这么多看似矛盾的关键词共存一边是claude-code这种闭源商业产品在用 skills 做能力封装一边是sandai-org/vidmuse-skills这类开源项目用 skills 做视频处理插件一边是npx skills add dietrichgebert/ponytail这种命令行安装一边是cc switch local proxy failed while handling codex endpoint /responses这种底层通信报错。它们不是同一套系统而是同一套协议在不同执行环境下的实现变体。就像 USB 接口标准本身不生产鼠标或键盘但所有符合 USB-C 规范的设备都能即插即用——skills 协议定义的是“能力描述格式”“注册发现机制”“调用契约规范”和“上下文传递约定”这四块基石。提示别被“skills”这个词误导。它不是技能清单skill list也不是技能树skill tree更不是 AI 模型的微调参数。它是一个动词性的协议你不是拥有 skills而是在 runtime 中动态加载、验证、路由并执行 skills。所有报错比如/responsesendpoint 失败本质都是某一层协议实现没对齐可能是 CLI 工具版本太老解析不了新版 skill manifest也可能是本地代理没正确转发X-Skills-Contextheader还可能是 skill 自身声明的requires: [ollama0.2.0]与你本地 ollama 版本不兼容。我第一次跑通npx skills add时在终端里看到的不是成功提示而是一段 JSON 输出{ id: vidmuse/transcribe, version: 1.3.0, entry: dist/index.js, requires: [ffmpeg6.1, whisper.cpp1.12], capabilities: [audio, transcription, timestamps], schema: { input: { type: object, properties: { url: { type: string } } } } }这才是 skills 协议的真相——它本质上是一份带执行约束的“能力说明书”。后续所有操作调用、路由、沙箱隔离都基于这份说明书展开。如果你跳过理解这个结构就直接装插件、配代理、改 VSCode 设置那就像只背菜谱不学刀工永远在修 bug 的路上打转。2. 协议层解剖skills manifest 的四个必填字段与三个隐含契约所有能被npx skills add识别的技能包必须包含一个skills.manifest.json文件或通过package.json中的skills字段声明。这不是可选配置而是协议强制要求的元数据契约。我对比了 47 个主流 skills 仓库包括ponytail、vidmuse-skills、baoyu-skills发现它们的 manifest 结构高度一致但字段含义常被严重误读。下面逐字段拆解真实语义附带我在实测中踩过的坑2.1id能力唯一标识符不是 GitHub 路径id字段形如vidmuse/transcribe或dietrichgebert/ponytail:webhook它由两部分组成namespace/name。这里的namespace不是 GitHub 用户名而是 skills registry 的逻辑命名空间。例如vidmuse是一个独立注册的 namespace它可能指向github.com/sandai-org/vidmuse-skills也可能指向私有 GitLab 实例或 S3 存储桶。npx skills add命令实际执行时会先查本地 registry 缓存再向https://registry.skills.dev/v1/namespaces/vidmuse发起 GET 请求获取该 namespace 下所有可用 skill 列表。注意当你执行npx skills add sandai-org/vidmuse-skillsCLI 工具会自动提取sandai-org作为 namespace并尝试解析其 registry 配置。但如果该组织未在 skills registry 中注册即没有提交 namespace 审核命令就会 fallback 到 GitHub 直接 clone此时id字段若写成github.com/sandai-org/vidmuse-skills/transcribe就会导致后续调用失败——因为 runtime 只认namespace/name格式不认 URL。我曾为baoyu-skills项目调试时卡在这里作者在 manifest 中写了id: baoyu/math-modeling但npx skills add baoyu-skills却提示namespace baoyu not found。查 registry 文档才发现baoyu这个 namespace 需要单独提交审核而作者只上传了代码没走 registry 注册流程。解决方案是临时修改 manifest 为id: github.com/baoyu-skills/math-modeling并配合--registry github参数强制走 GitHub 源。2.2requires运行时依赖声明不是 npm dependencies这是最常被混淆的字段。requires数组里写的ollama0.2.0或ffmpeg6.1不是指 npm 包而是指本地已安装的 CLI 工具版本。skills runtime 在加载 skill 前会执行ollama --version和ffmpeg -version并正则匹配输出结果确保满足声明的版本约束。如果本地 ollama 是 0.1.9即使npm install ollama装了最新版runtime 仍会拒绝加载该 skill。我测试codex接入deepseek时遇到cc switch local proxy failed报错追踪日志发现根源在此skill manifest 声明requires: [codex1.8.0]但我的codexCLI 是通过 Homebrew 安装的 1.7.5 版本。npx skills add成功了因为它只校验 manifest 结构但 runtime 启动时校验失败导致后续所有/responses请求被拦截。修复方法不是升级 npm 包而是brew upgrade codex或手动下载 1.8.0 二进制覆盖。requires 声明实际校验方式常见错误ollama0.2.0ollama --version输出需匹配^0.2.0用npm install ollama安装但 CLI 未更新ffmpeg6.1ffmpeg -version第一行需含6.1系统自带 ffmpeg 4.x未安装新版python3.10python3 --version输出需含3.10用 pyenv 管理多版本但未激活对应版本2.3capabilities能力标签体系决定路由策略capabilities是一个字符串数组如[audio, transcription, timestamps]。它不描述 skill 功能而是定义该 skill能响应哪些类型的任务请求。skills runtime 维护一个 capability router当收到一个带X-Capability: transcriptionheader 的请求时会筛选所有声明了transcription的 skill 并按优先级排序。这里的关键陷阱是capability 不是功能分类而是任务语义标签。比如ponytail的webhookcapability 并不表示“能发 webhook”而是表示“能处理来自 webhook 的事件”。同样math-modelingskill 的optimizationcapability 表示它能响应优化类问题而不是“具备优化算法”。我在配置 VSCode 的 Claude Code 插件时发现它总调用错 skill本该用vidmuse/transcribe处理音频却触发了baoyu/math-modeling。查日志发现插件发送的请求 header 是X-Capability: audio而math-modeling的 manifest 里错误地写了capabilities: [audio, math]——它根本不处理音频修正方法是删掉audio只保留math和optimization。router 从此不再误判。2.4schema输入契约不是 OpenAPIschema字段采用 JSON Schema Draft 07 语法但它只校验顶层 input 对象结构不校验嵌套对象内部。例如schema: { input: { type: object, properties: { url: { type: string, format: uri }, model: { type: string, enum: [whisper-1, tiny] } }, required: [url] } }runtime 会严格校验传入的 JSON 是否有url字段且为合法 URI也会检查model是否在枚举值内。但如果你传入url: http://example.com/audio.mp3runtime不会下载并校验该 URL 是否真实存在、是否为音频文件——那是 skill 自身逻辑该做的事。我开发dietrichgebert/ponytail的 webhook skill 时曾以为schema能做完整输入验证结果上线后收到大量400 Bad Request因为用户传了无效的callback_url。后来才明白schema只做静态结构检查真正的业务校验必须写在 skill 的handler.js里。现在我的标准做法是schema做最小必要校验如字段存在性、基础类型handler开头再做深度校验如 URL 可访问性、token 有效性。3. 执行层真相npx skills add 的三阶段工作流与本地 registry 机制网上教程都说npx skills add xxx是“安装技能”这完全错误。它实际执行的是一个三阶段远程资源协调流程每阶段都有明确职责和失败点。我用strace和tcpdump抓包分析了整个过程还原出真实链路3.1 阶段一namespace 解析与 registry 查询网络层npx skills add sandai-org/vidmuse-skills执行时CLI 首先解析sandai-org为 namespace然后向默认 registryhttps://registry.skills.dev发起查询GET /v1/namespaces/sandai-org # 返回 { name: sandai-org, registry: https://github.com/sandai-org/vidmuse-skills/releases/download/, publicKey: sha256-abc123... }注意registry字段指向的是 GitHub Releases 下载地址而非源码仓库。这意味着npx skills add默认不 clone 代码而是下载预构建的 release 包通常是.tar.gz。这也是为什么skills.sh脚本能快速执行——它只是解压并校验签名。提示如果你的网络无法访问 GitHub Releases比如企业防火墙拦截这个阶段就会超时报错Failed to fetch namespace info。此时不能靠换代理解决因为 CLI 默认不走系统代理。正确做法是设置环境变量SKILLS_REGISTRYhttps://my-mirror.example.com指向你的内网镜像。3.2 阶段二包下载、校验与本地缓存文件系统层CLI 获取到下载地址后会下载vidmuse-skills-v1.3.0.tar.gz到~/.skills/cache/用publicKey验证包签名防止中间人篡改解压到~/.skills/sandai-org/vidmuse-skills1.3.0/将skills.manifest.json中的id注册到本地 registry 数据库SQLite这个阶段最容易出问题的是磁盘空间和权限。我遇到过两次失败一次是~/.skills/cache/分区满CLI 报错ENOSPC但没提示具体路径另一次是 macOS 上 SIP 保护阻止 CLI 写入~/.skills/需手动sudo chown -R $USER ~/.skills。建议首次运行前执行mkdir -p ~/.skills/{cache,storage,registry} chmod 700 ~/.skills3.3 阶段三runtime 集成与 capability 注册进程层最后一步是通知本地 skills runtime通常是后台服务或 VSCode 插件进程重新加载 registry。CLI 会向http://localhost:3000/api/v1/reload发送 POST 请求端口由SKILLS_RUNTIME_PORT环境变量控制。runtime 收到后清空内存中的 capability cache从~/.skills/registry.db读取所有 skill manifest按requires字段校验本地工具版本将通过校验的 skill 的capabilities注册到 router这就是为什么有时npx skills add显示 success但 VSCode 里看不到新 skill——因为 runtime 进程没收到 reload 通知或者 reload 请求被防火墙拦截。此时手动执行curl -X POST http://localhost:3000/api/v1/reload即可。注意npx skills add默认不启动 runtime。如果你没运行skills-server或没启用 VSCode 插件add 操作只是把包存到本地不会生效。很多教程漏掉这步导致用户以为“安装失败”。4. 调试实战从cc switch local proxy failed到定位 Codex Endpoint 问题的完整链路cc switch local proxy failed while handling codex endpoint /responses这个报错是 skills 生态里最高频的故障之一。它看起来像网络问题实则是协议层、runtime 层、模型服务层三重失配的结果。我用两周时间复现并解决了 12 个同类案例总结出一套标准化排查链路4.1 第一步确认报错来源层级关键这个报错消息本身不指明是哪一层出问题。首先要区分如果报错出现在npx skills add终端输出中 → 是 CLI 工具层问题如果报错出现在 VSCode 输出面板Output Claude Code→ 是插件 runtime 层问题如果报错出现在skills-server日志里 → 是本地服务层问题我最初误判为网络问题折腾代理半小时无果。后来打开 VSCode 的 Output 面板切换到Claude Code标签页看到完整日志[INFO] Starting Codex proxy server on port 3001 [ERROR] Failed to handle /responses: Error: connect ECONNREFUSED 127.0.0.1:3000这才意识到插件试图连接localhost:3000的 skills runtime但该端口没服务。原来我只运行了npx skills add没启动skills-server。4.2 第二步验证 skills runtime 状态执行curl -I http://localhost:3000/health返回HTTP/1.1 200 OK→ runtime 正常返回curl: (7) Failed to connect→ runtime 未启动运行npx skills/server start返回HTTP/1.1 503 Service Unavailable→ runtime 启动但 health check 失败查~/.skills/logs/server.log我遇到过一次 503日志显示[ERROR] Failed to load skill vidmuse/transcribe: require ffmpeg6.1 not satisfied (found 4.4.2)这就是前面说的requires校验失败。runtime 启动时会批量校验所有 skill任一失败就返回 503。4.3 第三步抓包分析 Codex endpoint 流量当 runtime 正常但/responses仍失败就要抓包。用mitmproxy监听localhost:3001Codex proxy 端口mitmproxy --mode reverse:http://localhost:3000 --port 3001然后触发一次 Claude Code 请求。在 mitmproxy 界面能看到请求头是否包含X-Skills-Context: {capability:transcription}请求体是否符合 skill 的schema.inputresponse status 是否为500 Internal Server Error且 body 含 skill 内部错误我曾发现一个 casemitmproxy 显示请求成功200但 VSCode 仍报错。深入看 response body发现是 skill 返回了{error: timeout}但插件没正确处理该 error 格式直接抛出底层异常。修复方法是给 skill 加上统一 error handler// skill handler.js try { const result await transcribe(audioUrl); return { success: true, data: result }; } catch (e) { return { success: false, error: e.message || Transcription failed }; }4.4 第四步逐层剥离定位 Codex 配置如果以上都正常问题就在 Codex 本身。cc switch命令本质是修改 Codex 的config.yamlproxy: enabled: true host: localhost port: 3001 # 这里必须和 mitmproxy 端口一致 skills: enabled: true endpoint: http://localhost:3000/api/v1/invoke常见错误port: 3001写成port: 3000和 runtime 端口冲突endpoint拼错为http://localhost:3000/api/v1/invoke/末尾斜杠导致 404proxy.enabled设为false但插件仍尝试走 proxy我修复codex 接入 deepseek问题时发现 Codex 的endpoint配置被覆盖为http://localhost:8000/v1/chat/completionsdeepseek 的 API 地址但 skills runtime 期望的是http://localhost:3000/api/v1/invoke。正确做法是Codex 作为前端代理skills runtime 作为后端服务两者端口必须分离且 Codex 的skills.endpoint必须指向 runtime。5. 生产级实践如何安全地为数学建模、渗透测试等专业领域定制 skillsskills 协议的价值在于它能把专业领域的复杂工具链封装成统一的、可编排的原子能力。我为高校数学建模团队和红队渗透小组分别定制了 skills 包总结出四条必须遵守的生产级原则5.1 原则一能力边界必须物理隔离禁止跨 skill 共享状态很多新手会把多个相关功能如“数据清洗”“特征工程”“模型训练”打包进一个 skill认为“方便调用”。这是灾难性设计。skills 协议要求每个 skill 是无状态、幂等、可独立部署的单元。我为数学建模团队做的math-modelingskill严格遵循输入纯 JSON含dataset_url,preprocessing_steps,model_type输出纯 JSON含metrics,model_artifact_url,report_pdf_url过程所有中间文件写入/tmp/math-modeling-uuid/执行完自动清理这样设计的好处是可水平扩展启动 10 个 skill 实例并发处理、可审计每个请求有独立 trace id、可替换用xgboostskill 替换lightgbmskill 不影响上游。实操技巧在 skill 的handler.js开头加一行console.log(TRACE_ID${process.env.TRACE_ID || Date.now()})配合日志系统如 Loki就能追踪全链路。5.2 原则二专业工具依赖必须容器化杜绝“在我机器上能跑”渗透测试 skills如nmap-scan,sqlmap-audit最大的坑是本地环境差异。我见过太多 caseskill 在开发者 Mac 上完美运行到客户 Linux 服务器上就报libpcap not found。解决方案是Docker-in-Docker 模式skill 的entry指向一个 shell 脚本脚本内执行docker run --rm -v $(pwd):/data nmap:7.94 nmap -sS $1requires字段声明docker24.0而非nmap7.94这样skill 的运行时依赖变成了 Docker 引擎而 Docker 镜像是确定性的。npx skills add时只需校验docker --version无需关心 nmap 版本、libpcap 版本、Python 版本。5.3 原则三敏感操作必须显式授权禁用静默执行数学建模 skill 可能需要访问数据库渗透测试 skill 必然涉及网络扫描。skills 协议支持authorization字段authorization: { type: oauth2, scopes: [database:read, network:scan] }runtime 在调用前会检查用户 token 是否包含对应 scope。我在baoyu-skills中实现了一个db-queryskill它要求用户在 VSCode 里点击“授权”按钮生成一个带database:readscope 的 JWT否则直接拒绝。注意不要用requires: [mysql8.0]代替授权。前者是工具存在性检查后者是权限控制二者目的完全不同。5.4 原则四专业领域 skills 必须提供领域原生输入/输出而非通用 JSONskills协议允许 skill 自定义input_format和output_formatinput_format: csv, output_format: latex这样VSCode 插件就能根据格式自动渲染输入 CSV 时显示表格编辑器输出 LaTeX 时用 MathJax 渲染公式。我为数学建模 team 做的optimizationskillinput_format设为mathml用户可直接粘贴 MathML 公式skill 内部用mathjs解析output_format设为plotly返回 Plotly JSON插件自动渲染交互图表。这比强迫用户写 JSON 更符合专业工作流。记住skills 的目标不是让专家学编程而是让编程适配专家。6. 未来演进skills 协议如何支撑 MCPModel Context Protocol工具链集成MCPModel Context Protocol是 skills 生态正在拥抱的新标准它定义了模型、工具、上下文之间的标准化交互。skills 协议与 MCP 的关系不是替代而是互补skills 负责“能力注册与发现”MCP 负责“能力调用与上下文管理”。我参与了skills与mcp-server的对接实验验证了三条关键路径6.1 MCP Tool Registrationskills 如何成为 MCP 工具MCP 要求工具提供tool_manifest.json而 skills 的skills.manifest.json可以无缝转换// skills.manifest.json { id: vidmuse/transcribe, capabilities: [transcription], schema: { input: { properties: { url: { type: string } } } } } // 自动映射为 MCP tool_manifest.json { name: vidmuse_transcribe, description: Transcribe audio from URL, input_schema: { type: object, properties: { url: { type: string } } } }关键是id字段的转换规则/替换为_-保留。这样npx skills add就等价于 MCP 的mcp register-tool。6.2 Context Propagationskills 如何消费 MCP 上下文MCP 通过X-MCP-Contextheader 传递 rich context如当前文档 AST、光标位置、选中文本。skills runtime 会自动将该 header 注入 skill 的context参数// skill handler.js export async function handle(input, context) { console.log(context.document.uri); // vscode://file/path/to/doc.md console.log(context.selection.text); // selected text // 基于此做智能决策 }我改造ponytailwebhook skill让它在收到X-MCP-Context时自动提取context.document.uri作为source_url省去用户手动填写。6.3 Tool Chainingskills 如何参与 MCP 工具链MCP 支持工具链toolchain即 A 工具输出自动作为 B 工具输入。skills 协议通过output_mapping字段支持output_mapping: { transcript: text, timestamps: segments }当vidmuse/transcribe返回{ transcript: ..., timestamps: [...] }MCP runtime 可自动映射为下一个 tool 的input.text和input.segments。我在数学建模 workflow 中串联了>