Agent-Skills：面向LLM的可发现、可调度能力中枢协议

1. 项目概述：Agent-Skills 不是插件，而是能力调度中枢

“Agent-Skills”这个词最近在开发者圈子里频繁刷屏，但很多人第一反应是——这又是个新出的 CLI 工具？还是某个大模型平台的官方技能市场？其实都不是。它本质上是一套面向 LLM Agent 的能力抽象与注册协议，核心目标只有一个：让大语言模型在执行复杂任务时，能像人类一样“知道该调用什么工具、何时调用、怎么传参、如何处理失败”。我从去年底开始在三个真实业务线中落地这套机制，从客服工单自动归因、到多源财报数据比对、再到内部知识库智能问答路由，全部基于同一套 Skills 注册规范实现。它不绑定任何特定框架（LangChain、LlamaIndex、DSPy 都能接入），也不依赖某家云厂商的 API 市场，而是用极简的 JSON Schema + 标准 HTTP 接口契约，把“能力”从代码里解耦出来，变成可发现、可组合、可灰度、可审计的独立单元。关键词里反复出现的 CLI、slash commands、API，恰恰印证了它的落地形态：前端开发者用zcode cli skills list查看当前可用能力；后端工程师用/skills/weather?city=北京直接触发服务；而 Agent 运行时则通过统一的find_skills("天气预报")接口动态匹配并调用。这不是炫技，而是解决 LLM 应用落地中最痛的三个问题：能力散落在各处难以复用、调用逻辑硬编码导致维护成本爆炸、错误处理缺乏统一兜底策略。如果你正在写一个需要调用数据库、发邮件、查天气、读 PDF 的 Agent，又不想每加一个功能就改一次主流程，那 Agent-Skills 就是你该立刻停下来认真看懂的底层基建。

2. 核心设计思路：为什么必须把“技能”从代码里拎出来？

2.1 传统做法的三大反模式，我们踩过全部坑

刚做 Agent 项目时，我和团队也走过典型弯路。第一种是“硬编码派”：所有能力直接写死在 Agent 的 prompt 里或 action 函数中。比如要查订单状态，就写个def get_order_status(order_id)，然后在 LLM 的 system prompt 里塞进一段说明：“你有以下能力：1. 查询订单状态，调用 get_order_status 函数……”。问题很快暴露：当订单系统升级接口、字段变更时，不仅要改函数，还要同步更新 prompt 里的描述，再重新微调模型——一次小改动牵动三处，上线周期从半天拉长到三天。第二种是“配置文件派”：把能力定义抽成 YAML，比如skills/order.yaml里写清楚 name、description、input_schema、endpoint。看似解耦，但实际运行时仍需手动加载、校验、拼接参数，LLM 返回的调用指令（如{"tool": "order", "args": {"id": "123"}}）还得靠一堆 if-else 去匹配路由。更麻烦的是，不同团队写的 YAML 格式五花八门，A 团队用input_schema，B 团队用parameters，C 团队干脆直接写字符串模板，导致整个平台的能力目录根本无法统一管理。第三种是“平台绑定派”：直接用 LangChain 的 Tool 或 LlamaIndex 的 ToolSpec，看似省事，结果一换框架就得重写全部能力封装，甚至有些能力（比如调用公司内网的 OA 系统）因为安全策略限制，根本没法按 LangChain 要求的签名方式暴露，最后只能打补丁绕过去。

提示：以上三种模式在中小项目里尚可应付，但一旦能力数超过 20 个、调用链路超过 3 层、参与团队超过 3 个，就会进入“混沌运维期”——没人敢轻易改能力，没人能说清某个技能到底被谁在什么场景下调用，故障排查全靠翻日志猜。

2.2 Agent-Skills 的破局逻辑：用 Web API 思维重构能力交付

我们最终选择回归最朴素的工程原则：把每个能力当成一个微型 Web 服务来设计和交付。不是让 LLM 去理解 Python 函数签名，而是让它学会调用标准 HTTP 接口。具体怎么做？核心就三点：

第一，能力即 API。每个 Skill 必须提供一个符合 OpenAPI 3.0 规范的openapi.json描述文件，里面明确定义：

• paths./v1/weather：这是该能力的唯一路径标识，也是 LLM 在生成调用指令时的 key；
• parameters：严格声明输入参数（如city: string, required），LLM 输出的 args 必须完全匹配此 schema，否则直接拒绝；
• responses.200.schema：明确返回结构，Agent 可据此做类型安全解析，避免response.data.temp这类易错访问；
• x-agent-skill-metadata：自定义扩展字段，存category: "utility"、cost_per_call: 0.02、timeout_ms: 5000等运营指标。

第二，发现即注册。不再靠人工维护 YAML 列表，而是让每个 Skill 服务启动时，向中央 Registry（一个轻量级 HTTP 服务）发起POST /register请求，带上自己的openapi.json和健康检查端点。Registry 自动校验 schema 合法性、去重、生成全局索引。前端 CLIzcode cli skills list --category utility实际就是调 Registry 的/skills?category=utility接口，拿到实时列表。

第三，调用即代理。Agent 运行时收到 LLM 的调用请求（如{"tool": "weather", "args": {"city": "上海"}}），不直接发 HTTP，而是统一走本地skills-proxy组件。这个 proxy 干三件事：

• 根据tool名查 Registry，找到对应服务地址；
• 用 JSON Schema 验证args合法性（自动过滤掉 LLM 胡编的{"city": null}）；
• 加入统一熔断、重试、超时、日志埋点，失败时返回标准化错误码（如SKILL_UNAVAILABLE），而非裸露的Connection refused。

这套设计让能力交付彻底脱离代码框架束缚。Python 写的天气服务、Go 写的数据库查询、甚至 Shell 脚本封装的curl命令，只要提供合规的 OpenAPI 描述，就能被任何 Agent 框架识别和调用。

2.3 为什么选 CLI 而非 GUI？命令行才是能力治理的黄金界面

看到热搜词里高频出现cli、zcode cli、codex cli，可能有人疑惑：现在都讲低代码，为啥还推命令行？因为 CLI 是能力生命周期管理最高效、最可编程、最易集成的界面。举几个真实场景：

• 开发阶段：工程师写完一个新 Skill（比如pdf-extract），执行zcode cli skills validate ./pdf-extract/openapi.json，工具会自动检查：是否所有 required 参数都有 description？是否 response schema 包含data字段（Agent 默认提取该字段）？是否x-agent-skill-metadata.cost_per_call为正数？——这些规则在 GUI 里很难做深度校验。

• 测试阶段：zcode cli skills test --skill weather --args '{"city":"北京"}'，工具自动构造请求、发起调用、比对返回是否符合 schema，并生成覆盖率报告（如 “input_schema 中 5 个字段，实际测试覆盖 4 个”）。我们曾用这个命令在上线前发现 7 个 Skills 的timeout_ms设置为 0，导致 Agent 卡死。

• 运维阶段：zcode cli skills status --health-check批量探测所有已注册 Skills 的健康状态，输出表格：
  | Skill | Status | Latency (ms) | Last Checked |
  |--------|--------|--------------|--------------|
  | weather | OK | 124 | 2024-06-15 14:22:03 |
  | order | TIMEOUT | — | 2024-06-15 14:21:58 |
  | pdf-extract | ERROR | — | 2024-06-15 14:22:01 |

注意：CLI 不是给终端用户用的，而是给 SRE、平台工程师、AI 工程师用的“能力操作系统”。它天然支持管道（zcode cli skills list --json | jq '.[] | select(.category=="data")'）、脚本化（for skill in $(zcode cli skills list --names); do zcode cli skills test --skill $skill; done）、CI/CD 集成（GitLab CI 中加入zcode cli skills validate步骤），这才是企业级能力治理的正确姿势。

3. 核心细节解析：Skills 的注册、发现与调用全链路拆解

3.1 注册环节：一个 Skills 服务启动时究竟发生了什么？

以一个真实的weather-svc为例，它用 Python FastAPI 实现，目录结构如下：

weather-svc/ ├── main.py # FastAPI 主程序 ├── openapi.json # OpenAPI 描述文件（关键！） ├── health.py # 健康检查端点 └── requirements.txt

openapi.json内容精简版如下（重点看x-agent-skill-metadata扩展）：

{ "openapi": "3.0.3", "info": { "title": "Weather Forecast", "version": "1.0.0" }, "paths": { "/v1/weather": { "post": { "summary": "Get current weather for a city", "operationId": "getWeather", "parameters": [ { "name": "city", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "temp": { "type": "number" }, "condition": { "type": "string" } } } } } } } } }, "x-agent-skill-metadata": { "category": "utility", "cost_per_call": 0.015, "timeout_ms": 3000, "reliability_score": 0.992 } } } } }

当main.py启动时，关键初始化代码如下：

from fastapi import FastAPI import httpx app = FastAPI() @app.on_event("startup") async def register_skill(): # 1. 读取本地 openapi.json with open("openapi.json") as f: spec = json.load(f) # 2. 构造注册 payload registry_url = "http://registry.internal:8080/register" payload = { "name": "weather", "spec": spec, "health_check_url": "http://localhost:8000/health", "service_url": "http://localhost:8000" } # 3. 发起注册请求（带重试） async with httpx.AsyncClient() as client: for i in range(3): try: resp = await client.post(registry_url, json=payload, timeout=5.0) if resp.status_code == 201: print("✅ Skill registered successfully") return except Exception as e: print(f"⚠️ Register attempt {i+1} failed: {e}") await asyncio.sleep(1) raise RuntimeError("Failed to register skill after 3 attempts")

这里有几个必须注意的细节：

• 注册时机：必须在服务完全就绪（HTTP server started）之后才注册，否则 Registry 会探测失败。FastAPI 的on_event("startup")是最佳钩子。
• 健康检查端点：/health必须返回{"status": "ok"}，且响应时间 < 200ms，Registry 每 30 秒轮询一次，连续 3 次失败即标记为UNHEALTHY。
• Service URL 的协议：必须是http://或https://，不能是localhost（容器内 DNS 解析问题），我们约定统一用服务名（如weather-svc.default.svc.cluster.local）。
• Spec 的完整性：Registry 会严格校验openapi.json是否包含x-agent-skill-metadata，且cost_per_call必须是数字，timeout_ms必须在 100~30000 范围内，否则注册直接拒绝。

3.2 发现阶段：Agent 如何在千个 Skills 中精准定位“天气预报”？

LLM 的输出往往是模糊的，比如用户问“今天北京天气怎么样”，LLM 可能生成{"tool": "get_weather", "args": {"location": "Beijing"}}，而 Registry 里注册的 Skill 名是weather，参数名是city。这就需要一套健壮的发现机制，而不是简单字符串匹配。

我们的find_skills服务采用三级匹配策略：

第一级：语义标签匹配（占权重 50%）
每个 Skill 在注册时，除了openapi.json，还会被自动分析生成一组语义标签：

• 从info.title提取关键词（如 “Weather Forecast” →["weather", "forecast"]）；
• 从paths./v1/weather.post.summary提取动词+名词（如 “Get current weather” →["get", "current", "weather"]）；
• 从x-agent-skill-metadata.category映射预设标签（如"utility"→["utility", "tool", "helper"]）。
  当查询 “今天北京天气怎么样”，系统分词得到["today", "beijing", "weather", "how"]，计算与各 Skill 标签的 Jaccard 相似度，weather的相似度最高。

第二级：参数兼容性匹配（占权重 30%）
即使语义匹配度高，如果参数不兼容，也不能调用。系统会检查：

• LLM 提供的args中，是否有至少一个 key 与 Skill 的parameters中的name完全一致（如cityvslocation）；
• 或者，args的 key 是否在 Skill 的parameters的description中被提及（如description: "城市名称，支持中文或英文"包含 “城市”、“中文”）；
• 如果都不满足，则降权处理。

第三级：历史调用频次加权（占权重 20%）
对同一类查询（如 “天气”），统计过去 24 小时内各 Skill 的成功调用次数，高频 Skill 优先展示。这解决了冷启动问题——新上线的weather-v2可能语义匹配度更高，但老weather-v1因稳定可靠，仍保持首位。

最终返回结果是一个有序列表：

[ { "name": "weather", "score": 0.92, "reason": "semantic_match=0.85, param_compatible=0.95, history_freq=0.98", "spec": { ... } // 精简后的 openapi.json 片段 }, { "name": "weather-ai", "score": 0.76, "reason": "semantic_match=0.90, param_compatible=0.65, history_freq=0.82" } ]

Agent 运行时默认取第一个，但也可配置策略（如fallback_to_best_match_on_failure）。

3.3 调用环节：Skills Proxy 如何成为 Agent 的“能力交通警察”

Skills Proxy 是整个链路的中枢，它不是一个简单的反向代理，而是一个具备策略引擎的智能网关。其核心职责有四：

职责一：Schema 强验证
LLM 生成的args绝大多数时候是“看起来像 JSON”的字符串，比如{"city": "北京", "unit": "celsius"}。Proxy 会：

• 先用json.loads()解析；
• 再用jsonschema.validate()对照 Skill 的parametersschema 校验；
• 若失败，立即返回标准化错误：{"error": "INVALID_ARGUMENTS", "detail": "Parameter 'unit' is not allowed. Allowed: ['city']"}，并记录告警。
  我们实测发现，约 18% 的 LLM 调用请求因参数错误被拦截，避免了下游服务无谓的负载。

职责二：智能重试与熔断
Proxy 内置 Circuit Breaker，状态机如下：

• CLOSED：正常转发；
• OPEN：连续 3 次调用超时或返回5xx，进入 OPEN 状态，后续请求直接返回SKILL_UNAVAILABLE；
• HALF_OPEN：OPEN 状态持续 60 秒后，放行 1 个请求试探，成功则恢复 CLOSED，失败则重置计时器。
  重试策略为指数退避：第一次失败后等 100ms，第二次等 200ms，第三次等 400ms，最多重试 2 次（超时时间本身已设为timeout_ms * 1.5）。

职责三：统一上下文注入
很多 Skill 需要用户身份、租户 ID、请求 trace_id。Proxy 会在转发前，自动将这些信息注入请求头：

• X-User-ID: u_abc123（从 Agent 的 session context 提取）；
• X-Tenant-ID: t_xyz789（多租户场景）；
• X-Trace-ID: trace-456（全链路追踪）。
  这样 Skill 服务无需自己解析 JWT 或查数据库，专注业务逻辑。

职责四：调用计量与限流
Proxy 记录每次调用的skill_name、duration_ms、status_code、cost_per_call（从 Registry 获取），写入 Prometheus。同时支持按 Skill 限流：

• weather：每秒最多 100 次（防爬虫）；
• database-query：每分钟最多 300 次（保护 DB）；
• send-email：每小时最多 50 次（防滥发）。
  限流规则通过 Consul KV 动态配置，无需重启 Proxy。

4. 实操过程：从零搭建一个可运行的 Agent-Skills 环境

4.1 环境准备：三台机器，十分钟搞定最小可行集群

我们不推荐在单机上模拟，因为 Skills 本质是分布式服务。以下是生产环境最小配置（也是我们测试环境的真实拓扑）：

步骤 1：部署 Registry

# 拉取镜像并运行（使用 SQLite 存储，适合小规模） docker run -d \ --name skills-registry \ -p 8080:8080 \ -v $(pwd)/registry-data:/app/data \ -e REGISTRY_STORAGE=sqlite \ -e REGISTRY_STORAGE_SQLITE_PATH=/app/data/registry.db \ agent-skills/registry:latest

验证：curl http://registry.internal:8080/health返回{"status":"ok"}。

步骤 2：部署 Proxy

# 注意：必须配置 Registry 地址 docker run -d \ --name skills-proxy \ -p 8000:8000 \ -e PROXY_REGISTRY_URL=http://registry.internal:8080 \ -e PROXY_LISTEN_PORT=8000 \ agent-skills/proxy:latest

验证：curl http://proxy.internal:8000/v1/skills/list返回空数组[]（初始无 Skills）。

步骤 3：启动 Weather Skill

# 克隆示例代码 git clone https://github.com/agent-skills/demo-weather.git cd demo-weather # 修改 main.py 中的 registry_url 为 http://registry.internal:8080 # 构建并运行 docker build -t weather-svc . docker run -d \ --name weather-svc \ -p 8000:8000 \ --network host \ # 关键：使用 host 网络，便于 Registry 探测 weather-svc

等待 10 秒，检查 Registry：curl http://registry.internal:8080/v1/skills/weather应返回完整 spec。

步骤 4：CLI 初始化
下载zcode-cli（Linux x64）：

curl -L https://github.com/zcode/cli/releases/download/v1.2.0/zcode-cli-linux-x64 -o /usr/local/bin/zcode chmod +x /usr/local/bin/zcode zcode config set registry-url http://registry.internal:8080 zcode config set proxy-url http://proxy.internal:8000

现在可以执行：

• zcode skills list→ 显示weather；
• zcode skills test --skill weather --args '{"city":"上海"}'→ 返回天气数据；
• zcode skills status→ 显示OK。

4.2 开发一个新 Skill：以“PDF 文本提取”为例

假设我们要接入一个开源 PDF 提取服务pdfplumber，目标是让 Agent 能说“请提取这份合同的关键条款”，然后调用该 Skill。

第一步：定义 OpenAPI
创建pdf-extract/openapi.json：

{ "openapi": "3.0.3", "info": { "title": "PDF Text Extractor", "version": "1.0.0" }, "paths": { "/v1/pdf/extract": { "post": { "summary": "Extract text from PDF file", "operationId": "extractPdfText", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string" }, "page_count": { "type": "integer" } } } } } } } } }, "x-agent-skill-metadata": { "category": "document", "cost_per_call": 0.08, "timeout_ms": 10000, "reliability_score": 0.95 } } } } }

第二步：实现 FastAPI 服务
main.py关键代码：

from fastapi import FastAPI, File, UploadFile from fastapi.responses import JSONResponse import pdfplumber app = FastAPI() @app.post("/v1/pdf/extract") async def extract_pdf(file: UploadFile = File(...)): try: # 读取文件内容 content = await file.read() # 使用 pdfplumber 提取文本 with pdfplumber.open(io.BytesIO(content)) as pdf: full_text = "" for page in pdf.pages: full_text += page.extract_text() or "" return { "data": { "text": full_text[:10000], # 截断防 OOM "page_count": len(pdf.pages) } } except Exception as e: return JSONResponse( status_code=500, content={"error": "EXTRACT_FAILED", "detail": str(e)} )

第三步：注册与测试
构建 Docker 镜像，运行后执行：

zcode skills list --category document # 输出：pdf-extract zcode skills test --skill pdf-extract --file ./test.pdf # 返回提取的文本片段

第四步：在 Agent 中调用
假设你的 Agent 用 LangChain，只需写一个自定义 Tool：

from langchain.tools import BaseTool from pydantic import BaseModel, Field class PdfExtractInput(BaseModel): file_path: str = Field(..., description="Local path to the PDF file") class PdfExtractTool(BaseTool): name = "pdf-extract" description = "Extract text from a PDF file. Input is a local file path." args_schema = PdfExtractInput def _run(self, file_path: str) -> str: # 读取文件，调用 proxy 的 /v1/skills/pdf-extract with open(file_path, "rb") as f: files = {"file": f} resp = requests.post( "http://proxy.internal:8000/v1/skills/pdf-extract", files=files ) return resp.json()["data"]["text"][:500] + "..."

LLM 生成{"tool": "pdf-extract", "args": {"file_path": "/tmp/contract.pdf"}}，Agent 就能自动执行。

4.3 生产级增强：监控、告警与灰度发布

光能跑通远远不够。我们在生产环境加了三层保障：

监控层：Proxy 暴露/metrics端点，采集指标：

• skills_call_total{skill="weather",status="success"}
• skills_call_duration_seconds_bucket{skill="weather",le="0.1"}
• skills_registry_health{status="unhealthy"}
  用 Grafana 做看板，关键面板包括：
• “Top 5 Skills by Error Rate”（错误率 > 5% 标红）；
• “Avg Latency by Category”（utility 类平均 < 200ms，data 类 < 2000ms）；
• “Registry Sync Lag”（注册延迟 > 5s 触发告警）。

告警层：用 Prometheus Alertmanager 配置：

- alert: SkillUnhealthy expr: sum by (skill) (skills_registry_health{status="unhealthy"}) > 0 for: 2m labels: severity: critical annotations: summary: "Skill {{ $labels.skill }} is unhealthy" description: "Registry has detected {{ $value }} unhealthy instances" - alert: HighErrorRate expr: rate(skills_call_total{status="error"}[5m]) / rate(skills_call_total[5m]) > 0.1 for: 1m labels: severity: warning

灰度发布层：Registry 支持版本标签。注册时可加version: "v2"，CLI 查询时指定--version v2。Agent 调用时，可配置策略：

• canary: 5%：5% 的流量打到v2，其余打v1；
• header-based: X-Skill-Version: v2：特定请求头强制走新版；
• failover: v1 -> v2：v1 失败后自动重试 v2。
  我们曾用此策略上线weather-v2（接入新气象 API），零故障切换。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 问题速查表：高频故障与一键修复

5.2 独家避坑技巧：来自 12 个项目的血泪经验

技巧一：OpenAPI 的description是 LLM 的“提示词富矿”
别小看parameters[].description字段。我们发现，LLM 对description: "城市名称，支持中文（如'北京'）或英文（如'Beijing'）"的理解，远好于description: "城市"。更进一步，我们在description里埋入示例："示例值: '上海', 'Shanghai'"，LLM 生成args的准确率提升 37%。所以，写 description 时，务必包含：

• 数据类型约束（“必须为字符串，长度 2-10”）；
• 取值范围（“仅支持 ['北京','上海','广州','深圳']”）；
• 示例值（“示例: '杭州'”）；
• 常见错误（“注意：不要传入经纬度坐标”）。

技巧二：用x-agent-skill-metadata.reliability_score做智能降级
reliability_score不是摆设。我们在 Agent 的find_skills逻辑里加了一条规则：如果候选 Skill 的reliability_score < 0.9，且存在reliability_score > 0.95的同类别 Skill，则自动降权前者。例如，weather-v1评分为 0.98，weather-v2评分为 0.85（新上线不稳定），那么即使语义匹配度v2更高，也会优先选v1。这个分数由 Registry 根据过去 24 小时的成功率、超时率、错误率动态计算，每天凌晨自动更新。

技巧三：CLI 的--dry-run是调试 LLM 的神器
zcode skills test --skill weather --args '{"city":"北京"}' --dry-run不真正调用服务，而是模拟整个链路：

• 解析args；
• 校验 schema；
• 计算调用成本；
• 输出将要发送的 HTTP 请求详情（URL、Headers、Body）。
  这让我们能在不扰动生产服务的情况下，反复调试 LLM 的 prompt——比如发现 LLM 总是生成{"city": null}，就立刻在 prompt 里加一句：“参数 city 绝对不可为空，必须提供有效城市名”。

技巧四：Registry 的search接口支持布尔运算，别只会list
zcode skills search --query "weather AND (free OR utility)"背后是 Registry 的全文检索。它支持：

• AND/OR/NOT；
• category:utility（字段过滤）；
• cost_per_call<0.05（数值比较）；
• "北京天气"（短语匹配）。
  我们在 Agent 的find_skills里，会根据用户 query 的复杂度自动构造搜索条件：简单问句用AND，复杂需求用OR，带否定词（“不要”、“排除”）用NOT。

技巧五：Proxy 的X-Skill-Debug: true头开启全链路日志
在调试棘手问题时，在请求头加X-Skill-Debug: true，Proxy 会返回额外字段：

{ "data": { ... }, "debug": { "registry_lookup_time_ms": 12.3, "schema_validation_time_ms": 0.8, "upstream_request_id": "req-789", "upstream_response_time_ms": 245.6 } }

配合日志系统（如 Loki），能快速定位是 Registry 慢、Schema 校验慢，还是上游服务慢。

6. 能力生态的延伸思考：从 Skills 到 Agent OS

Agent