agent-skills：可插拔AI能力交付协议详解-育师

1. “agent-skills”不是功能模块，而是一套可插拔的能力交付协议

“agent-skills”这个词最近在开发者社区里高频出现，但很多人一搜就懵——它既不是某个具体开源库的官方命名，也不是某家大厂发布的标准产品，更不是 npm 上能直接npm install agent-skills就跑起来的包。我最早在调试一个 CLI 工具链时撞见它：执行codex skills list后输出的 JSON 结构里，每个条目都带"type": "agent-skills"字段；后来在阅读 Reasonix 的插件注册文档时，又看到registerSkill({ id: 'web-search', type: 'agent-skills', ... })这样的调用。再往后，翻 GitHub 上几个活跃的 LLM 工具链项目（比如 trae、boos、zcode），它们的skills/目录下统一存放.skill.yaml文件，文件顶部赫然写着kind: agent-skills。

这说明什么？说明“agent-skills”本质上是一种约定大于配置的接口契约——它定义了“一个能力（skill）该如何被 Agent 发现、加载、校验和执行”。它不绑定语言（Python/JS/Go 都能实现）、不绑定运行时（本地进程、Docker 容器、HTTP 微服务均可）、不绑定模型提供商（DeepSeek、Qwen、Claude、Kimi 甚至本地 Ollama 模型都能调用）。它的核心价值，是让“能力”从 Agent 主体中解耦出来，变成可独立开发、测试、版本管理、灰度发布的单元。就像前端工程里的 Web Component，或后端服务里的 OpenAPI Spec，它解决的是“能力复用”和“能力治理”的底层问题。

你可能会问：那它和普通 CLI 命令、普通 API 接口有什么区别？区别在于上下文感知能力与执行契约。一个curl https://api.example.com/search?q=xxx是纯 HTTP 调用，Agent 必须自己拼 URL、处理鉴权头、解析 JSON、容错重试；而一个agent-skills格式的 search skill，会自带input_schema（声明需要哪些参数、类型、是否必填）、output_schema（声明返回结构）、execution_mode（是同步阻塞还是异步回调）、required_permissions（需声明访问网络、读取文件等权限）、甚至fallback_strategy（当主服务不可用时降级到本地关键词匹配）。Agent 运行时拿到这个 skill 描述后，能自动生成调用逻辑、自动注入 token、自动做输入校验、自动处理超时，开发者只需专注写业务逻辑本身。

所以，“agent-skills”不是技术栈，而是协作范式。它背后站着的是整个 Agent 生态的工业化演进：当越来越多团队开始构建自己的 Agent 时，重复造轮子（搜索、天气、数据库查询、代码生成）成了最大瓶颈。有人写了个好用的 PDF 解析 skill，却没法被隔壁组的 Reasonix Agent 直接复用；有人封装了高精度的股票数据 API，但因鉴权方式不同，被集成进 trae CLI 时要重写三遍。agent-skills 协议就是为终结这种碎片化而生——它用一份 YAML + 一个标准执行入口（通常是./run.sh或main.py），把能力变成“即插即用”的黑盒。你不需要知道它内部用的是 Requests 还是 httpx，用的是 SQLite 还是 PostgreSQL，只要它符合协议，Agent 就能安全、可靠、一致地调用它。

提示：不要试图在 npm 或 PyPI 上搜索agent-skills。它不是一个包名，而是一个语义标签。你在 GitHub 搜索"kind: agent-skills"或"type: agent-skills"，能找到真实项目中落地的 skill 定义文件；搜索"agent-skills spec"则会跳转到 OpenSkills Initiative 的非正式草案文档——那是目前最接近事实标准的参考实现。

2. 解剖一个真实可用的 agent-skills：从 YAML 定义到 CLI 执行闭环

光说概念太虚，我们直接拆一个已在生产环境跑了一年的真实 skill：github-pr-reviewer.skill.yaml。它被集成在某 SaaS 公司的内部 codex CLI 中，用于自动扫描 PR 更改并生成代码评审建议。这个文件不到 80 行，却完整体现了 agent-skills 协议的核心设计思想。我们逐段解读：

# github-pr-reviewer.skill.yaml kind: agent-skills version: 1.2 id: github-pr-reviewer name: GitHub Pull Request Reviewer description: Analyze code diffs in a PR and generate actionable review comments with line references. author: devops-team@company.com license: MIT # 输入契约：Agent 调用时必须提供的参数 input_schema: type: object required: [repo_owner, repo_name, pr_number, diff_content] properties: repo_owner: type: string description: GitHub organization or username repo_name: type: string description: Repository name pr_number: type: integer description: Pull request number diff_content: type: string description: Full git diff output (max 500KB) maxLength: 512000 # 输出契约：skill 承诺返回的结构 output_schema: type: object required: [review_comments, summary] properties: review_comments: type: array items: type: object required: [file_path, line_number, comment] properties: file_path: { type: string } line_number: { type: integer } comment: { type: string } summary: type: string description: High-level assessment of PR quality # 执行契约：如何运行这个能力 execution: mode: sync timeout_seconds: 120 entrypoint: ./run.sh environment: GITHUB_TOKEN: secret MODEL_PROVIDER: deepseek-official MODEL_NAME: deepseek-coder-33b-instruct # 权限声明：运行此 skill 需要哪些系统能力 permissions: - network: true - filesystem: read - secrets: [GITHUB_TOKEN] # 元数据：用于发现与治理 tags: [github, code-review, static-analysis] categories: [devops, engineering]

这个 YAML 文件就是 skill 的“身份证”和“说明书”。Agent 运行时（比如 codex CLI）加载它时，首先校验kind和version是否兼容；然后根据input_schema生成表单或校验传入参数——如果用户漏传pr_number，CLI 会直接报错ValidationError: missing required field 'pr_number'，而不是把错误丢给下游服务；接着检查permissions，发现需要network和secrets，就会提前提示用户确认是否授权，并安全注入GITHUB_TOKEN环境变量；最后调用./run.sh，并将diff_content等参数以 JSON 格式通过 stdin 传入。

./run.sh的内容极简，却至关重要：

#!/bin/bash set -e # 1. 从 stdin 读取标准化输入 INPUT=$(cat /dev/stdin) REPO_OWNER=$(echo "$INPUT" | jq -r '.repo_owner') PR_NUMBER=$(echo "$INPUT" | jq -r '.pr_number') DIFF=$(echo "$INPUT" | jq -r '.diff_content') # 2. 调用核心逻辑（此处调用 Python 脚本） python3 ./reviewer.py \ --repo-owner "$REPO_OWNER" \ --repo-name "$REPO_NAME" \ --pr-number "$PR_NUMBER" \ --diff "$DIFF" \ --model-provider "$MODEL_PROVIDER" \ --model-name "$MODEL_NAME" # 3. 输出严格符合 output_schema 的 JSON # reviewer.py 的最后一行必须是：print(json.dumps(result, ensure_ascii=False))

注意三个关键点：第一，run.sh不做任何业务逻辑，只负责协议桥接——它把 agent-skills 的标准化输入，转换成业务脚本（reviewer.py）能理解的命令行参数；第二，所有敏感信息（如GITHUB_TOKEN）由 Agent 运行时注入，skill 本身不硬编码、不读取.env文件，彻底隔离密钥风险；第三，reviewer.py的输出必须是纯 JSON，且结构必须与output_schema完全一致，Agent 会用 JSON Schema 验证器做最终校验，不匹配则视为 skill 执行失败。

实测下来，这套机制带来的好处非常实在：当公司升级 GitHub API 权限策略时，运维只需更新GITHUB_TOKEN的注入逻辑，所有基于 agent-skills 协议的 GitHub 相关 skill（PR Reviewer、Issue Auto-Closer、Dependency Alert）全部自动生效，无需修改任何一个 skill 的代码；当需要把评审模型从 DeepSeek 切换到 Qwen 时，只需在 CLI 配置里改一行MODEL_PROVIDER=qwen-official，所有 skill 无缝切换——因为模型选择是运行时决策，不是 skill 内部硬编码。

注意：execution.mode: sync表示同步执行，适合耗时 < 2 分钟的任务。对于长周期任务（如训练小模型、批量视频转码），应设为async，此时 skill 需实现/status和/result两个 HTTP 端点，Agent 通过轮询获取结果。这是 agent-skills 协议支持的两种标准模式，不能自行发明第三种。

3. CLI 工具链如何识别、加载并安全执行 agent-skills

理解了 skill 的定义格式，下一个问题是：CLI 工具（如 codex、trae、zcode）是怎么把它“活”起来的？不是简单地sh ./run.sh就完事——那会带来严重的安全与稳定性风险。一个成熟的 CLI 必须完成四层工作：发现（Discovery）、加载（Loading）、沙箱化（Sandboxing）、编排（Orchestration）。我们以 codex CLI 为例，拆解其内部流程。

3.1 发现：从本地目录到远程 Registry 的多源索引

codex CLI 启动时，会按优先级顺序扫描以下位置的.skill.yaml文件：

当前工作目录下的./skills/子目录（最高优先级，用于快速原型验证）；
用户主目录下的~/.codex/skills/（个人常用 skill 集）；
全局安装路径/usr/local/share/codex/skills/（系统级预装 skill）；
远程 Registry（如 https://registry.codex.dev/skills）（通过codex skills install github-pr-reviewer下载）。

关键在于，它不是简单地find . -name "*.skill.yaml"，而是构建了一个带元数据缓存的索引树。每次扫描时，CLI 会读取每个 YAML 文件的id、version、tags、categories，并计算文件内容的 SHA256 哈希值，存入本地 SQLite 数据库~/.codex/skills.db。这样做的好处是：codex skills list --tag=devops这类命令能毫秒级响应，无需实时遍历文件系统；codex skills update时，CLI 只需比对远程 Registry 的哈希值，就能精准判断哪些 skill 需要下载或更新，避免全量拉取。

更进一步，codex 支持skills.yaml清单文件，允许用户定义一组 skill 的依赖关系：

# my-stack.skills.yaml name: frontend-dev-stack version: 1.0 skills: - id: github-pr-reviewer version: "^1.2.0" - id: npm-audit-scanner version: "~0.8.3" - id: vite-bundle-analyzer version: ">=2.1.0"

执行codex skills apply my-stack.skills.yaml时，CLI 会解析依赖树，自动处理版本冲突（如两个 skill 都要求不同版本的common-utils），并生成一个锁定文件my-stack.lock.yaml，确保团队内所有人加载完全一致的 skill 组合。这本质上就是前端领域的package-lock.json，只是针对 agent-skills 生态。

3.2 加载：YAML 解析与运行时契约校验

发现 skill 后，CLI 进入加载阶段。这不是简单的yaml.load()，而是一系列强制校验：

协议版本校验：检查version字段是否在 CLI 支持范围内（codex v3.x 支持1.0~1.3，不支持2.0）；
Schema 合法性校验：用预编译的 JSON Schema 验证input_schema和output_schema是否语法正确（例如maxLength不能是负数，required数组不能包含不存在的字段）；
权限可行性校验：检查permissions中声明的能力，当前运行环境是否支持。例如，在 Windows Subsystem for Linux (WSL) 中，filesystem: write是允许的，但docker: true（若声明了 Docker 权限）则会报错Docker daemon not accessible；
入口点存在性校验：检查execution.entrypoint文件是否存在、是否可执行（chmod +x）、是否为 shell 脚本或 Python 文件（通过 shebang 判断）。

任何一项校验失败，CLI 都会给出明确错误定位。比如：

Error loading skill 'github-pr-reviewer': - input_schema: 'diff_content.maxLength' must be >= 0 (got -1) - permissions: 'docker' declared but Docker socket not found at /var/run/docker.sock - execution.entrypoint: './run.sh' is not executable (chmod +x ./run.sh to fix)

这种“fail-fast”设计，把问题拦截在执行前，极大降低了调试成本。我见过太多团队把校验逻辑放到 skill 内部，导致错误堆栈深、定位难、日志混乱。

3.3 沙箱化：进程隔离与资源限制的硬核实践

这才是 agent-skills 安全落地的核心。CLI 绝不会用os.system()直接执行./run.sh。以 Linux 为例，codex 使用unshare+cgroups构建轻量级沙箱：

命名空间隔离：调用unshare --user --pid --mount --net --uts创建新命名空间，skill 进程看不到宿主机的进程树、网络接口、挂载点；
资源限制：通过cgroups v2设置 CPU Quota（最多使用 1 个逻辑核的 50%）、内存上限（2GB）、磁盘 I/O 速率（10MB/s）；
文件系统只读：除./（skill 目录）和/tmp外，整个根文件系统挂载为ro（只读），防止 skill 恶意修改系统文件；
环境变量净化：只注入 skill YAML 中声明的environment（如GITHUB_TOKEN），清除所有用户环境变量（PATH、HOME等被重置为最小集）；
网络策略：默认禁用网络，仅当permissions.network: true时，才通过iptables规则放行https://api.github.com等白名单域名，其他请求一律拒绝。

这套机制的效果立竿见影。去年我们上线一个调用第三方天气 API 的 skill，其内部 Python 脚本有个未修复的 DNS 劫持漏洞，会尝试连接malicious-ads.net。在沙箱环境下，该请求被iptables直接 DROP，skill 因超时失败退出，未对宿主机造成任何影响。而如果直接执行，这个请求可能污染 DNS 缓存，影响整个开发机。

提示：Windows 和 macOS 用户不必担心。codex 在这些平台使用Windows Sandbox（Win10/11）或sandbox-exec（macOS）替代unshare，原理相同，只是底层技术不同。CLI 会自动检测平台并选择最优方案。

4. 开发一个 agent-skills 的完整工作流：从零到发布

现在，我们动手开发一个实用 skill：pdd-order-tracker.skill.yaml，用于查询拼多多订单物流状态。这不仅是技术练习，更是理解 agent-skills 开发范式的最佳入口。整个流程分为五步：需求分析 → 协议定义 → 核心逻辑开发 → 本地测试 → 发布到 Registry。

4.1 需求分析：明确边界与失败场景

在写 YAML 之前，先厘清业务边界：

输入：拼多多订单号（order_sn，字符串，16位数字）、用户 access_token（从拼多多开放平台获取）；
输出：物流轨迹数组（含时间、地点、状态）、当前物流状态摘要；
失败场景：订单号不存在、access_token 过期、拼多多 API 限流（429）、网络超时、返回 JSON 格式异常。

这些都要转化为 YAML 中的input_schema和output_schema，并指导后续错误处理逻辑。特别注意access_token是敏感信息，必须声明为secret，不能出现在日志中。

4.2 协议定义：编写严谨的 .skill.yaml

kind: agent-skills version: 1.2 id: pdd-order-tracker name: Pinduoduo Order Tracker description: Query real-time logistics status for a Pinduoduo order using official API. author: your-name@domain.com license: MIT input_schema: type: object required: [order_sn, access_token] properties: order_sn: type: string pattern: '^[0-9]{16}$' description: 16-digit Pinduoduo order number access_token: type: string description: OAuth2 access token from Pinduoduo Open Platform (treated as secret) output_schema: type: object required: [logistics_traces, current_status] properties: logistics_traces: type: array items: type: object required: [time, location, status_desc] properties: time: { type: string, format: "date-time" } location: { type: string } status_desc: { type: string } current_status: type: string enum: ["pending", "shipped", "delivered", "cancelled"] execution: mode: sync timeout_seconds: 45 entrypoint: ./run.sh environment: PDD_API_BASE_URL: https://api.pinduoduo.com PDD_API_VERSION: v1 permissions: - network: true - secrets: [access_token] tags: [ecommerce, logistics, pdd] categories: [business, operations]

这里的关键设计点：

pattern: '^[0-9]{16}$'对订单号做正则校验，比单纯type: string更安全；
format: "date-time"让 Agent 知道time字段是 ISO8601 时间，可自动做时区转换；
enum限定current_status取值，避免 skill 返回shippied（拼写错误）导致下游解析失败。

4.3 核心逻辑开发：Python 脚本的健壮性实践

./reviewer.py（实际是./tracker.py）的代码必须处理所有已知失败场景，并返回结构化错误：

#!/usr/bin/env python3 import sys import json import os import requests from datetime import datetime def main(): try: # 1. 读取 stdin 输入 input_data = json.load(sys.stdin) order_sn = input_data['order_sn'] access_token = input_data['access_token'] # 2. 构造拼多多 API 请求 api_url = f"{os.environ['PDD_API_BASE_URL']}/logistics/traces" headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json" } payload = {"order_sn": order_sn} # 3. 带重试的 HTTP 调用（最多 3 次） for attempt in range(3): try: resp = requests.post( api_url, json=payload, headers=headers, timeout=(5, 30) # connect:5s, read:30s ) resp.raise_for_status() break except requests.exceptions.RequestException as e: if attempt == 2: raise e # 短暂等待后重试 import time time.sleep(0.5 * (2 ** attempt)) # 4. 解析响应，映射到 output_schema api_resp = resp.json() traces = [] for trace in api_resp.get("traces", []): traces.append({ "time": datetime.fromtimestamp(trace["timestamp"]).isoformat(), "location": trace.get("location", ""), "status_desc": trace.get("status_desc", "") }) # 5. 构建符合 schema 的输出 result = { "logistics_traces": traces, "current_status": api_resp.get("status", "pending") } print(json.dumps(result, ensure_ascii=False)) except json.JSONDecodeError as e: # 输入 JSON 格式错误 error_result = {"error": "Invalid input JSON", "details": str(e)} print(json.dumps(error_result, ensure_ascii=False)) sys.exit(1) except requests.exceptions.HTTPError as e: # API 返回 4xx/5xx error_result = {"error": "PDD API Error", "status_code": e.response.status_code} if e.response.status_code == 401: error_result["hint"] = "Check if access_token is expired" print(json.dumps(error_result, ensure_ascii=False)) sys.exit(1) except Exception as e: # 其他未预期错误 error_result = {"error": "Internal processing error", "details": str(e)} print(json.dumps(error_result, ensure_ascii=False)) sys.exit(1) if __name__ == "__main__": main()

这段代码的亮点在于：

显式错误分类：区分JSONDecodeError（输入问题）、HTTPError（API 问题）、Exception（内部问题），每种都返回结构化错误对象，Agent 可据此做不同处理（如对 401 提示用户刷新 token）；
指数退避重试：对网络抖动做容错，避免一次失败就放弃；
时间戳转换：将拼多多返回的 Unix 时间戳转为 ISO8601，满足output_schema的format: "date-time"要求。

4.4 本地测试：CLI 内置的测试框架

codex CLI 提供codex skills test命令，无需启动任何服务：

# 准备测试输入 cat > test-input.json << 'EOF' { "order_sn": "1234567890123456", "access_token": "your-real-token-here" } EOF # 执行测试（自动进入沙箱） codex skills test ./pdd-order-tracker.skill.yaml < test-input.json # 输出会显示： # ✅ Input validation passed # ✅ Execution succeeded (exit code 0) # ✅ Output matches output_schema # 📋 Result: {"logistics_traces": [...], "current_status": "shipped"}

这个命令会：

自动加载 skill YAML；
用input_schema验证test-input.json；
在真实沙箱环境中执行./run.sh；
用output_schema验证返回 JSON；
输出详细的通过/失败报告。

比手动写pytest测试快得多，且保证了测试环境与生产环境一致。

4.5 发布到 Registry：签名与版本控制

最后一步，发布到公共 Registry：

# 1. 生成 GPG 签名（确保完整性） gpg --detach-sign --armor pdd-order-tracker.skill.yaml # 2. 构建发布包（包含 YAML、run.sh、tracker.py、README.md） tar -czf pdd-order-tracker-1.0.0.tgz \ pdd-order-tracker.skill.yaml \ pdd-order-tracker.skill.yaml.asc \ run.sh \ tracker.py \ README.md # 3. 推送到 Registry（需 API Key） codex skills publish \ --file pdd-order-tracker-1.0.0.tgz \ --api-key YOUR_REGISTRY_KEY \ --version 1.0.0

Registry 会验证 GPG 签名，存储 tar 包，并生成一个唯一的 content-addressable URL（如https://registry.codex.dev/skills/pdd-order-tracker/1.0.0/sha256:abc123...）。其他用户执行codex skills install pdd-order-tracker时，CLI 会从这个 URL 下载，并用公钥验证签名，确保未被篡改。

5. agent-skills 生态的现状与避坑指南：那些文档里不会写的真相

经过一年在多个团队推广 agent-skills 协议，我总结出几条血泪经验——这些不是理论推导，而是踩过坑、修过半夜线上故障后的真实体会。它们往往被官方文档忽略，却是决定项目成败的关键。

5.1 最大陷阱：把 skill 当作微服务来设计

很多团队一上来就想用agent-skills实现“高可用、可伸缩”的能力，于是给每个 skill 配上 Kubernetes Deployment、Service、Ingress，走 HTTP 调用。这完全违背了协议初衷。agent-skills 的设计哲学是“进程内优先，网络调用次选”。原因有三：

延迟爆炸：本地进程调用./run.sh是毫秒级；HTTP 调用至少增加 50ms 网络往返，加上序列化/反序列化，轻松破百毫秒。一个需要串行调用 5 个 skill 的 Agent，延迟从 200ms 变成 500ms+，用户体验断崖下跌；
运维复杂度翻倍：一个 skill 对应一个 K8s Pod，意味着要管理 Service Mesh、证书轮换、健康检查探针、HPA 策略……而一个 CLI 工具链，本应是开箱即用的单二进制文件；
调试地狱：codex skills list显示 skill 正常，但codex run --skill github-pr-reviewer却报Connection refused，你得查 Istio 日志、K8s Event、Pod 事件，层层嵌套。

正确做法：95% 的 skill 应作为本地进程运行。只有两类场景才考虑 HTTP：

需要 GPU 加速的 heavy-lifting task（如视频生成），必须用专用节点；
需要共享状态的 long-running service（如一个 Redis-backed 的 session manager）。

即便如此，也应通过execution.mode: async+callback_url机制集成，而非让 Agent 主动轮询。

5.2 权限模型的致命误区：过度授权与权限缺失

permissions字段常被误用。常见错误有两种：

过度授权：permissions: [network: true, filesystem: read, filesystem: write]—— 这等于给了 skill 全盘读写权限，一个恶意 skill 可以删掉用户整个~/Documents；
权限缺失：声明network: true，却忘了在environment中注入代理配置，导致 skill 在企业内网无法访问外网 API。

安全实践：

最小权限原则：只声明绝对必需的权限。filesystem: read足够时，绝不写filesystem: true；
细粒度路径控制：filesystem: { read: ["/tmp", "/home/user/.config/myapp"] }（部分 CLI 已支持）；
代理透明化：CLI 运行时自动注入HTTP_PROXY/HTTPS_PROXY环境变量，skill 无需关心，只需用标准库发起 HTTP 请求。

5.3 版本管理的隐形雷区：语义化版本 vs 实际兼容性

version: 1.2看似遵循 SemVer，但 agent-skills 的兼容性判断不能只看数字。真正的兼容性取决于input_schema和output_schema的变更：

向后兼容：input_schema新增可选字段、output_schema新增可选字段、execution.timeout_seconds从 30 改为 45；
破坏性变更：input_schema删除必填字段、output_schema修改必填字段类型（如string→integer）、execution.entrypoint文件名变更。

团队规范：

所有 skill 的version必须由 CI/CD 流水线自动生成（如git describe --tags），禁止手动修改；
每次 PR 合并前，CI 必须运行schema-compat-check工具，比对新旧版本 YAML，自动判断是否为破坏性变更，并阻止合并；
破坏性变更必须发布新 major 版本（2.0.0），并在 changelog 中明确列出所有 schema 变更点。

5.4 调试技能：如何在沙箱中高效定位问题

当codex skills test报错，但./run.sh在终端里单独运行却正常，怎么办？这是沙箱环境导致的典型问题。我的调试清单：

检查环境变量：在run.sh开头加env | grep -E "^(PDD|GITHUB|MODEL)" > /tmp/env-debug.log，查看 CLI 注入的变量是否符合预期；
捕获 stderr：codex skills test默认只显示 stdout，错误信息可能在 stderr。修改run.sh，将2>&1重定向到日志文件；
模拟沙箱：用unshare --user --pid --mount --net --uts /bin/bash手动进入沙箱，再执行./run.sh，复现问题；
检查文件权限：沙箱中./tracker.py可能因 SELinux 或 AppArmor 被拒绝执行，用ls -Z ./tracker.py查看安全上下文。

最有效的技巧是：在 skill 目录下放一个debug.sh脚本，一键复现沙箱环境：

#!/bin/bash # debug.sh unshare --user --pid --mount --net --uts \ --setuid 1000 --setgid 1000 \ --bind /proc:/proc \ --bind /sys:/sys \ --bind /dev:/dev \ --bind $(pwd):$(pwd) \ --chdir $(pwd) \ /bin/bash -c "cd $(pwd); ./run.sh"

运行./debug.sh < test-input.json，就能 100% 复现 CLI 的执行环境。

我在实际使用中发现，真正让 agent-skills 协议落地的，从来不是炫酷的技术，而是这些琐碎却关键的工程细节：一个严谨的 schema、一次干净的沙箱、一份清晰的错误反馈、一个可复现的调试流程。当团队能把这些“脏活累活”标准化，能力复用才不再是口号，而成为每天都在发生的生产力提升。