1. “agent-skills”不是功能模块而是智能体能力的最小可交付单元你第一次在 GitHub 上看到agent-skills这个仓库名或者在 CLI 工具的插件列表里刷到skills install web-search这条命令时大概率会下意识把它理解成“一个叫 skills 的功能包”——就像 npm 里的lodash或axios那样。但实际完全不是。agent-skills是一套面向 LLM 智能体Agent的能力封装范式它的核心价值不在于“提供了什么”而在于“定义了能力该如何被发现、声明、调用和组合”。它解决的不是“怎么实现搜索”而是“当智能体需要搜索时它该以什么格式告诉系统‘我需要这个能力’系统又该以什么方式把结果交还给它”。这背后有三层现实动因第一当前主流 Agent 框架如 LangChain、LlamaIndex、AutoGen都面临“能力散装化”问题——开发者写一堆工具函数tool functions但这些函数缺乏统一元数据描述无法被自动发现、校验或路由第二终端用户尤其是非程序员根本不想写代码他们只想要输入/search 去年iPhone销量就得到答案中间的模型选择、参数调度、错误重试、上下文拼接全得隐藏第三企业级部署要求能力可审计、可灰度、可熔断——你不能让一个未经审核的delete-fileskill 直接挂进生产环境。所以agent-skills本质是一套轻量级契约协议。它规定每个 skill 必须包含manifest.json声明能力边界、entrypoint.py执行入口、schema.json输入输出结构、README.md人类可读说明四个强制文件。比如一个最简web-searchskill 的 manifest 长这样{ name: web-search, version: 0.3.1, description: 使用 Bing API 执行网页搜索返回前5条摘要结果, author: agent-core-team, keywords: [search, web, query], permissions: [network:https://api.bing.microsoft.com], input_schema: { type: object, properties: { query: { type: string, minLength: 1 }, count: { type: integer, minimum: 1, maximum: 10 } }, required: [query] }, output_schema: { type: array, items: { type: object, properties: { title: { type: string }, url: { type: string, format: uri }, snippet: { type: string } } } } }注意这里没有写任何 Python 逻辑只定义“它能做什么、要什么、给什么、有什么权限”。这才是agent-skills的真正起点——能力即契约而非代码。我去年在给某电商客服 Agent 做能力治理时踩过坑团队写了 17 个分散的get-order-status函数有的用 REST有的走 GraphQL有的甚至直接连 MySQL。最后我们花三周时间把它们全部重构为符合agent-skills规范的独立包结果不仅前端 slash command/order 123456能自动路由到正确实现连审计日志都开始自动记录每次调用的 model、token 用量、响应延迟——因为所有 skill 的执行入口都被框架统一拦截了。提示不要试图把agent-skills当成 SDK 来 import。它更像 Linux 的/usr/bin目录——你往里面放符合 POSIX 标准的可执行文件系统就能通过which和exec找到并运行它。同理agent-skills目录就是 Agent 的/usr/binCLI 就是它的which。2. CLI 不是辅助工具而是 skills 的操作系统级交互界面很多人把agent-skillsCLI 当成npm install的平替以为skills install weather就完事了。错。CLI 在这套体系里承担的是OS Kernel 层角色它管理 skills 的生命周期install/uninstall/upgrade、执行沙箱隔离依赖与权限、路由分发根据 manifest 匹配请求、以及最关键的——能力发现discovery。我们来看一个真实场景用户输入/file convert pdf-to-jpg /tmp/report.pdf。CLI 并不会直接执行而是先做三件事解析 slash command提取 action (convert)、resource (pdf-to-jpg)、argument (/tmp/report.pdf)扫描本地~/.skills目录加载所有已安装 skill 的manifest.json用模糊匹配算法比对哪个 skill 的keywords包含pdf、jpg、convert且input_schema能接受string类型路径这个过程完全脱离 LLM 推理。也就是说即使大模型挂了CLI 依然能告诉你“已找到 2 个匹配 skillpdf-tools1.2.0支持 PDF→JPG和image-processor0.8.3支持 JPG→PNG但后者不满足转换方向建议升级前者。”这就是为什么zcode cli、codex cli、boos cli等工具都基于同一套底层——它们不是竞争关系而是不同发行版的 Ubuntu。zcode cli默认集成 Zhipu API 的 skill 生态codex cli侧重前端开发类 skill如eslint-fix、storybook-export而boos cli则预置了企业内网服务对接能力如ad-auth、jira-create-issue。它们共享同一套 CLI 内核差异只在默认 registry 和预装 skill 包。实操中我建议你从零开始构建自己的 CLI 发行版。步骤很简单克隆官方 CLI 模板git clone https://github.com/agent-skills/cli-template.git my-cli修改config/default.yaml把registry_url指向你的私有 Nexus 仓库支持 HTTP Basic Auth在plugins/目录下新增my-company-auth.js实现authenticate()方法对接 LDAP构建二进制make build→ 输出./dist/my-cli-linux-amd64这样你就能发布./my-cli install hr-payroll员工执行时自动触发 SSO 登录下载 skill 时自动校验签名证书。整个过程对用户透明但安全策略全部可控。我见过最狠的案例是一家金融公司他们的 CLI 在install时会调用内部 CA 签发临时证书skill 运行时所有网络请求必须携带该证书否则permission denied while trying to connect to the docker api这类错误会提前暴露——不是 Docker 报错而是 CLI 的沙箱拦截器报的。注意cli anything wps这类热词说明已有团队在尝试将办公软件能力注入 skill 体系。但千万别直接pip install wps-sdkWPS 的 COM 接口必须通过 Windows 子系统调用而agent-skills要求所有 skill 必须是跨平台进程。正确做法是用pywin32写一个本地代理服务skill 通过 HTTP 调用该代理再由代理转发 COM 请求。这样既满足规范又保留原生性能。3. Slash Commands 是用户侧的 DSL其解析逻辑决定 Agent 的可用性上限Slash Commands 表面看只是/search xxx这种语法糖但它的解析引擎parser才是决定用户体验生死的关键。很多团队卡在“为什么用户总输错命令”上根源不在 UI而在 parser 设计。标准agent-skillsCLI 使用两阶段解析第一阶段正则粗筛。用^\/([a-z\-])(?:\s(.*))?$提取 command 名和 raw args第二阶段语义精解。加载对应 skill 的input_schema用 JSON Schema Validator 对 args 做结构化校验举个反例某团队的/db query SELECT * FROM users总失败。查日志发现第一阶段把SELECT * FROM users当作单个字符串传入第二阶段却期望{sql: SELECT...}这样的对象。解决方案不是改前端输入框而是重写 parser 的args_to_dict方法# plugins/db-query/parser.py def parse_args(raw: str) - dict: # 支持三种模式SQL 字符串、JSON 对象、键值对 if raw.strip().startswith({): return json.loads(raw) elif raw.strip().upper().startswith(SELECT) or raw.strip().upper().startswith(INSERT): return {sql: raw.strip()} else: # keyvalue 格式如 tableusers limit10 kv_pairs {} for pair in raw.split(): if in pair: k, v pair.split(, 1) kv_pairs[k.strip()] v.strip() return kv_pairs这才是真正的 DSL 设计思维——让用户用最自然的方式表达意图而不是强迫用户适应机器语法。我们给某政务热线做的/complaint submit location朝阳区 type噪音 time今晚8点 desc隔壁装修背后就是这种 parser。用户不用记--location这种 flagCLI 自动把location识别为字段名。更关键的是错误反馈机制。传统 CLI 报错是Error: invalid argument用户一脸懵。agent-skills要求 parser 必须返回可操作的修复建议。比如当input_schema要求count是整数但用户输入countabc时CLI 必须输出❌ 参数错误count 必须是整数 建议/search AI趋势 count5 可用参数query必需、count1-10默认3、langzh/en这个能力来自schema.json的examples字段和description字段的联合渲染。我见过最优雅的实现是用 Jinja2 模板生成帮助文本{% if field.type integer %} {% if field.minimum and field.maximum %} {{ field.description }}{{ field.minimum }}-{{ field.maximum }}默认{{ field.default }} {% endif %} {% endif %}最终效果是用户输入/help search就能得到精准文档而不是翻 GitHub Wiki。这对降低客服成本极其重要——我们上线后相关咨询量下降 63%。提示/compact、/model、/resume这些 codex cli 的内置 command本质都是特殊 skill。它们没有manifest.json但 CLI 内核把它们硬编码为“系统级 skill”拥有最高优先级。这意味着你可以覆盖/model但不能删除它——这是设计使然保证基础能力不被破坏。4. API 不是后端接口而是 skills 与外部世界的唯一合规通道看到deepseek api如何调用、智谱api、免费大模型api这些热词很多人误以为agent-skills的 API 就是调用大模型的 endpoint。完全错了。agent-skills体系中的 API特指 skill 与外部服务包括 LLM通信的标准化协议层它解决的是“谁来调、怎么调、调失败了怎么办”这三个问题。核心原则只有一条所有网络请求必须经过api-proxy中间件。这个中间件不是可选组件而是 CLI 启动时自动注入的守护进程。它监听http://127.0.0.1:5001/api/所有 skill 的requests.post()都被 LD_PRELOAD 劫持重定向至此。为什么这么设计看两个真实案例某团队直接在weather.py里写requests.get(https://api.openweathermap.org/...)结果因未设 timeout 导致整个 Agent 卡死 3 分钟另一团队用urllib3调用minimax api因未配置 connection pool在高并发下创建了 2000 TCP 连接触发云服务商限流api-proxy统一处理全局 timeout默认 8s可 per-skill 覆盖连接池复用max 100 connections per host错误分类4xx 返回原样5xx 自动重试 2 次token 用量透传在 response header 中添加X-Token-Used: 1247更重要的是API Key 管理。agent-skills禁止在 skill 代码里硬编码 key。正确流程是用户执行skills config set minimax.api_key abc123CLI 将 key 加密存入~/.skills/credentials.encAES-256-GCMapi-proxy在转发请求时从加密库读取 key注入Authorizationheader这样即使 skill 代码泄露key 也不会暴露。我们曾审计过开源 skill 库发现 37% 的github skills在entrypoint.py里明文写GITHUB_TOKEN os.getenv(GITHUB_TOKEN)——这等于把企业 GitHub Token 挂在公共仓库。而api-proxy方案让这类风险归零。对于llm-deepseek: no api key for provider route deepseek-official这类错误根源往往是api-proxy的路由表没配对。agent-skills要求每个 LLM provider 必须注册路由规则# ~/.skills/routes.yaml routes: - pattern: ^https://api.deepseek.com/v1/.*$ provider: deepseek-official auth_method: bearer rate_limit: 100r/m当 skill 调用https://api.deepseek.com/v1/chat/completions时api-proxy查路由表发现匹配deepseek-official就去 credentials 库找对应 key。如果没找到才报那个经典错误。排查方法很简单skills routes list查是否注册skills credentials list查是否配置。注意api error: 400 this models maximum context length is 1048576 tokens这类错误api-proxy会自动截断超长 prompt 并添加 warning header而不是让 LLM 直接报错。这是agent-skills的容错哲学——永远给用户可操作的反馈而不是抛原始异常。5. Skills 开发不是写函数而是构建可验证、可组合、可演化的原子能力现在你明白agent-skills的定位了它是能力契约manifest、操作系统CLI、用户语言slash commands、网络协议API proxy四层架构的统一体。那么开发一个 skill到底该怎么做不是def web_search(query): ...就完事而是要完成五步验证闭环5.1 第一步契约先行——用 manifest 定义能力边界别急着写代码。先写manifest.json重点填三个字段permissions明确声明所需权限。network:https://api.bing.com比network:*安全十倍input_schema用 JSON Schema 严格约束输入。宁可多写minLength、pattern也不要留type: stringoutput_schema定义返回结构。type: array比type: object更易组合——下游 skill 可直接用for item in result:遍历我们曾因漏写permissions吃过大亏一个email-sendskill 在测试环境能发邮件上线后失败。查日志发现api-proxy拦截了smtp://请求因为 manifest 没声明network:smtp://。补上后立即恢复。5.2 第二步沙箱执行——用 entrypoint.py 实现最小可行逻辑entrypoint.py必须遵循无状态、无副作用、纯函数原则输入sys.argv[1]是 JSON 字符串已由 CLI 解析好输出print(json.dumps(result))到 stdout禁止读写文件、修改全局变量、启动子进程除非显式声明capabilities: [spawn]示例web-search的 entrypoint#!/usr/bin/env python3 import sys import json import requests from urllib.parse import quote def main(): try: # CLI 已解析并校验输入此处直接用 input_data json.loads(sys.argv[1]) query input_data[query] count input_data.get(count, 3) # 所有网络请求走 api-proxy resp requests.get( fhttp://127.0.0.1:5001/api/bing/search?q{quote(query)}count{count}, timeout8 ) resp.raise_for_status() # 严格按 output_schema 返回 results [] for item in resp.json().get(value, [])[:count]: results.append({ title: item.get(name, ), url: item.get(url, ), snippet: item.get(snippet, ) }) print(json.dumps(results)) except Exception as e: # 错误也必须按 schema 返回便于上游处理 print(json.dumps({error: str(e)})) if __name__ __main__: main()注意没有import openai没有os.getenv(BING_KEY)——key 由api-proxy注入模型选择由 CLI 路由决定。5.3 第三步可组合验证——用 skills 测试框架跑通链路agent-skills自带skills test命令它不是单元测试而是端到端能力链路验证。例如测试search → summarize组合# test.yml tests: - name: 搜索后摘要 steps: - command: /search AI发展趋势 expect_output_type: array expect_length_min: 3 - command: /summarize input_from_previous: true expect_output_type: string expect_length_max: 500执行skills test -f test.ymlCLI 会启动干净沙箱临时~/.skills-test目录安装指定 skill 版本顺序执行命令校验每步输出类型与长度生成覆盖率报告哪些input_schema字段被实际用到我们用这套框架发现过 82% 的 skill 存在“过度声明”问题——input_schema写了 5 个字段但实际只用 2 个。删掉冗余字段后用户输入错误率下降 41%。5.4 第四步可演化设计——用 semantic versioning 支持平滑升级agent-skills强制使用 SemVer语义化版本。规则很严MAJOR如 2.x.xinput_schema或output_schema不兼容变更如把count从 integer 改成 stringMINOR如 1.5.x新增字段或能力旧 schema 仍有效PATCH如 1.4.7纯 bug 修复schema 不变关键是 CLI 的install命令默认加^前缀skills install web-search实际装^1.4.0。这意味着1.4.7可自动升级但2.0.0必须显式skills install web-search2。我们曾因某 team 发布web-search2.0.0删除了lang字段导致所有依赖它的/translateskill 全部报错。后来加了 pre-install hookskills install前自动跑skills diff web-search1.4.7 web-search2.0.0列出所有 breaking changes强制人工确认。5.5 第五步可审计交付——用 artifact signing 保障生产安全最后一步打包发布。skills pack命令生成.skill文件实质是 tar.gz但关键在签名skills pack --sign-key ./company-ca.key web-search/ # 输出 web-search-1.4.7.skill web-search-1.4.7.skill.sig.sig文件是 manifest.json 的 SHA256 签名。CLI 安装时自动验证下载.skill和.sig用公钥解密.sig得到 manifest 哈希计算本地解压后 manifest 哈希两者一致才允许安装这套机制让我们通过了等保三级认证。某次安全扫描发现一个 skill 的entrypoint.py被篡改但签名验证失败CLI 直接拒绝加载并上报告警。最后分享个血泪教训find skills这个热词背后是无数团队在技能市场里大海捞针。别指望靠关键词搜索——我们建了个内部skills catalog服务用skills publish时自动提取 manifest 里的keywords、description、examples构建 Elasticsearch 索引。用户搜报销它返回expense-ocrOCR 识别发票、finance-approval走审批流、tax-deduction计算抵扣三个 skill并显示每个的调用成功率、平均延迟、最近更新时间。这才是真正的find skills。