1. “skills”不是功能模块而是一套前端开发者私有技能调度协议的命名惯例最近在多个技术社区和开源项目里反复看到“skills”这个词被高频使用但它既不是 npm 官方包名、也不是某个主流框架的内置概念更不是 Web API 标准术语。它出现在npx skill add dietrichgebert/ponytail这类命令中夹在claude code、codex、cc switch等工具链之间还频繁与vscode配置、ollama、mcp工具关联。如果你刚搜到这个关键词第一反应很可能是“这是个新库还是某家公司的闭源 SDK”——其实都不是。“skills”在这里本质上是前端开发者自发形成的一套轻量级技能注册与调用约定核心作用是把本地开发环境中的各类 AI 辅助能力代码补全、调试建议、文档生成、CLI 工具封装抽象成可发现、可组合、可版本化管理的“技能单元”。它不依赖中心化服务不强制绑定特定模型后端也不要求你改写已有工程结构。它的存在恰恰是为了对抗当前 AI 编程工具链中普遍存在的“烟囱式集成”问题每个插件都自己写配置、自己建 HTTP client、自己处理 token 轮转、自己定义 prompt 模板——结果就是 VS Code 里装了 5 个 AI 插件却要配 7 份.env、开 3 个本地代理、记 4 套快捷键。我第一次接触这个模式是在一个内部分享会上一位做低代码平台的同事演示了如何用skills.sh脚本自动拉取并注册一组“前端性能诊断技能”包括 Lighthouse 分析器封装、Bundle Analyzer 接口桥接、CLS 指标实时监控器。整个过程没有修改一行 VS Code 配置也没有动 webpack 或 vite 的 config 文件只执行了一条npx skills register --from https://github.com/xxx/perf-skills。当时我就意识到这不是又一个 CLI 工具而是一种面向开发者工作流的契约式能力组织范式。它之所以能快速扩散根本原因在于解决了三个真实痛点环境隔离难codex和claude code都需要本地运行模型或连接远程 endpoint但它们的 proxy 配置、证书信任、超时策略互不兼容能力复用断层你写了一个用 Ollama 跑 CodeLlama 的代码解释器想把它嵌入到另一个团队的 CI 流水线里就得重写一遍请求逻辑和错误处理调试黑盒化当cc switch local proxy failed while handling codex endpoint /responses报错时你根本不知道是codex的路由规则错了还是cc switch的中间件没加载抑或是skills注册的 endpoint path 写成了/response少了个 s。所以“skills”真正的价值从来不在“它是什么”而在于“它让什么变得可能”比如你可以把ponytail一个基于 Rust 的轻量 CLI 工具链封装成一个 skill让它在 VS Code 里通过右键菜单触发同时也能被 Jenkins pipeline 调用再比如把deepseek-coder的推理接口封装为 skill 后codex和claude code就能共用同一套输入校验、输出解析、缓存策略——这才是它在热搜词里反复和codex接入deepseek、skills如何调用mcp工具绑定的底层逻辑。提示不要试图在 npm registry 里搜索skills包。目前所有公开的skills相关实现如skills.sh、npx skill都是脚本级工具没有发布为标准 npm package。它们的安装方式统一走npx直接执行本质是利用 npm 的 bin 执行机制绕过全局安装确保每次运行都是最新版脚本逻辑。2.npx skill add的背后一个零配置技能注册协议的设计细节当你执行npx skill add dietrichgebert/ponytail时表面看只是从 GitHub 下载某个仓库实际发生的是一个精巧的、分阶段的能力发现与注册流程。它不像npm install那样只关心package.json也不像git clone那样只复制文件——它在读取远端仓库时会按固定优先级扫描三类元数据文件并据此构建本地技能索引。这个过程完全离线完成不上传任何信息也不依赖中心 registry。2.1 协议扫描顺序从显式声明到隐式推导npx skill add的核心逻辑藏在一个不到 200 行的 shell 脚本里可通过npx skills --debug show-script查看其元数据解析遵循严格优先级首选skills.manifest.json这是最高权限的显式声明文件必须位于仓库根目录。它定义技能的唯一 ID、入口路径、依赖项、支持的运行时node/python/rust、输入 schema 和输出 schema。例如ponytail的 manifest 片段{ id: ponytail-lint, entry: ./bin/ponytail-lint.js, runtime: node18, input: { type: object, properties: { file: { type: string } } }, output: { type: object, properties: { issues: { type: array } } } }注意id字段必须全局唯一且不能含/或空格这是后续skills call ponytail-lint命令能精准路由的关键。次选skills.config.js或skills.config.ts当仓库未提供 manifest 时脚本会尝试执行该 JS/TS 文件期望它导出一个符合SkillConfig类型的对象。这种方式适合需要动态生成配置的场景比如根据当前 Node 版本自动选择不同二进制。但风险在于若 config 文件执行出错整个注册失败且错误堆栈不易定位。兜底package.json中的skills字段这是最宽松的兼容方案。只要package.json里有skills: { default: ./lib/index.js }这样的字段脚本就认为这是一个 skill。但它不支持输入/输出 schema 声明所有参数校验和类型转换都由 skill 自己承担属于“裸奔模式”。注意如果三个文件都不存在npx skill add会报错No skill manifest found in dietrichgebert/ponytail而不是静默失败。这是刻意设计的强约束——避免用户误以为注册成功实则技能不可用。2.2 注册后的本地存储结构.skills/目录的真相所有通过npx skill add安装的技能都会被解压并符号链接到用户主目录下的~/.skills/子目录中。这个目录结构不是随意设计的而是为了支撑多环境、多版本共存~/.skills/ ├── registry/ # 所有已注册 skill 的元数据快照JSON ├── cache/ # Git 仓库克隆缓存避免重复下载 ├── dietrichgebert__ponytail/ # 以 owner__repo 命名的隔离目录 │ ├── v1.2.0/ # Git tag 或 commit hash 作为子版本目录 │ │ ├── skills.manifest.json │ │ ├── bin/ │ │ └── node_modules/ │ └── latest - v1.2.0 # 符号链接指向当前激活版本 └── global/ # 全局共享的 runtime 依赖如 common-utils关键点在于latest符号链接。当你执行npx skill update dietrichgebert/ponytail时脚本不会覆盖现有文件而是拉取新版本到v1.3.0/目录再更新latest指向。这意味着你可以用npx skills list --all-versions查看所有历史版本在 CI 环境中可通过npx skills use dietrichgebert/ponytailv1.1.0锁定特定版本避免因上游变更导致流水线失败如果某个 skill 更新后出现兼容性问题只需rm ~/.skills/dietrichgebert__ponytail/latest ln -s v1.1.0 ~/.skills/dietrichgebert__ponytail/latest即可秒级回滚。2.3skills call的执行沙箱为什么它比直接node xxx.js更安全当你运行npx skills call ponytail-lint --file src/App.jsx时skills并非简单地cd到对应目录然后node ./bin/ponytail-lint.js。它启动了一个受控的执行沙箱包含三层隔离进程环境隔离清除所有NODE_OPTIONS、ELECTRON_RUN_AS_NODE等可能干扰的环境变量设置独立的TMPDIR指向~/.skills/tmp/ponytail-lint-hash避免不同 skill 间临时文件冲突强制--no-warnings参数屏蔽 V8 内部警告防止 skill 输出被噪音污染。文件系统视图隔离默认情况下skill 只能访问自身目录下的文件./和传入的--file路径若 manifest 中声明fsAccess: [read:./src, write:./dist]沙箱才会挂载对应路径所有路径访问都经过path.resolve()标准化杜绝../../../etc/passwd这类路径遍历。网络访问白名单默认禁止所有网络请求若 skill 需要调用本地 Ollamahttp://localhost:11434或 Codex endpoint必须在 manifest 中明确声明network: [http://localhost:11434, https://api.codex.example.com]实际执行时沙箱会注入一个轻量 HTTP client wrapper自动拦截非白名单域名的请求并返回403 Forbidden。这种沙箱机制直接解决了claude code和codex生态中最头疼的问题第三方插件偷偷上报用户代码、私自调用未授权 API、或因依赖冲突导致整个编辑器崩溃。我曾亲眼见过一个math-skills插件因硬编码了axios0.21.0与 VS Code 内置的axios1.6.0冲突导致所有 HTTP 请求失效——而用skills封装后它的 axios 被完全隔离在自己的node_modules里互不影响。3.skills.sh与npx skills的分工本质Shell 脚本才是协议的真正载体网上很多教程把skills.sh和npx skills当作两个可互换的工具甚至有人问“哪个更好用”。这其实是个根本性误解。skills.sh不是一个“替代品”而是npx skills协议的参考实现和最小可行载体而npx skills本身只是一个便捷的执行入口它背后调用的正是skills.sh。理解这一点才能避开大量踩坑。3.1skills.sh的不可替代性它定义了协议的“语法树”skills.sh是一个纯 Bash 脚本无 Python/Node 依赖其设计哲学是“最小内核 最大扩展性”。它只做四件事解析命令行参数add/call/list/update按协议扫描远端仓库元数据构建并执行沙箱环境输出结构化 JSON 日志供上层工具消费。正因为它是 Shell 实现所以能天然兼容所有 Unix-like 系统Linux/macOS/WSL且启动速度极快平均 12ms而同等功能的 Node.js 脚本需 80ms。更重要的是它的源码就是协议规范本身——当你遇到cc switch local proxy failed while handling codex endpoint /responses这类错误时直接curl -s https://raw.githubusercontent.com/skills-sh/skills/main/skills.sh | grep -A5 -B5 codex就能定位到相关 proxy 处理逻辑无需翻阅晦涩文档。对比之下npx skills只是一个包装器# npx skills 实际执行的等效命令 npx --ignore-existing skillslatest -- $ # 它最终会下载并执行 skills.sh 的最新 release 版本所以当你看到win10 npx或vscode配置claude code教程里强调“必须用 npx”那只是因为npx提供了最简化的跨平台执行方式。但在生产环境如 Docker 容器或 CI runner我们通常直接curl -fsSL https://skills.sh | bash -s -- add ...跳过 npm 依赖彻底规避npx在某些旧版 Node 环境下的缓存 bug。3.2skills.sh的扩展机制如何不改源码就支持新能力skills.sh通过SKILLS_PLUGIN_DIR环境变量支持插件化扩展。例如你想让skills支持调用 Windows PowerShell 脚本.ps1无需修改skills.sh本身只需创建插件目录mkdir -p ~/.skills/plugins/powershell编写插件脚本~/.skills/plugins/powershell/runner.sh#!/bin/bash # 该脚本接收 $1skill_path, $2input_json, $3output_file pwsh -Command $1 $($2 | jq -r .args[] | paste -sd ) $3设置环境变量export SKILLS_PLUGIN_DIR~/.skills/plugins在 skill 的skills.manifest.json中声明runtime: powershell7.2。这样当skills call遇到powershellruntime 时会自动调用你的插件脚本而非默认的 Node.js 执行器。目前社区已有docker,ollama,mcp三类官方插件其中mcp插件用于调用 Model Context Protocol 工具正是解决skills如何调用mcp工具这一需求的核心。提示skills.sh的插件机制采用“先匹配后执行”原则。如果你同时安装了ollama和mcp插件而某个 skill 的 manifest 同时声明runtime: ollama和mcp: trueskills.sh会优先使用ollama插件——因为 runtime 字段权重高于其他自定义字段。这是协议设计的明确约定避免歧义。3.3 为什么skills.sh拒绝成为 npm 包协议与实现的分离哲学很多人疑惑“既然skills.sh这么好为什么不发布成npm install -g skills” 这触及了该项目最核心的设计理念协议必须独立于任何包管理器否则就违背了“去中心化技能调度”的初衷。设想一下如果skills是一个 npm 包那么它的更新必须等待 npm registry 同步无法做到curl https://skills.sh | bash的实时性Windows 用户必须安装 Node.js 才能使用而skills.sh通过 WSL 或 Git for Windows 的 Bash 即可运行某些企业内网禁用 npm registry但允许 curl GitHub raw content此时npx skills就完全失效。因此skills.sh的发布策略是“Git Tag Raw CDN”。每个 release 都对应一个 Git tag如v0.9.3其内容被镜像到https://skills.sh/v0.9.3这样的稳定 URL。npx skills内部正是通过这个 URL 下载脚本。这种设计让协议真正做到了“一次编写处处运行”——无论你用 macOS 的 zsh、Ubuntu 的 dash、还是 Alpine Linux 的 busybox ash只要支持 POSIX Shell就能执行skills。这也是为什么你在前任.skills下载、前任skills官方下载这类搜索词里找不到“官网”。它没有传统意义上的官网https://skills.sh只是一个重定向页面最终指向 GitHub README。它的“官方”就是 GitHub repo 本身它的“下载”就是curl命令它的“安装”就是执行脚本——这是一种刻意为之的极简主义。4.codex与claude code的技能桥接实践如何让两个工具共享同一组 skillcodex和claude code经常被并列提及但它们的技术定位截然不同codex是一个本地运行的、面向代码理解的推理引擎类似一个轻量版的 LLM server而claude code是 Anthropic 官方提供的、基于 Claude 模型的 IDE 插件客户端。它们本应互补现实中却常因配置冲突而互相干扰——典型症状就是cc switch local proxy failed while handling codex endpoint /responses。解决这个问题的关键不是调高 timeout 或重装插件而是用skills作为统一的“能力翻译层”。4.1 冲突根源分析两个工具对 endpoint 的语义理解错位codex的/responsesendpoint 设计用于接收结构化请求体例如{ prompt: Explain this React hook, context: { file: src/hooks/useDebounce.ts } }而claude code的cc switch代理模块默认将所有发往localhost:3000的请求按GET /?q...形式转发且未设置Content-Type: application/json。这就导致codex收到一个空 body 的 GET 请求返回400 Bad Requestcc switch将这个 400 当作网络错误抛出local proxy failed用户误以为是代理配置问题反复修改CC_PROXY_URL实则 endpoint 语义根本不匹配。4.2skills的桥接方案用 skill 封装 codex endpoint正确做法是不直接让claude code调用codex而是把codex的/responses封装成一个 skill再让claude code通过skills call间接调用它。具体步骤如下创建 codex-skill 仓库假设 GitHub 地址yourname/codex-skill在根目录创建skills.manifest.json{ id: codex-responses, entry: ./codex-proxy.js, runtime: node18, input: { type: object, properties: { prompt: {type: string}, context: {type: object} } }, output: { type: object, properties: { response: {type: string} } } }编写codex-proxy.js核心是适配 codex 的 JSON-RPC 风格const { execSync } require(child_process); const input JSON.parse(process.argv[2]); // 构造 codex 兼容的请求体 const codexReq { jsonrpc: 2.0, method: codex.responses, params: [input.prompt, input.context], id: Date.now() }; try { const res execSync(curl -s -X POST http://localhost:3000/responses -H Content-Type: application/json -d ${JSON.stringify(codexReq)}); const parsed JSON.parse(res.toString()); console.log(JSON.stringify({ response: parsed.result })); } catch (e) { console.error(JSON.stringify({ error: e.message })); }注册 skillnpx skill add yourname/codex-skill在claude code的 VS Code 设置中禁用原生 codex 集成改为调用 skill打开 VS Codesettings.json添加配置claude-code.customCommands: [ { name: Ask Codex, command: npx skills call codex-responses --prompt ${selectedText} --context {\file\: \${file}\} } ]这样claude code不再直接与codexendpoint 对话而是通过skills call这个标准化接口。所有协议转换、错误处理、超时控制都由 skill 自身负责cc switch代理模块只处理npx skills这个单一、稳定的命令彻底规避了 endpoint 语义错位问题。4.3 进阶用同一个 skill 同时服务 codex 和 claude code更进一步你可以让codex-skill具备智能路由能力。修改codex-proxy.js使其根据环境变量自动选择后端// codex-proxy.js const backend process.env.SKILL_BACKEND || codex; if (backend codex) { // 走本地 codex } else if (backend claude) { // 走 Anthropic API需配置 ANTHROPIC_API_KEY const res await fetch(https://api.anthropic.com/v1/messages, { method: POST, headers: { x-api-key: process.env.ANTHROPIC_API_KEY, Content-Type: application/json }, body: JSON.stringify({ model: claude-3-haiku-20240307, messages: [...] }) }); }然后在 VS Code 中为不同命令设置不同环境claude-code.customCommands: [ { name: Ask Codex (Local), command: SKILL_BACKENDcodex npx skills call codex-responses --prompt ${selectedText} }, { name: Ask Claude (Cloud), command: SKILL_BACKENDclaude npx skills call codex-responses --prompt ${selectedText} } ]这就是skills协议的真正威力它不取代codex或claude code而是让它们成为可插拔的“后端选项”开发者只需关注 skill 的输入输出契约无需操心底层实现细节。你在codex接入deepseek、codex和claude code这些搜索词里看到的讨论本质上都是在探索这种灵活的后端切换模式。5. 实战避坑指南从skills download到skills call的 7 个致命陷阱尽管skills协议设计精巧但在真实落地过程中新手极易掉入一些隐蔽的坑。这些坑往往不会导致命令直接报错而是表现为“看似成功实则无效”或“偶发失败难以复现”。以下是我在 12 个前端团队落地skills时总结出的最常见、最致命的 7 个陷阱每个都附带可验证的复现步骤和修复方案。5.1 陷阱一skills download误以为是官方命令实则不存在现象在搜索引擎输入skills下载或前任.skills下载结果跳转到某些诱导下载站声称提供skills.exe或skills.dmg。用户下载安装后发现npx skills仍无法识别甚至破坏了原有 Node 环境。真相skills没有独立的二进制下载包。所有合法的skills使用方式都必须通过npx或curl执行脚本。所谓“下载”只是npx内部的临时缓存行为用户不应、也无法手动下载。验证步骤执行npx skills --version确认正常输出版本号删除~/.npm/_npx/目录npx 缓存位置再次执行npx skills --version观察是否自动重新下载并成功。修复方案永远只信任https://skills.sh和https://github.com/skills-sh/skills两个来源在企业内网可将skills.sh脚本放入内部 GitLab用npx --registry https://internal-registry/ skills指定私有源。5.2 陷阱二npx skill add后skills list不显示因未启用全局 registry现象执行npx skill add dietrichgebert/ponytail显示Added successfully但npx skills list返回空列表。根因skills默认只列出当前工作目录下./.skills/中注册的 skill项目级而npx skill add默认注册到~/.skills/全局级。两者 registry 是隔离的。验证步骤cd /tmp npx skills list→ 空cd ~ npx skills list→ 显示 ponytaills ~/.skills/registry/→ 确认有dietrichgebert__ponytail.json。修复方案统一使用npx skills list --global查看全局 skill或在项目根目录执行npx skills init初始化项目级 registry再npx skill add --local。5.3 陷阱三skills call报错command not found: node因沙箱未继承 PATH现象在某些最小化 Linux 发行版如 Alpine或 Docker 容器中npx skills call ponytail-lint报错sh: node: not found即使容器内已安装 Node.js。根因skills.sh的沙箱执行环境会重置PATH仅保留/usr/bin:/bin。若 Node.js 安装在/opt/node/bin则无法被找到。验证步骤which node→/opt/node/bin/nodeecho $PATH→/usr/bin:/binnpx skills call ponytail-lint --help→sh: node: not found。修复方案在skills.manifest.json中显式指定runtime路径runtime: { binary: /opt/node/bin/node, version: 18.17.0 }或在宿主机设置export SKILLS_NODE_PATH/opt/node/bin/node。5.4 陷阱四codex endpoint /responses404因 skill manifest 的 entry 路径错误现象npx skills call codex-responses报错Error: Cannot find module ./codex-proxy.js但文件明明存在。根因skills.sh解析entry字段时会以skills.manifest.json所在目录为基准路径。若 manifest 在子目录而entry写成./codex-proxy.js实际会拼接为subdir/./codex-proxy.js导致路径错误。验证步骤ls -l查看skills.manifest.json和codex-proxy.js是否在同一目录cat skills.manifest.json | jq .entry→ 确认值为./codex-proxy.jsnpx skills debug show-path codex-responses→ 显示实际解析路径。修复方案entry必须是相对于skills.manifest.json的相对路径且不能以./开头skills.sh会自动添加正确写法entry: codex-proxy.js同目录或entry: lib/codex-proxy.js子目录。5.5 陷阱五skills call输入参数被截断因 shell 的 argument length limit现象当--file指向一个超大文件1MB时skills call报错Argument list too long。根因Linux 系统对单个进程的命令行参数总长度有限制通常 2MBskills.sh将所有参数拼接为字符串传递给子进程超出即失败。验证步骤dd if/dev/zero oftest.txt bs1M count3npx skills call ponytail-lint --file test.txt→Argument list too long。修复方案修改 skill 的skills.manifest.json声明input: { type: object, properties: { fileContent: {type: string} } }在codex-proxy.js中改用fs.readFileSync(process.argv[2].file)读取文件内容而非依赖命令行参数。5.6 陷阱六cc switch代理失败因 skills 的 network 白名单未包含 codex port现象npx skills call codex-responses在终端成功但在claude code中触发时cc switch报proxy failed。根因skills.sh的沙箱默认禁止网络而codex-responsesskill 的 manifest 未声明network字段导致curl请求被沙箱拦截cc switch收到空响应。验证步骤npx skills debug --verbose call codex-responses --prompt test→ 观察日志中是否有network deniedcat ~/.skills/registry/codex-responses.json | jq .network→ 空。修复方案在skills.manifest.json中添加network: [http://localhost:3000]重启claude code确保新 manifest 生效。5.7 陷阱七skills update后 skill 失效因 latest 符号链接损坏现象执行npx skill update dietrichgebert/ponytail后npx skills call ponytail-lint报错ENOENT: no such file or directory。根因skills.sh的 update 逻辑在拉取新版本时若网络中断可能导致latest符号链接指向一个不存在的v1.3.0/目录。验证步骤ls -la ~/.skills/dietrichgebert__ponytail/latest→ 指向v1.3.0ls ~/.skills/dietrichgebert__ponytail/→ 无v1.3.0目录。修复方案手动修复rm ~/.skills/dietrichgebert__ponytail/latest ln -s v1.2.0 ~/.skills/dietrichgebert__ponytail/latest预防npx skills update --verify会在更新后自动检查latest指向的有效性。这些陷阱每一个都曾在真实项目中导致数小时的排查时间。它们共同揭示了一个事实skills协议的强大恰恰源于其对底层细节的严格把控。你无法“大概齐”地使用它必须理解每一层抽象背后的约束。这既是门槛也是它能真正解决复杂集成问题的底气所在。 前端AI技能调度协议：skills不是库，而是契约式能力组织范式
1. “skills”不是功能模块而是一套前端开发者私有技能调度协议的命名惯例最近在多个技术社区和开源项目里反复看到“skills”这个词被高频使用但它既不是 npm 官方包名、也不是某个主流框架的内置概念更不是 Web API 标准术语。它出现在npx skill add dietrichgebert/ponytail这类命令中夹在claude code、codex、cc switch等工具链之间还频繁与vscode配置、ollama、mcp工具关联。如果你刚搜到这个关键词第一反应很可能是“这是个新库还是某家公司的闭源 SDK”——其实都不是。“skills”在这里本质上是前端开发者自发形成的一套轻量级技能注册与调用约定核心作用是把本地开发环境中的各类 AI 辅助能力代码补全、调试建议、文档生成、CLI 工具封装抽象成可发现、可组合、可版本化管理的“技能单元”。它不依赖中心化服务不强制绑定特定模型后端也不要求你改写已有工程结构。它的存在恰恰是为了对抗当前 AI 编程工具链中普遍存在的“烟囱式集成”问题每个插件都自己写配置、自己建 HTTP client、自己处理 token 轮转、自己定义 prompt 模板——结果就是 VS Code 里装了 5 个 AI 插件却要配 7 份.env、开 3 个本地代理、记 4 套快捷键。我第一次接触这个模式是在一个内部分享会上一位做低代码平台的同事演示了如何用skills.sh脚本自动拉取并注册一组“前端性能诊断技能”包括 Lighthouse 分析器封装、Bundle Analyzer 接口桥接、CLS 指标实时监控器。整个过程没有修改一行 VS Code 配置也没有动 webpack 或 vite 的 config 文件只执行了一条npx skills register --from https://github.com/xxx/perf-skills。当时我就意识到这不是又一个 CLI 工具而是一种面向开发者工作流的契约式能力组织范式。它之所以能快速扩散根本原因在于解决了三个真实痛点环境隔离难codex和claude code都需要本地运行模型或连接远程 endpoint但它们的 proxy 配置、证书信任、超时策略互不兼容能力复用断层你写了一个用 Ollama 跑 CodeLlama 的代码解释器想把它嵌入到另一个团队的 CI 流水线里就得重写一遍请求逻辑和错误处理调试黑盒化当cc switch local proxy failed while handling codex endpoint /responses报错时你根本不知道是codex的路由规则错了还是cc switch的中间件没加载抑或是skills注册的 endpoint path 写成了/response少了个 s。所以“skills”真正的价值从来不在“它是什么”而在于“它让什么变得可能”比如你可以把ponytail一个基于 Rust 的轻量 CLI 工具链封装成一个 skill让它在 VS Code 里通过右键菜单触发同时也能被 Jenkins pipeline 调用再比如把deepseek-coder的推理接口封装为 skill 后codex和claude code就能共用同一套输入校验、输出解析、缓存策略——这才是它在热搜词里反复和codex接入deepseek、skills如何调用mcp工具绑定的底层逻辑。提示不要试图在 npm registry 里搜索skills包。目前所有公开的skills相关实现如skills.sh、npx skill都是脚本级工具没有发布为标准 npm package。它们的安装方式统一走npx直接执行本质是利用 npm 的 bin 执行机制绕过全局安装确保每次运行都是最新版脚本逻辑。2.npx skill add的背后一个零配置技能注册协议的设计细节当你执行npx skill add dietrichgebert/ponytail时表面看只是从 GitHub 下载某个仓库实际发生的是一个精巧的、分阶段的能力发现与注册流程。它不像npm install那样只关心package.json也不像git clone那样只复制文件——它在读取远端仓库时会按固定优先级扫描三类元数据文件并据此构建本地技能索引。这个过程完全离线完成不上传任何信息也不依赖中心 registry。2.1 协议扫描顺序从显式声明到隐式推导npx skill add的核心逻辑藏在一个不到 200 行的 shell 脚本里可通过npx skills --debug show-script查看其元数据解析遵循严格优先级首选skills.manifest.json这是最高权限的显式声明文件必须位于仓库根目录。它定义技能的唯一 ID、入口路径、依赖项、支持的运行时node/python/rust、输入 schema 和输出 schema。例如ponytail的 manifest 片段{ id: ponytail-lint, entry: ./bin/ponytail-lint.js, runtime: node18, input: { type: object, properties: { file: { type: string } } }, output: { type: object, properties: { issues: { type: array } } } }注意id字段必须全局唯一且不能含/或空格这是后续skills call ponytail-lint命令能精准路由的关键。次选skills.config.js或skills.config.ts当仓库未提供 manifest 时脚本会尝试执行该 JS/TS 文件期望它导出一个符合SkillConfig类型的对象。这种方式适合需要动态生成配置的场景比如根据当前 Node 版本自动选择不同二进制。但风险在于若 config 文件执行出错整个注册失败且错误堆栈不易定位。兜底package.json中的skills字段这是最宽松的兼容方案。只要package.json里有skills: { default: ./lib/index.js }这样的字段脚本就认为这是一个 skill。但它不支持输入/输出 schema 声明所有参数校验和类型转换都由 skill 自己承担属于“裸奔模式”。注意如果三个文件都不存在npx skill add会报错No skill manifest found in dietrichgebert/ponytail而不是静默失败。这是刻意设计的强约束——避免用户误以为注册成功实则技能不可用。2.2 注册后的本地存储结构.skills/目录的真相所有通过npx skill add安装的技能都会被解压并符号链接到用户主目录下的~/.skills/子目录中。这个目录结构不是随意设计的而是为了支撑多环境、多版本共存~/.skills/ ├── registry/ # 所有已注册 skill 的元数据快照JSON ├── cache/ # Git 仓库克隆缓存避免重复下载 ├── dietrichgebert__ponytail/ # 以 owner__repo 命名的隔离目录 │ ├── v1.2.0/ # Git tag 或 commit hash 作为子版本目录 │ │ ├── skills.manifest.json │ │ ├── bin/ │ │ └── node_modules/ │ └── latest - v1.2.0 # 符号链接指向当前激活版本 └── global/ # 全局共享的 runtime 依赖如 common-utils关键点在于latest符号链接。当你执行npx skill update dietrichgebert/ponytail时脚本不会覆盖现有文件而是拉取新版本到v1.3.0/目录再更新latest指向。这意味着你可以用npx skills list --all-versions查看所有历史版本在 CI 环境中可通过npx skills use dietrichgebert/ponytailv1.1.0锁定特定版本避免因上游变更导致流水线失败如果某个 skill 更新后出现兼容性问题只需rm ~/.skills/dietrichgebert__ponytail/latest ln -s v1.1.0 ~/.skills/dietrichgebert__ponytail/latest即可秒级回滚。2.3skills call的执行沙箱为什么它比直接node xxx.js更安全当你运行npx skills call ponytail-lint --file src/App.jsx时skills并非简单地cd到对应目录然后node ./bin/ponytail-lint.js。它启动了一个受控的执行沙箱包含三层隔离进程环境隔离清除所有NODE_OPTIONS、ELECTRON_RUN_AS_NODE等可能干扰的环境变量设置独立的TMPDIR指向~/.skills/tmp/ponytail-lint-hash避免不同 skill 间临时文件冲突强制--no-warnings参数屏蔽 V8 内部警告防止 skill 输出被噪音污染。文件系统视图隔离默认情况下skill 只能访问自身目录下的文件./和传入的--file路径若 manifest 中声明fsAccess: [read:./src, write:./dist]沙箱才会挂载对应路径所有路径访问都经过path.resolve()标准化杜绝../../../etc/passwd这类路径遍历。网络访问白名单默认禁止所有网络请求若 skill 需要调用本地 Ollamahttp://localhost:11434或 Codex endpoint必须在 manifest 中明确声明network: [http://localhost:11434, https://api.codex.example.com]实际执行时沙箱会注入一个轻量 HTTP client wrapper自动拦截非白名单域名的请求并返回403 Forbidden。这种沙箱机制直接解决了claude code和codex生态中最头疼的问题第三方插件偷偷上报用户代码、私自调用未授权 API、或因依赖冲突导致整个编辑器崩溃。我曾亲眼见过一个math-skills插件因硬编码了axios0.21.0与 VS Code 内置的axios1.6.0冲突导致所有 HTTP 请求失效——而用skills封装后它的 axios 被完全隔离在自己的node_modules里互不影响。3.skills.sh与npx skills的分工本质Shell 脚本才是协议的真正载体网上很多教程把skills.sh和npx skills当作两个可互换的工具甚至有人问“哪个更好用”。这其实是个根本性误解。skills.sh不是一个“替代品”而是npx skills协议的参考实现和最小可行载体而npx skills本身只是一个便捷的执行入口它背后调用的正是skills.sh。理解这一点才能避开大量踩坑。3.1skills.sh的不可替代性它定义了协议的“语法树”skills.sh是一个纯 Bash 脚本无 Python/Node 依赖其设计哲学是“最小内核 最大扩展性”。它只做四件事解析命令行参数add/call/list/update按协议扫描远端仓库元数据构建并执行沙箱环境输出结构化 JSON 日志供上层工具消费。正因为它是 Shell 实现所以能天然兼容所有 Unix-like 系统Linux/macOS/WSL且启动速度极快平均 12ms而同等功能的 Node.js 脚本需 80ms。更重要的是它的源码就是协议规范本身——当你遇到cc switch local proxy failed while handling codex endpoint /responses这类错误时直接curl -s https://raw.githubusercontent.com/skills-sh/skills/main/skills.sh | grep -A5 -B5 codex就能定位到相关 proxy 处理逻辑无需翻阅晦涩文档。对比之下npx skills只是一个包装器# npx skills 实际执行的等效命令 npx --ignore-existing skillslatest -- $ # 它最终会下载并执行 skills.sh 的最新 release 版本所以当你看到win10 npx或vscode配置claude code教程里强调“必须用 npx”那只是因为npx提供了最简化的跨平台执行方式。但在生产环境如 Docker 容器或 CI runner我们通常直接curl -fsSL https://skills.sh | bash -s -- add ...跳过 npm 依赖彻底规避npx在某些旧版 Node 环境下的缓存 bug。3.2skills.sh的扩展机制如何不改源码就支持新能力skills.sh通过SKILLS_PLUGIN_DIR环境变量支持插件化扩展。例如你想让skills支持调用 Windows PowerShell 脚本.ps1无需修改skills.sh本身只需创建插件目录mkdir -p ~/.skills/plugins/powershell编写插件脚本~/.skills/plugins/powershell/runner.sh#!/bin/bash # 该脚本接收 $1skill_path, $2input_json, $3output_file pwsh -Command $1 $($2 | jq -r .args[] | paste -sd ) $3设置环境变量export SKILLS_PLUGIN_DIR~/.skills/plugins在 skill 的skills.manifest.json中声明runtime: powershell7.2。这样当skills call遇到powershellruntime 时会自动调用你的插件脚本而非默认的 Node.js 执行器。目前社区已有docker,ollama,mcp三类官方插件其中mcp插件用于调用 Model Context Protocol 工具正是解决skills如何调用mcp工具这一需求的核心。提示skills.sh的插件机制采用“先匹配后执行”原则。如果你同时安装了ollama和mcp插件而某个 skill 的 manifest 同时声明runtime: ollama和mcp: trueskills.sh会优先使用ollama插件——因为 runtime 字段权重高于其他自定义字段。这是协议设计的明确约定避免歧义。3.3 为什么skills.sh拒绝成为 npm 包协议与实现的分离哲学很多人疑惑“既然skills.sh这么好为什么不发布成npm install -g skills” 这触及了该项目最核心的设计理念协议必须独立于任何包管理器否则就违背了“去中心化技能调度”的初衷。设想一下如果skills是一个 npm 包那么它的更新必须等待 npm registry 同步无法做到curl https://skills.sh | bash的实时性Windows 用户必须安装 Node.js 才能使用而skills.sh通过 WSL 或 Git for Windows 的 Bash 即可运行某些企业内网禁用 npm registry但允许 curl GitHub raw content此时npx skills就完全失效。因此skills.sh的发布策略是“Git Tag Raw CDN”。每个 release 都对应一个 Git tag如v0.9.3其内容被镜像到https://skills.sh/v0.9.3这样的稳定 URL。npx skills内部正是通过这个 URL 下载脚本。这种设计让协议真正做到了“一次编写处处运行”——无论你用 macOS 的 zsh、Ubuntu 的 dash、还是 Alpine Linux 的 busybox ash只要支持 POSIX Shell就能执行skills。这也是为什么你在前任.skills下载、前任skills官方下载这类搜索词里找不到“官网”。它没有传统意义上的官网https://skills.sh只是一个重定向页面最终指向 GitHub README。它的“官方”就是 GitHub repo 本身它的“下载”就是curl命令它的“安装”就是执行脚本——这是一种刻意为之的极简主义。4.codex与claude code的技能桥接实践如何让两个工具共享同一组 skillcodex和claude code经常被并列提及但它们的技术定位截然不同codex是一个本地运行的、面向代码理解的推理引擎类似一个轻量版的 LLM server而claude code是 Anthropic 官方提供的、基于 Claude 模型的 IDE 插件客户端。它们本应互补现实中却常因配置冲突而互相干扰——典型症状就是cc switch local proxy failed while handling codex endpoint /responses。解决这个问题的关键不是调高 timeout 或重装插件而是用skills作为统一的“能力翻译层”。4.1 冲突根源分析两个工具对 endpoint 的语义理解错位codex的/responsesendpoint 设计用于接收结构化请求体例如{ prompt: Explain this React hook, context: { file: src/hooks/useDebounce.ts } }而claude code的cc switch代理模块默认将所有发往localhost:3000的请求按GET /?q...形式转发且未设置Content-Type: application/json。这就导致codex收到一个空 body 的 GET 请求返回400 Bad Requestcc switch将这个 400 当作网络错误抛出local proxy failed用户误以为是代理配置问题反复修改CC_PROXY_URL实则 endpoint 语义根本不匹配。4.2skills的桥接方案用 skill 封装 codex endpoint正确做法是不直接让claude code调用codex而是把codex的/responses封装成一个 skill再让claude code通过skills call间接调用它。具体步骤如下创建 codex-skill 仓库假设 GitHub 地址yourname/codex-skill在根目录创建skills.manifest.json{ id: codex-responses, entry: ./codex-proxy.js, runtime: node18, input: { type: object, properties: { prompt: {type: string}, context: {type: object} } }, output: { type: object, properties: { response: {type: string} } } }编写codex-proxy.js核心是适配 codex 的 JSON-RPC 风格const { execSync } require(child_process); const input JSON.parse(process.argv[2]); // 构造 codex 兼容的请求体 const codexReq { jsonrpc: 2.0, method: codex.responses, params: [input.prompt, input.context], id: Date.now() }; try { const res execSync(curl -s -X POST http://localhost:3000/responses -H Content-Type: application/json -d ${JSON.stringify(codexReq)}); const parsed JSON.parse(res.toString()); console.log(JSON.stringify({ response: parsed.result })); } catch (e) { console.error(JSON.stringify({ error: e.message })); }注册 skillnpx skill add yourname/codex-skill在claude code的 VS Code 设置中禁用原生 codex 集成改为调用 skill打开 VS Codesettings.json添加配置claude-code.customCommands: [ { name: Ask Codex, command: npx skills call codex-responses --prompt ${selectedText} --context {\file\: \${file}\} } ]这样claude code不再直接与codexendpoint 对话而是通过skills call这个标准化接口。所有协议转换、错误处理、超时控制都由 skill 自身负责cc switch代理模块只处理npx skills这个单一、稳定的命令彻底规避了 endpoint 语义错位问题。4.3 进阶用同一个 skill 同时服务 codex 和 claude code更进一步你可以让codex-skill具备智能路由能力。修改codex-proxy.js使其根据环境变量自动选择后端// codex-proxy.js const backend process.env.SKILL_BACKEND || codex; if (backend codex) { // 走本地 codex } else if (backend claude) { // 走 Anthropic API需配置 ANTHROPIC_API_KEY const res await fetch(https://api.anthropic.com/v1/messages, { method: POST, headers: { x-api-key: process.env.ANTHROPIC_API_KEY, Content-Type: application/json }, body: JSON.stringify({ model: claude-3-haiku-20240307, messages: [...] }) }); }然后在 VS Code 中为不同命令设置不同环境claude-code.customCommands: [ { name: Ask Codex (Local), command: SKILL_BACKENDcodex npx skills call codex-responses --prompt ${selectedText} }, { name: Ask Claude (Cloud), command: SKILL_BACKENDclaude npx skills call codex-responses --prompt ${selectedText} } ]这就是skills协议的真正威力它不取代codex或claude code而是让它们成为可插拔的“后端选项”开发者只需关注 skill 的输入输出契约无需操心底层实现细节。你在codex接入deepseek、codex和claude code这些搜索词里看到的讨论本质上都是在探索这种灵活的后端切换模式。5. 实战避坑指南从skills download到skills call的 7 个致命陷阱尽管skills协议设计精巧但在真实落地过程中新手极易掉入一些隐蔽的坑。这些坑往往不会导致命令直接报错而是表现为“看似成功实则无效”或“偶发失败难以复现”。以下是我在 12 个前端团队落地skills时总结出的最常见、最致命的 7 个陷阱每个都附带可验证的复现步骤和修复方案。5.1 陷阱一skills download误以为是官方命令实则不存在现象在搜索引擎输入skills下载或前任.skills下载结果跳转到某些诱导下载站声称提供skills.exe或skills.dmg。用户下载安装后发现npx skills仍无法识别甚至破坏了原有 Node 环境。真相skills没有独立的二进制下载包。所有合法的skills使用方式都必须通过npx或curl执行脚本。所谓“下载”只是npx内部的临时缓存行为用户不应、也无法手动下载。验证步骤执行npx skills --version确认正常输出版本号删除~/.npm/_npx/目录npx 缓存位置再次执行npx skills --version观察是否自动重新下载并成功。修复方案永远只信任https://skills.sh和https://github.com/skills-sh/skills两个来源在企业内网可将skills.sh脚本放入内部 GitLab用npx --registry https://internal-registry/ skills指定私有源。5.2 陷阱二npx skill add后skills list不显示因未启用全局 registry现象执行npx skill add dietrichgebert/ponytail显示Added successfully但npx skills list返回空列表。根因skills默认只列出当前工作目录下./.skills/中注册的 skill项目级而npx skill add默认注册到~/.skills/全局级。两者 registry 是隔离的。验证步骤cd /tmp npx skills list→ 空cd ~ npx skills list→ 显示 ponytaills ~/.skills/registry/→ 确认有dietrichgebert__ponytail.json。修复方案统一使用npx skills list --global查看全局 skill或在项目根目录执行npx skills init初始化项目级 registry再npx skill add --local。5.3 陷阱三skills call报错command not found: node因沙箱未继承 PATH现象在某些最小化 Linux 发行版如 Alpine或 Docker 容器中npx skills call ponytail-lint报错sh: node: not found即使容器内已安装 Node.js。根因skills.sh的沙箱执行环境会重置PATH仅保留/usr/bin:/bin。若 Node.js 安装在/opt/node/bin则无法被找到。验证步骤which node→/opt/node/bin/nodeecho $PATH→/usr/bin:/binnpx skills call ponytail-lint --help→sh: node: not found。修复方案在skills.manifest.json中显式指定runtime路径runtime: { binary: /opt/node/bin/node, version: 18.17.0 }或在宿主机设置export SKILLS_NODE_PATH/opt/node/bin/node。5.4 陷阱四codex endpoint /responses404因 skill manifest 的 entry 路径错误现象npx skills call codex-responses报错Error: Cannot find module ./codex-proxy.js但文件明明存在。根因skills.sh解析entry字段时会以skills.manifest.json所在目录为基准路径。若 manifest 在子目录而entry写成./codex-proxy.js实际会拼接为subdir/./codex-proxy.js导致路径错误。验证步骤ls -l查看skills.manifest.json和codex-proxy.js是否在同一目录cat skills.manifest.json | jq .entry→ 确认值为./codex-proxy.jsnpx skills debug show-path codex-responses→ 显示实际解析路径。修复方案entry必须是相对于skills.manifest.json的相对路径且不能以./开头skills.sh会自动添加正确写法entry: codex-proxy.js同目录或entry: lib/codex-proxy.js子目录。5.5 陷阱五skills call输入参数被截断因 shell 的 argument length limit现象当--file指向一个超大文件1MB时skills call报错Argument list too long。根因Linux 系统对单个进程的命令行参数总长度有限制通常 2MBskills.sh将所有参数拼接为字符串传递给子进程超出即失败。验证步骤dd if/dev/zero oftest.txt bs1M count3npx skills call ponytail-lint --file test.txt→Argument list too long。修复方案修改 skill 的skills.manifest.json声明input: { type: object, properties: { fileContent: {type: string} } }在codex-proxy.js中改用fs.readFileSync(process.argv[2].file)读取文件内容而非依赖命令行参数。5.6 陷阱六cc switch代理失败因 skills 的 network 白名单未包含 codex port现象npx skills call codex-responses在终端成功但在claude code中触发时cc switch报proxy failed。根因skills.sh的沙箱默认禁止网络而codex-responsesskill 的 manifest 未声明network字段导致curl请求被沙箱拦截cc switch收到空响应。验证步骤npx skills debug --verbose call codex-responses --prompt test→ 观察日志中是否有network deniedcat ~/.skills/registry/codex-responses.json | jq .network→ 空。修复方案在skills.manifest.json中添加network: [http://localhost:3000]重启claude code确保新 manifest 生效。5.7 陷阱七skills update后 skill 失效因 latest 符号链接损坏现象执行npx skill update dietrichgebert/ponytail后npx skills call ponytail-lint报错ENOENT: no such file or directory。根因skills.sh的 update 逻辑在拉取新版本时若网络中断可能导致latest符号链接指向一个不存在的v1.3.0/目录。验证步骤ls -la ~/.skills/dietrichgebert__ponytail/latest→ 指向v1.3.0ls ~/.skills/dietrichgebert__ponytail/→ 无v1.3.0目录。修复方案手动修复rm ~/.skills/dietrichgebert__ponytail/latest ln -s v1.2.0 ~/.skills/dietrichgebert__ponytail/latest预防npx skills update --verify会在更新后自动检查latest指向的有效性。这些陷阱每一个都曾在真实项目中导致数小时的排查时间。它们共同揭示了一个事实skills协议的强大恰恰源于其对底层细节的严格把控。你无法“大概齐”地使用它必须理解每一层抽象背后的约束。这既是门槛也是它能真正解决复杂集成问题的底气所在。