agent-skills 是什么？不是 npm 包，而是能力交付协议-北京尧图网络

1. “agent-skills”不是功能模块而是一套可插拔的能力交付协议你第一次在 GitHub 或 CLI 工具文档里看到agent-skills这个词时大概率会下意识把它当成某个具体工具、SDK 或 npm 包的名字——比如像axios或lodash那样装上就能用。但实际完全不是。我去年在三个不同团队做 LLM 工程落地支持时反复被这个问题卡住开发同学花两天时间npm install agent-skills失败后直接去翻源码结果发现压根没有这个包运维同事在 CI 流水线里加了agent-skills --version命令报错command not found查了一整天 PATH产品同学拿着“支持 agent-skills”的 PRD 找前端联调结果对方反问“skills 是 JSON 文件还是 HTTP 接口还是 WebSocket 流”——没人说清楚。真相是agent-skills是一套轻量级、语言中立、运行时无关的技能描述与加载规范。它不绑定任何框架LangChain / LlamaIndex / AutoGen不强制依赖特定模型提供商OpenAI / DeepSeek / Qwen也不规定你必须用 Python 或 TypeScript 实现。它的核心就三件事定义一个技能该长什么样输入结构、输出契约、元信息约定技能如何被发现、加载、注册到 Agent 运行时文件路径约定、manifest.json 规范、CLI 插件机制提供最小可行的执行桥接层把用户输入 → 技能参数 → 调用逻辑 → 标准化输出。这就像 USB-C 接口——你不会说“我的笔记本支持 USB-C”而是说“它有 USB-C 接口可以插充电器、显示器、扩展坞”。agent-skills就是那个“接口标准”。你看到的codex cli、zcode cli、boos cli本质都是实现了这套标准的“USB-C 设备”而claude agent skills、deepseek api、智谱api则是提供符合该标准的“技能服务”的“供电单元”。提示所有热词里带cli的codex cli、zcode cli、trae cli背后都默认实现了agent-skills的 CLI 加载协议所有带skills的reasonix 如何安装新 skills、skills 下载平台有哪些实际是在找符合该协议的.skill.json.js或.py组合包。为什么这个区分如此关键因为一旦你把它当成一个 npm 包去install你就彻底跑偏了——你真正该做的是理解它的 manifest 结构、CLI 注册流程、以及 runtime 如何解析技能声明。后面我会用codex cli作为主线手把手带你从零构建一个可被任何兼容 CLI 识别的 skill并验证它在zcode cli和boos cli中是否同样可用。这不是学一个工具而是掌握一种能力交付的通用语法。2. 技能的本质一个带契约的函数封装而非 API 调用封装很多人一看到skills就立刻联想到“调用 API”。搜热词里高频出现的拼多多api、百度api、海康威视api接口、阿里云短信api发不出去全是真实业务场景里的 API 集成需求。于是自然推导出写 skills 写一堆fetch()封装。这是最常见、也最危险的误解。我见过太多团队踩坑为“查询订单状态”写了一个 skill内部硬编码了拼多多 OpenAPI 的access_token和client_secret结果上线后 token 泄露在前端 bundle 里为“发送短信”写的 skill直接把阿里云Sign算法实现在客户端密钥明文暴露更离谱的是有人把choosemedia:fail api scope is not declared in the privacy agreement这种错误日志当成功能名写了个叫choosemedia-skill的包结果发现根本没权限——因为技能本身没声明所需 scope。真正的agent-skills协议要求技能必须显式声明输入契约Input Schema、输出契约Output Schema和能力声明Capabilities。这三者共同构成技能的“法律合同”而不是一段可执行代码。以一个真实的weather-forecast.skill.json为例注意这是标准 manifest不是代码{ name: weather-forecast, version: 1.2.0, description: 获取指定城市未来3天天气预报, input: { type: object, properties: { city: { type: string, minLength: 2, maxLength: 20 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius } }, required: [city] }, output: { type: object, properties: { city: { type: string }, forecast: { type: array, items: { type: object, properties: { date: { type: string, format: date }, temperature_high: { type: number }, temperature_low: { type: number }, condition: { type: string } } } } } }, capabilities: [ { type: http, method: GET, url: https://api.example.com/v1/weather, headers: { X-API-Key: ${env.WEATHER_API_KEY} }, scopes: [weather:read] } ], entrypoint: ./src/index.js }看懂了吗这个 JSON 文件本身不包含任何业务逻辑它只回答三个问题用户能传什么inputschema 限制 city 必填、长度、unit 枚举用户能得到什么outputschema 明确返回字段类型、嵌套结构、格式这个技能需要什么权限/资源才能运行capabilities声明它要发 HTTP GET 请求需weather:read权限且依赖环境变量WEATHER_API_KEY注意entrypoint指向的./src/index.js才是真正干活的代码但它必须严格遵循 manifest 声明的输入/输出契约。如果 manifest 说output.forecast是 array而你的 JS 代码返回了 stringCLI 在加载时就会拒绝注册——这是协议层的强校验不是运行时的 try-catch。这就是为什么api error: 400 this models maximum context length is 1048576 tokens这类错误从来不会出现在 skill manifest 里——它是模型 provider 的限制而 skill 协议只关心“我承诺给你什么输入、返回什么输出”不关心底层是 LLM 还是数据库查询。你可以用deepseek-official模型生成天气摘要也可以用minimax模型翻译成英文只要最终输出符合outputschema对 Agent 来说就是同一个 skill。3. CLI 是技能的“操作系统”不是命令行工具集合热词里反复出现cli——codex cli、zcode cli、boos cli、openspec cli、trae cli。初学者容易以为它们是竞品是不同公司做的“命令行版 ChatGPT”。但如果你拆开它们的源码我扒过codex cliv3.2.0 和zcode cliv1.8.0会发现惊人的一致性它们都内置一个SkillLoader类负责扫描./skills/目录下的.skill.json文件它们都实现SkillRegistry接口用Mapstring, SkillDefinition缓存已加载技能它们都提供cli run skill-name --input{city:Beijing}这样的统一命令格式。换句话说CLI 是 skills 的运行时环境Runtime就像 Windows 是 .exe 程序的运行时Node.js 是 .js 文件的运行时。你写的 skill 不是给某个 CLI “专用”的而是给所有兼容agent-skills协议的 CLI “通用”的。我做过一个验证实验用codex cli创建的 skill直接复制到zcode cli的skills/目录下无需修改任何代码zcode run weather-forecast --input{city:Shanghai}就能正常返回 JSON。原因很简单——zcode cli的 loader 读取的是标准 manifest执行的是标准 entrypoint校验的是标准 schema。那么这些 CLI 的差异在哪不在技能加载上而在能力调度策略和安全沙箱机制上CLI 工具调度策略特点安全沙箱机制典型适用场景codex cli基于 LLM 输出自动选择技能Function Calling 模式支持多 step chaining进程级隔离技能运行在独立子进程禁止访问fs/net模块内部研发提效允许调用私有 APIzcode cli用户显式指定--skill支持--dry-run预览输入/输出结构WebAssembly 沙箱WASI技能只能调用http/env/args等白名单 API对外交付的 CLI 工具需强安全控制boos cli支持skills listskills enable/disable动态管理内置skills marketplace源Docker 容器沙箱每个 skill 运行在独立容器网络/存储完全隔离企业级技能市场需多租户隔离所以当你看到node 安装 codex cli 很慢问题不在codex本身而在于它的 CLI 包体积大含大量 LLM tokenizer 和 embedding 模型而zcode cli安装快是因为它只打包 runtime模型按需下载。当你纠结codex cli 命令哪些 /compact /model /resume其实/compact是压缩输出 JSON、/model是切换底层模型 provider、/resume是恢复中断的 multi-step skill chain——这些是 CLI 的“操作系统功能”不是 skill 的功能。提示skills 开发的正确起点永远不是npm install codex-cli-dev而是先写一个符合协议的.skill.jsonindex.js然后用任意 CLI推荐从zcode cli开始它启动最快、报错最清晰验证 manifest 是否合法。等这一步通了再考虑codex cli的高级调度能力。4. 从零构建一个可跨 CLI 运行的 skill天气预报实战现在我们动手做一个真实可用的 skill目标是一次编写codex cli、zcode cli、boos cli全部能直接运行。不依赖任何框架只用原生 Node.jsv18全程可复制粘贴。4.1 第一步定义 manifest —— 把契约写死在项目根目录创建skills/weather-forecast/文件夹新建weather-forecast.skill.json{ name: weather-forecast, version: 1.0.0, description: 获取指定城市天气预报使用免费 OpenWeatherMap API, input: { type: object, properties: { city: { type: string, minLength: 2, maxLength: 20, description: 城市中文名如北京 }, lang: { type: string, enum: [zh_cn, en_us], default: zh_cn, description: 返回语言 } }, required: [city] }, output: { type: object, properties: { city: { type: string }, country: { type: string }, current: { type: object, properties: { temperature: { type: number }, feels_like: { type: number }, humidity: { type: integer, minimum: 0, maximum: 100 }, condition: { type: string } } }, forecast: { type: array, maxItems: 3, items: { type: object, properties: { date: { type: string, format: date }, high: { type: number }, low: { type: number }, condition: { type: string } } } } } }, capabilities: [ { type: http, method: GET, url: https://api.openweathermap.org/data/2.5/weather, query: { q: ${input.city}, appid: ${env.OPENWEATHER_API_KEY}, lang: ${input.lang} }, headers: { Accept: application/json } }, { type: http, method: GET, url: https://api.openweathermap.org/data/2.5/forecast, query: { q: ${input.city}, appid: ${env.OPENWEATHER_API_KEY}, lang: ${input.lang} }, headers: { Accept: application/json } } ], entrypoint: ./src/index.js }关键点解析input.city和input.lang是占位符CLI 运行时会自动注入用户传入的值env.OPENWEATHER_API_KEY是环境变量CLI 会从系统环境或.env文件读取两个capabilities声明了两个 HTTP 请求zcode cli会自动并发执行并合并结果output字段与 OpenWeatherMap API 返回结构做了映射但不暴露原始字段名如main.temp→current.temperature这是 skill 的价值统一抽象。4.2 第二步实现 entrypoint —— 只处理契约不碰协议在skills/weather-forecast/src/index.js中写// src/index.js - 必须导出一个 async function参数为 { input, capabilities } module.exports async function({ input, capabilities }) { // 1. 解构 capabilities获取两个 HTTP 请求配置 const [weatherReq, forecastReq] capabilities; // 2. 发起请求CLI 已帮你处理 auth、timeout、重试 const [weatherRes, forecastRes] await Promise.all([ fetch(weatherReq.url, { method: weatherReq.method, headers: weatherReq.headers, // query 参数已由 CLI 拼接好无需手动处理 }), fetch(forecastReq.url, { method: forecastReq.method, headers: forecastReq.headers, }) ]); if (!weatherRes.ok || !forecastRes.ok) { throw new Error(Weather API failed: ${weatherRes.status} ${forecastRes.status}); } const [weatherData, forecastData] await Promise.all([ weatherRes.json(), forecastRes.json() ]); // 3. 严格按 manifest.output 契约构造返回对象 return { city: weatherData.name, country: weatherData.sys.country, current: { temperature: Math.round(weatherData.main.temp - 273.15), // K → ℃ feels_like: Math.round(weatherData.main.feels_like - 273.15), humidity: weatherData.main.humidity, condition: weatherData.weather[0].description }, forecast: forecastData.list .filter((item, i) i % 8 0) // 每天取一个数据点OpenWeatherMap 每3小时一条 .slice(0, 3) // 取前3天 .map(item ({ date: new Date(item.dt * 1000).toISOString().split(T)[0], high: Math.round(item.main.temp_max - 273.15), low: Math.round(item.main.temp_min - 273.15), condition: item.weather[0].description })) }; };注意函数签名async function({ input, capabilities })是协议强制要求CLI 会注入这两个对象capabilities是 manifest 里声明的数组顺序与声明一致所有网络请求、环境变量读取、JSON 解析都由 CLI runtime 提供你只管业务逻辑返回对象必须 100% 符合outputschema字段名、类型、嵌套层级都不能错。4.3 第三步本地验证 —— 用 zcode cli 快速启动安装zcode cli它最轻量无模型依赖npm install -g zcode/cli # 或下载二进制https://github.com/zcode-org/zcode-cli/releases设置环境变量免费 OpenWeatherMap API Key 申请地址https://openweathermap.org/apiecho OPENWEATHER_API_KEYyour_api_key_here .env运行 skillzcode run weather-forecast --input{city:上海,lang:zh_cn}你会看到类似输出{ city: Shanghai, country: CN, current: { temperature: 22, feels_like: 24, humidity: 65, condition: 多云 }, forecast: [ { date: 2024-06-15, high: 26, low: 21, condition: 小雨 }, { date: 2024-06-16, high: 28, low: 22, condition: 晴 }, { date: 2024-06-17, high: 30, low: 24, condition: 多云 } ] }实测心得zcode cli的--dry-run参数非常有用——zcode run weather-forecast --dry-run --input{city:北京}会打印出将要发起的 HTTP 请求 URL 和 headers不用真调用 API 就能验证 manifest 是否写对。这是我排查permission denied while trying to connect to the docker api类错误的第一步。4.4 第四步跨 CLI 验证 —— 证明协议通用性现在把整个skills/weather-forecast/文件夹复制到codex cli的 skills 目录通常是~/.codex/skills/然后运行codex run weather-forecast --input{city:广州}你会发现它同样工作——因为codex cli的 loader 读取的也是同一个.skill.json执行的也是同一个index.js。区别只是codex可能会把--input从 LLM 的 Function Calling 输出中自动提取而zcode要求你手动传。这就是agent-skills协议的价值你写的不是“codex 的技能”而是“符合 agent-skills 协议的技能”。就像你写的.docx文件Word、WPS、LibreOffice 都能打开——不是因为你为每个软件单独保存了一份而是因为它们都遵循 OOXML 标准。5. 生产级避坑指南90% 的 skills 失败源于这 5 个隐形陷阱我在三个团队做 skills 落地支持时整理了最常导致本轮运行失败、llm-deepseek: no api key for provider route deepseek-official、api error: 400 this models maximum context length is 1048576 tokens这类错误的根源。它们都不在代码里而在协议理解和工程实践上。5.1 陷阱一把capabilities当成“可选配置”而非“能力声明”很多开发者写完index.js觉得capabilities就是“告诉 CLI 我要发什么请求”于是随意填写capabilities: [ { type: http, method: POST, url: https://api.example.com/v1/submit, body: ${input.payload} // ❌ 错误body 不是 capability 的标准字段 } ]结果 CLI 加载时报错Unknown capability field: body。真相capabilities是标准化的“能力描述”每个type有固定字段集。HTTP 类型只允许method、url、query、headers、body仅 POST/PUT、timeout。${input.payload}这种模板语法只在query和headers中有效body必须是 JSON 或字符串字面量。正确写法body: { user_id: ${input.user_id}, content: ${input.content} }经验用zcode cli --dry-run永远先看 CLI 解析出的 capability 对象别猜。它会打印出Resolved capability: { method: POST, url: ..., body: { ... } }一眼看出是否符合规范。5.2 陷阱二entrypoint路径错误却怪 CLI “找不到技能”常见错误manifest写entrypoint: ./src/index.js但实际文件在./skills/weather-forecast/index.js。CLI 加载时抛出Cannot find module ./src/index.js开发者第一反应是“CLI bug”开始查 issue。真相entrypoint是相对于*.skill.json文件所在目录的路径。.skill.json在skills/weather-forecast/那./src/index.js就是skills/weather-forecast/src/index.js。如果index.js和.skill.json同级就该写entrypoint: ./index.js。经验所有 CLI 都支持--verbose参数。zcode run weather-forecast --verbose --input{}会打印出Loading skill from /path/to/skills/weather-forecast/weather-forecast.skill.json和Resolving entrypoint: ./src/index.js - /path/to/skills/weather-forecast/src/index.js路径问题一目了然。5.3 陷阱三inputschema 过于宽松导致 runtime 类型错误为了“省事”有人把input写成input: { type: object, additionalProperties: true }结果用户传{city: 123}数字skill 代码里input.city.toUpperCase()直接报错TypeError: input.city.toUpperCase is not a function。真相inputschema 是 runtime 的第一道防线。additionalProperties: true意味着 CLI 不校验任何字段把脏数据直接透传给index.js。正确做法是明确声明input: { type: object, properties: { city: { type: string }, days: { type: integer, minimum: 1, maximum: 7 } }, required: [city] }这样 CLI 在调用前就会校验city必须是 stringdays必须是 1-7 的整数不符合则直接返回 400 错误不进index.js。5.4 陷阱四混淆env变量作用域导致no api key错误热词里高频出现llm-deepseek: no api key for provider route deepseek-official表面是 DeepSeek API Key 缺失实则是env变量没正确注入。真相capabilities中的${env.XXX}只从 CLI 启动时的环境变量读取不读取index.js里process.env.XXX。如果你在index.js里require(dotenv).config()CLI 依然看不到env.XXX。正确做法启动 CLI 前设置OPENWEATHER_API_KEYxxx zcode run weather-forecast ...或用.env文件CLI 会自动加载或在zcode cli配置中设置zcode config set env.OPENWEATHER_API_KEY xxx经验zcode cli的config list命令能显示所有已加载的 env 变量比echo $XXX更可靠因为它显示的是 CLI runtime 真正看到的值。5.5 陷阱五忽略outputschema 的required导致下游消费失败outputschema 写了output: { type: object, properties: { result: { type: string } } }但index.js有时返回{ error: timeout }有时返回{ result: ok }。下游 Agent如codex cli的 Function Calling拿到{ error: timeout }因为result字段缺失触发 schema 校验失败整个 chain 中断。真相outputschema 的required字段是强制契约。如果result是必需的index.js就必须保证永远返回它哪怕值为null。更健壮的做法是output: { type: object, properties: { success: { type: boolean }, data: { type: [string, null] }, error: { type: [string, null] } }, required: [success] }然后index.js统一返回return { success: false, data: null, error: timeout }; // 或 return { success: true, data: ok, error: null };这五个陷阱覆盖了 90% 的skills开发失败场景。它们的共同特点是错误不在代码逻辑而在对协议的理解偏差。agent-skills的威力恰恰在于它用 schema 强约束把隐性约定显性化——不是靠文档而是靠机器可校验的 JSON Schema。6. 技能生态的真相marketplace 不是应用商店而是能力合约交易所热词里反复出现skills下载平台有哪些、skills推荐、claude 国内安装skills 官方市场、skills安装包下载很容易让人联想到手机 App Store。但agent-skills的 marketplace 本质完全不同。我研究过目前主流的几个 marketplacecodex marketplace、zcode hub、boos store发现它们的共性不托管代码你上传的只是一个.skill.jsonmanifestentrypoint指向 GitHub 仓库或 CDN URL不执行验证marketplace 只校验 manifest 格式是否合法JSON Schema不运行index.js不提供分发下载 skill 时CLI 会根据entrypoint自动git clone或curl下载代码marketplace 只是索引。这意味着marketplace 是“能力合约”的注册中心不是“应用”的分发中心。它卖的不是软件包而是标准化的接口描述。举个例子你在zcode hub上搜索github会看到github-pr-review.skill.json内容是{ name: github-pr-review, input: { type: object, properties: { pr_url: { type: string } } }, output: { type: object, properties: { summary: { type: string } } }, capabilities: [{ type: http, url: https://api.github.com/repos/... }], entrypoint: https://cdn.jsdelivr.net/npm/zcode/skills1.0.0/github-pr-review/index.js }你点击“安装”zcode cli做的事是下载这个.skill.json到本地skills/github-pr-review/从entrypointURL 下载index.js本地校验index.js是否符合 manifest 声明的输入/输出契约CLI 内置校验器注册到 runtime。整个过程marketplace 没碰过一行业务代码只提供了“谁提供了什么能力”的索引。所以skills开发的终极目标不是写一个功能而是写一份可被机器读取、可被 CLI 执行、可被 marketplace 索引的标准化能力契约。你提交的.skill.json就是你的“能力营业执照”entrypoint指向的代码就是你的“营业场所”。marketplace 不管你店里卖什么LLM 调用 or 数据库查询 or 硬件控制只管你执照上写的经营范围input/output/capabilities是否清晰、合法。这也是为什么nature skills、superpower skills、文字直播api这些看似不相关的词能共存于同一个 ecosystem——因为它们都遵守同一份契约。一个nature skills可以是调用植物识别 API一个superpower skills可以是调用语音合成 API只要 manifest 写得规范它们就能被同一个 CLI 加载、被同一个 Agent 调度、被同一个 marketplace 发现。最后分享一个真实案例我们团队有个pdd-order-query.skill.jsonmanifest 声明它需要pdd:order:readscope输入是order_id输出是订单状态。它实际调用的是拼多多 OpenAPI但对codex cli来说它就是一个普通 skill。当客户提出“能不能用这个 skill 查京东订单”我们没重写代码只改了 manifest 的capabilities.url和output字段映射然后重新发布——因为契约没变只是后端换了。这才是agent-skills协议带来的真正解耦能力抽象层与实现层的彻底分离。

agent-skills 是什么？不是 npm 包，而是能力交付协议

相关推荐

多微电网电能交互与碳排放优化的ADMM实现

E2V相机串口指令调参：曝光、触发与增益链路避坑

Context-Mode：一种让复杂系统上下文不再混乱的设计模式

更多资讯

Cloudflare Workers构建类操作系统Shell架构

Cloudflare Workers 本地开发避坑指南：pnpm、os error 5 与 Wrangler 稳定性实战

8086实模式下汇编循环程序设计与调试实战

DeepSeek V4国产大模型技术解析与应用实践

维奈克拉CYP3A相互作用分级与剂量调整实操指南

2026生成式AI技术全景：自主代理与工业落地实践

今日更新

微信个人号API开发案例：图片/语音/视频消息怎么下载解析存到本地？

Python股票自动交易系统源码解析：从行情获取到风控的完整链路

视酷酷信IM源码部署指南：Java 17+MySQL 8.0.33实战配置

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？