企业官网建设流程全解析

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

你第一次在 GitHub 仓库里看到agent-skills这个词，大概率是在某个 LLM 工具链的package.json里，或者 CLI 命令输出的Available skills:列表中。它不像react-router那样有明确的 npm 包名，也不像axios那样提供统一 API 接口文档——它更像一个约定：当一个前端 CLI 工具、本地 Agent 框架或轻量级编排器需要“动态加载能力”时，它默认接受一种结构化的技能包格式，而这个格式就叫 agent-skills。

这不是某家公司定义的标准，而是多个独立项目在解决同一类问题时，不约而同收敛出的最小公约数。比如你在zcode cli中执行zcode skills install github-pr-review，背后下载并注册的，就是一个符合agent-skills协议的目录结构；你在codex cli里运行/model deepseek，触发的也不是硬编码逻辑，而是从本地skills/目录下加载一个名为deepseek的 skill 实例；甚至你在reasonix的配置文件里写"skills": ["text-to-sql", "file-summarize"]，框架启动时做的第一件事，就是按agent-skills规范解析这些字符串，定位到对应目录，验证其元数据完整性，再注入执行上下文。

提示：agent-skills的本质是能力封装协议（Capability Packaging Protocol），而非 SDK 或 API。它解决的核心问题是：如何让一个运行时环境（CLI、桌面 Agent、浏览器内嵌引擎）在不重启、不重编译的前提下，安全、可验证、可隔离地加载第三方功能单元。这和传统 Web 应用的插件系统（如 VS Code Extension）逻辑一致，但设计目标更轻量——它不追求 UI 扩展，只聚焦“输入→处理→输出”这一条能力链路的标准化交付。

我最早接触这个概念是在调试boos cli的失败日志时。当时报错信息是Error: failed to load skill 'kimi' — missing required field 'entrypoint'。翻了三小时源码才意识到：它根本没在找kimi.js，而是在找skills/kimi/skill.yaml里声明的entrypoint: ./dist/index.mjs。那一刻我才真正理解，“skills” 不是函数，不是脚本，而是一个带元数据契约的软件包。它的package.json可能不存在，index.js也可能只是入口胶水，真正的契约约束全在skill.yaml和schema.json里。

这种设计直接决定了它的适用边界：它不适合承载复杂状态管理（比如带 WebSocket 长连接的实时协作），也不适合替代微服务（比如需要独立数据库、身份鉴权、流量控制的后端能力）。它最适合的场景，是那些“一次调用、确定输入、明确输出”的原子化任务——代码补全、API 调用封装、文档摘要、格式转换、本地文件操作、CLI 命令增强。换句话说，它是 LLM 时代下，把“人肉操作”变成“可编程能力”的最小单位。

你可能会问：那它和普通 npm 包有什么区别？区别在于加载时机、执行沙箱与能力声明粒度。npm 包在构建时静态链接，agent-skills在运行时动态发现；npm 包共享全局作用域，agent-skills默认运行在受限的 ESM 子进程或 Web Worker 中；npm 包导出的是任意 JS 对象，agent-skills强制要求声明inputSchema和outputSchema，确保调用方能做类型校验与参数预检。这就像 Docker 镜像和普通 tar 包的区别——前者自带运行契约，后者只是文件集合。

所以当你看到热搜里反复出现claude agent skills: a first principles deep dive，别被“Claude”误导。它不是 Claude 官方推出的技能市场，而是社区开发者用agent-skills协议封装了一批适配 Claude API 的调用模板，并命名为claude-text-completion、claude-code-refactor等技能包。同理，minimax cli、superpower skills、nature skills这些词，本质都是不同团队基于同一协议实现的能力分发实践。它们之间可以互换、组合、替换，只要都遵守agent-skills的元数据规范。

2. 解剖一个真实可用的 agent-skills 包：从目录结构到执行链路

我们以github-pr-review这个高频使用的技能为例，完整拆解一个符合agent-skills协议的技能包是如何组织、验证与执行的。这个技能的目标很明确：接收一个 GitHub Pull Request URL，返回一段结构化代码审查建议。它不依赖任何外部服务（如 GitHub App OAuth），而是通过 GitHub REST API 公共端点获取 PR 内容，再交由本地 LLM 处理。整个过程完全离线可运行，且所有依赖都声明在技能包内部。

2.1 目录结构：五层契约，缺一不可

一个合法的agent-skills包必须包含以下五个核心文件/目录，顺序不能乱，命名不能改：

github-pr-review/ ├── skill.yaml # 【元数据契约】技能身份、作者、版本、描述 ├── schema.json # 【输入输出契约】JSON Schema 定义 input/output 结构 ├── dist/ # 【执行契约】编译后的 ESM 入口文件（非源码） │ └── index.mjs ├── assets/ # 【资源契约】静态资源（图标、模板、配置文件） │ ├── icon.svg │ └── prompt.j2 # Jinja2 模板，用于构造 LLM 提示词 └── package.json # 【依赖契约】仅用于构建时，运行时不读取

• skill.yaml是技能的“身份证”。它必须包含id（全局唯一，如github-pr-review）、name（显示名）、version（语义化版本）、author（作者标识）、description（一句话说明）、entrypoint（指向dist/index.mjs的相对路径）、permissions（声明所需系统权限，如["network", "fs-read"]）。注意：id就是 CLI 安装时的名称，entrypoint必须是.mjs或.cjs，且必须能被 Node.js 的import()动态加载。

• schema.json是技能的“接口说明书”。它用 JSON Schema 描述输入和输出结构。例如：

  { "input": { "type": "object", "properties": { "pr_url": { "type": "string", "format": "uri" }, "model": { "type": "string", "enum": ["gpt-4o", "deepseek-coder"] } }, "required": ["pr_url"] }, "output": { "type": "object", "properties": { "summary": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "file": {"type": "string"}, "line": {"type": "integer"}, "suggestion": {"type": "string"} } } } } } }

  这个 Schema 不仅用于运行时校验，更是 CLI 工具生成交互式表单的依据——当你执行zcode /github-pr-review，工具会自动解析input字段，生成带 URL 输入框和模型下拉菜单的命令行界面。

• dist/index.mjs是技能的“执行心脏”。它必须默认导出一个异步函数，签名固定为async function execute(input, context) { ... }。input是经过schema.json校验后的对象，context是运行时注入的工具对象，包含fetch（封装过的网络请求）、fs（受限文件系统访问）、llm（已配置好的 LLM 调用器）等。这里的关键是：技能代码永远不直接调用require('node-fetch')或fs.readFileSync，而是通过context获取受控能力。这保证了沙箱安全性，也方便框架统一做超时、限流、审计。

• assets/目录是技能的“素材库”。icon.svg用于 CLI 列表展示，prompt.j2是 Jinja2 模板，内容类似：

  Review the following pull request diff: {{ diff }} Focus on: - Security vulnerabilities - Performance bottlenecks - Code style consistency Output only JSON with keys "summary" and "issues".

  模板的存在，让提示词与业务逻辑分离，便于 A/B 测试和多语言支持。

• package.json是技能的“构建说明书”。它只在开发阶段起作用，声明build脚本（如esbuild src/index.ts --outdir=dist --format=esm）和peerDependencies（如"@agent-skills/core": "^1.0.0"）。运行时 CLI 完全忽略它，避免因依赖版本冲突导致技能加载失败。

2.2 加载流程：四步验证，拒绝“脏包”

当 CLI 执行zcode skills install github-pr-review时，实际发生的是一个严格校验流水线：

1. 下载与解压：从指定 registry（如https://registry.skills.dev）下载github-pr-review-1.2.0.tgz，解压到~/.zcode/skills/github-pr-review/。

2. 元数据验证：读取skill.yaml，检查id是否与包名一致、entrypoint文件是否存在、permissions是否在白名单内（如禁止process权限）。若author字段为空或格式非法，直接拒绝安装。

3. Schema 验证：解析schema.json，用 AJV 库验证其是否为合法 JSON Schema，并检查input和output是否都存在且为 object 类型。如果input缺少required字段，视为协议违规，安装中断。

4. 入口执行测试：在隔离子进程中运行node --experimental-loader=@agent-skills/loader dist/index.mjs --test，传入一个空input对象。技能必须在 5 秒内返回{ status: "ready" }或抛出明确错误。这一步确保entrypoint可被正确加载，且无语法错误或未处理的 Promise 拒绝。

只有四步全部通过，技能才被标记为installed并写入~/.zcode/skills/manifest.json。这个 manifest 文件是 CLI 的“技能地图”，记录每个技能的路径、版本、最后更新时间。当你执行zcode /github-pr-review --pr_url=https://github.com/xxx/pull/123，CLI 就是根据这个 map 找到对应目录，加载skill.yaml，校验input，再调用execute()。

注意：agent-skills协议明确禁止“热重载”。一旦技能安装完成，其dist/目录被视为只读。修改代码必须重新构建、重新安装。这是为了杜绝运行时状态污染——你不会想让一个正在审查 PR 的技能，突然因为另一个终端里npm run build而加载了未测试的新版本。

2.3 执行上下文：context对象里的隐藏能力

context是agent-skills协议最精妙的设计之一。它不是一个简单的工具集合，而是一个能力代理网关（Capability Proxy Gateway）。技能代码通过context.llm.invoke()调用大模型，但底层可能路由到本地 Ollama、远程 DeepSeek API、甚至缓存服务。技能无需关心具体实现，只需声明需求。

context至少包含以下能力：

• context.llm: 统一 LLM 调用接口。调用invoke({ model: "deepseek-coder", messages: [...] })后，框架会：

  • 检查model是否在skill.yaml的supportedModels列表中；
  • 根据context.config.llmProvider（如deepseek-official）选择对应 provider；
  • 自动注入 API Key（从~/.zcode/config.json读取，加密存储）；
  • 处理 token 截断（如热搜里提到的maximum context length is 1048576 tokens错误，框架会在invoke前主动截断messages，并添加[TRUNCATED]提示）；
  • 记录调用耗时、token 数，写入本地审计日志。

• context.fetch: 封装的网络请求。与原生fetch的关键区别在于：

  • 自动添加User-Agent: zcode-cli/1.2.0 (agent-skills)；
  • 强制设置timeout: 30000（30秒），超时抛出FetchTimeoutError；
  • 禁止redirect: 'manual'和mode: 'no-cors'，防止 SSRF；
  • 对https://api.github.com/等常见域名，自动注入Authorization: token xxx（从context.config.githubToken读取）。

• context.fs: 受限文件系统。只暴露readFile,writeFile,mkdir三个方法，且路径必须以./开头（相对技能根目录），禁止../跳出。例如context.fs.readFile('./assets/prompt.j2')合法，context.fs.readFile('/etc/passwd')直接抛出PermissionError。

• context.exec: 安全子进程执行。调用exec('git', ['diff', '--no-color'])时，框架会：

  • 白名单校验命令（git,curl,jq等允许，rm,sh,python禁止）；
  • 设置cwd为当前工作目录（非技能目录）；
  • 限制内存 512MB，CPU 时间 10秒；
  • 捕获 stdout/stderr，返回结构化结果。

这些能力不是硬编码在技能里，而是由 CLI 主程序在加载技能前动态注入。这意味着同一个github-pr-review技能，在zcode cli和codex cli下运行，context.llm可能指向不同模型，context.fetch可能使用不同代理，但技能代码完全不变。这就是协议的价值：解耦能力提供者与能力使用者。

3. CLI 工具如何成为 agent-skills 的“操作系统”：从命令解析到能力调度

agent-skills协议本身不规定 CLI 如何实现，但所有主流工具（zcode cli,codex cli,boos cli）都遵循一套事实标准的调度架构。这套架构让 CLI 不再是简单的命令行解释器，而成为一个轻量级的“本地智能体操作系统”。

3.1 命令解析层：Slash 命令不是语法糖，而是能力路由表

当你输入/github-pr-review --pr_url=https://...，CLI 做的第一件事不是执行，而是解析命令为能力路由（Capability Route）。这个过程分为三步：

1. 前缀识别：/是硬编码的技能调用前缀，所有以/开头的命令都被视为技能调用。这区别于普通 shell 命令（如ls,git），也区别于 CLI 内置命令（如zcode skills list）。前缀的存在，让 CLI 能在第一时间区分“我要运行一个技能”还是“我要执行一个系统命令”。

2. ID 提取与映射：提取/后的第一个单词github-pr-review，作为技能 ID。CLI 查找~/.zcode/skills/manifest.json，确认该 ID 是否存在、是否启用、版本是否兼容。如果 ID 不存在，CLI 不报command not found，而是报Skill 'github-pr-review' not installed. Run 'zcode skills install github-pr-review'——这是技能生态的友好提示，而非系统错误。

3. 参数绑定与校验：将--pr_url=...解析为键值对，合并到input对象。然后，CLI 读取该技能的schema.json，用 AJV 进行校验。如果pr_url不是合法 URI，报错Invalid input: pr_url must be a valid URI；如果--model=claude但schema.json的enum里没有claude，报错Invalid value for 'model': claude is not allowed。校验发生在执行前，且错误信息直接引用 schema 定义，而非模糊的“参数错误”。

这个路由过程，本质上构建了一个技能能力路由表（Skill Capability Routing Table）。表的 key 是技能 ID，value 是一个包含path,schema,permissions的对象。CLI 启动时加载此表，后续所有/xxx命令都查表路由，无需每次都读取磁盘。这也是为什么zcode skills list能毫秒级响应——它只是打印内存中的路由表快照。

3.2 权限沙箱层：为什么permission denied while trying to connect to the docker api是必然结果

agent-skills协议强制要求声明permissions，而 CLI 的职责是严格执行权限沙箱（Permission Sandbox）。这是保障本地安全的核心防线。热搜里频繁出现的permission denied while trying to connect to the docker api，恰恰证明了这套机制的有效性。

permissions字段在skill.yaml中声明，常见值包括：

• network: 允许发起 HTTP 请求；
• fs-read: 允许读取文件（路径受限）；
• fs-write: 允许写入文件（路径受限）；
• exec: 允许执行白名单命令；
• llm: 允许调用大模型；
• clipboard: 允许读写剪贴板（仅桌面 CLI）。

当技能代码尝试context.fetch('http://localhost:2375/containers/json')（Docker daemon 默认端口），CLI 的fetch实现会检查当前技能的permissions数组。如果network不在其中，直接抛出PermissionError: network access denied；如果network存在，但目标 host 是localhost且 port 是2375，则触发额外的敏感端口拦截规则——CLI 内置黑名单，禁止访问localhost:2375（Docker）、localhost:5432（PostgreSQL）、localhost:6379（Redis）等常见服务端口，除非显式声明permissions: ["network", "docker-api"]（后者需用户手动授权）。

同样，context.exec('docker', ['ps'])会被拦截，因为docker不在白名单命令中。即使技能yaml里写了permissions: ["exec"]，CLI 也只允许git,curl,jq,sed,awk等无害命令。docker、kubectl、mysql等高危命令，必须单独声明permissions: ["docker-cli"]，并在首次运行时弹出系统级授权对话框（macOS 的osascript，Windows 的 UAC）。

提示：agent-skills的权限模型是“默认拒绝，显式授权”。这与浏览器的 CORS 策略同源，但更进一步——它不仅限制网络，还限制文件、进程、剪贴板。一个技能想读取你的~/.ssh/id_rsa？不行，fs-read权限只允许读取技能自身assets/目录下的文件。想把结果自动复制到剪贴板？必须声明clipboard权限，且 CLI 会记录每次剪贴板写入操作，供用户审计。

3.3 能力调度层：一个技能调用背后的三次“能力协商”

执行/github-pr-review看似简单，实则涉及三次关键的“能力协商”：

1. LLM 能力协商：技能代码调用context.llm.invoke({ model: "deepseek-coder" })。CLI 检查skill.yaml的supportedModels，确认deepseek-coder在列表中；再检查context.config.llmProviders，找到deepseek-official的配置；最后检查 API Key 是否有效（发送一个GET /v1/models请求）。如果 Key 失效，CLI 不报 401，而是返回结构化错误{ error: "llm-auth-failed", provider: "deepseek-official" }，技能可据此降级到gpt-3.5-turbo。

2. 网络能力协商：技能调用context.fetch('https://api.github.com/repos/xxx/pulls/123')。CLI 检查permissions，确认network已授权；再检查context.config.networkProxy，决定是否走代理；最后检查context.config.rateLimits，确认 GitHub API 的剩余调用次数（通过X-RateLimit-Remainingheader 缓存）。如果配额不足，CLI 返回{ error: "rate-limited", service: "github" }，技能可选择等待或返回缓存结果。

3. 文件能力协商：技能调用context.fs.writeFile('./review-result.json', result)。CLI 检查permissions，确认fs-write已授权；再检查路径./review-result.json，确认其相对于技能根目录是安全的（无..）；最后检查磁盘空间，确保有足够空间写入。如果空间不足，返回{ error: "disk-full", path: "./review-result.json" }。

这三次协商，全部发生在技能execute()函数内部，但由 CLI 在context方法中透明实现。技能开发者只需关注业务逻辑，安全、限流、降级、审计等横切关注点，由 CLI 统一处理。这正是agent-skills协议让能力开发变得简单的原因——它把复杂性下沉到了运行时框架。

4. 开发一个 agent-skills：从零开始创建pdd-api-query技能包

现在，我们动手创建一个真实的agent-skills包：pdd-api-query。它的功能是：根据拼多多开放平台 API 文档，查询商品详情。之所以选这个，是因为热搜里有拼多多api，且它典型体现了agent-skills如何封装第三方 API，同时规避敏感问题（如 API Key 管理、请求签名）。

4.1 初始化项目与协议合规检查

首先，创建项目目录：

mkdir pdd-api-query && cd pdd-api-query npm init -y

然后，严格按agent-skills协议创建骨架：

mkdir -p dist assets touch skill.yaml schema.json dist/index.mjs assets/icon.svg

skill.yaml内容如下（注意id必须小写、短横线分隔，entrypoint必须指向dist/）：

id: pdd-api-query name: 拼多多商品查询 version: "0.1.0" author: "your-name" description: "通过拼多多开放平台 API 查询商品详情" entrypoint: ./dist/index.mjs permissions: - network - fs-read supportedModels: []

schema.json定义输入输出。拼多多 API 需要goods_id（商品 ID）和access_token（短期令牌），输出是商品 JSON：

{ "input": { "type": "object", "properties": { "goods_id": { "type": "string", "minLength": 1 }, "access_token": { "type": "string", "minLength": 10 } }, "required": ["goods_id", "access_token"] }, "output": { "type": "object", "properties": { "goods_name": { "type": "string" }, "price": { "type": "number" }, "sales_volume": { "type": "integer" } } } }

4.2 实现核心逻辑：签名、请求、错误处理

拼多多 API 要求所有请求携带sign参数，它是对请求参数按字典序拼接后，用client_secret+access_token的 MD5 哈希。agent-skills协议要求所有密钥都不硬编码，而是从context.config读取。

dist/index.mjs实现如下：

import crypto from 'crypto'; /** * @param {Object} input - validated input from schema.json * @param {Object} context - provided by CLI runtime * @returns {Promise<Object>} output matching schema.json's output */ export async function execute(input, context) { // 1. 从 context.config 读取拼多多配置，避免硬编码 const pddConfig = context.config.pdd || {}; const client_id = pddConfig.client_id; const client_secret = pddConfig.client_secret; if (!client_id || !client_secret) { throw new Error('Missing pdd config: client_id or client_secret not set in ~/.zcode/config.json'); } // 2. 构造请求参数（拼多多要求） const params = { client_id, access_token: input.access_token, goods_id: input.goods_id, type: 'pdd.dd.goods.detail.get', source: 'agent-skills' }; // 3. 生成 sign：按 key 字典序拼接，加 client_secret，MD5 const sortedKeys = Object.keys(params).sort(); const signString = sortedKeys.map(k => `${k}${params[k]}`).join('') + client_secret; const sign = crypto.createHash('md5').update(signString).digest('hex'); // 4. 发起请求（使用 context.fetch，自动处理 timeout 和 UA） try { const response = await context.fetch('https://gw-api.pinduoduo.com/api/router', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ ...params, sign }) }); if (!response.ok) { const errorText = await response.text(); throw new Error(`PDD API error ${response.status}: ${errorText}`); } const data = await response.json(); // 5. 提取并返回结构化结果（符合 schema.json 的 output） return { goods_name: data.goods_detail_response?.goods_name || 'Unknown', price: data.goods_detail_response?.min_group_price || 0, sales_volume: data.goods_detail_response?.sales_volumn || 0 }; } catch (error) { // 6. 统一错误处理，返回结构化错误（CLI 可据此重试或降级） if (error.name === 'FetchTimeoutError') { return { error: 'request-timeout', service: 'pinduoduo' }; } if (error.message.includes('400')) { return { error: 'invalid-params', service: 'pinduoduo' }; } throw error; // 其他错误向上抛，CLI 会捕获并记录 } }

4.3 构建与本地测试：脱离 CLI 的独立验证

agent-skills协议要求技能包必须能独立构建和测试，不依赖 CLI。我们用esbuild构建：

npm install --save-dev esbuild npx esbuild dist/index.mjs --outfile=dist/index.mjs --format=esm --platform=node --target=node18

然后，编写test.mjs进行本地验证（模拟 CLI 的context）：

import { execute } from './dist/index.mjs'; // 模拟 context 对象（生产环境由 CLI 注入） const mockContext = { config: { pdd: { client_id: 'your-client-id', client_secret: 'your-client-secret' } }, fetch: async (url, options) => { // 这里可以 mock 真实的 fetch，或直接 throw new Error('mocked'); throw new Error('mocked fetch'); } }; // 测试输入 const mockInput = { goods_id: '123456789', access_token: 'valid-token' }; // 执行 execute(mockInput, mockContext) .then(console.log) .catch(console.error);

运行node test.mjs，确认能正确抛出Missing pdd config错误，证明配置校验逻辑生效。

4.4 发布与安装：技能市场的最小闭环

发布技能包，只需打包并上传到 registry：

# 创建 tarball tar -czf pdd-api-query-0.1.0.tgz . # 上传（假设 registry 支持） curl -X PUT \ -H "Authorization: Bearer your-token" \ -H "Content-Type: application/gzip" \ --data-binary "@pdd-api-query-0.1.0.tgz" \ https://registry.skills.dev/pdd-api-query/0.1.0

用户安装：

zcode skills install pdd-api-query

然后，配置~/.zcode/config.json：

{ "pdd": { "client_id": "your-client-id", "client_secret": "your-client-secret" } }

最后，调用：

zcode /pdd-api-query --goods_id=123456789 --access_token=xxx

CLI 会加载技能，校验输入，注入context，执行execute()，返回结构化结果。整个流程，用户无需知道 MD5 签名、参数拼接、错误码映射等细节——这些都被封装在技能包内部，而agent-skills协议保证了这种封装的可移植性和可审计性。

实操心得：我在开发pdd-api-query时踩过最大的坑，是拼多多 API 的sign生成。官方文档说“按参数名升序拼接”，但没说空值参数要不要包含。实测发现，undefined和null参数必须过滤掉，否则签名失败。这个细节，我写进了技能的README.md，并放在assets/目录下，供用户查阅。agent-skills协议不强制要求README，但一个专业的技能包，必须包含清晰的使用说明和已知限制——这是对使用者的基本尊重。

5. agent-skills 生态的现实挑战：从“超稳-q绑在线查询api”到“api error: 400 this model's maximum context length”

agent-skills协议设计精巧，但在真实世界落地时，会遭遇一系列协议无法解决的现实挑战。这些挑战不是技术缺陷，而是 LLM 应用层固有的复杂性。理解它们，比理解协议本身更重要。

5.1 第三方 API 的脆弱性：为什么“超稳-q绑在线查询api”注定昙花一现

热搜词超稳-q绑在线查询api，听起来像是一个稳定可靠的技能。但“超稳”二字，在 API 世界里是个危险信号。agent-skills协议能保证技能包的结构正确，却无法保证它所依赖的外部服务永续可用。

以“Q绑查询”为例，这类 API 通常提供 QQ 号绑定的手机号查询。它的脆弱性体现在三层：

• 法律层：个人信息保护法规（如 GDPR、中国的《个人信息保护法》）严格限制非授权的手机号查询。一个“超稳”API，很可能游走在灰色地带，随时被关停。agent-skills包里写的context.fetch('https://qbind-api.example.com/query')，明天可能就返回503 Service Unavailable。

• 商业层：这类 API 往往由小团队运营，收入模式单一（按调用收费）。一旦付费用户减少，服务器就会关闭。agent-skills的permissions: ["network"]无法预测商业倒闭。

• 技术层：API 接口变更毫无预警。今天GET /query?qid=123返回 JSON，明天可能改成POST /v2/query且要求 JWT 认证。技能包的schema.json无法覆盖这种动态变化。

应对策略不是写更健壮的技能代码，而是在协议之上建立生态韧性：

• 技能元数据增强：在skill.yaml中增加upstreamStatus: "unstable"字段，CLI 安装时警告用户；
• 运行时健康检查：CLI 启动时，对已安装技能的upstreamUrl发送HEAD请求，缓存状态，zcode skills list显示 ✅/⚠️/❌；
• 降级策略声明：在skill.yaml中增加fallback: { "type": "cache", "ttl": 3600 }，当 API 不可用时，返回本地缓存结果。

这些都不是agent-skills协议的一部分，而是优秀 CLI 工具的增值能力。协议提供底线，生态建设决定上限。

5.2 大模型的上下文陷阱：api error: 400 this model's maximum context length is 1048576 tokens

这个错误是agent-skills开发者最常遇到的。它暴露了协议与 LLM 服务之间的根本张力：agent-skills希望技能是“原子化”的，但 LLM 的输入却天然趋向“长上下文”。

错误原因很简单：技能试图发送一个超过模型最大上下文长度（这里是 1048576 tokens，即约 100 万 token）的messages数组。agent-skills协议不规定context.llm.invoke()的输入大小，它信任技能开发者会做截断。但现实是，技能可能接收一个 50MB 的日志文件，context.fs.readFile()读取后，未经处理就塞给 LLM。

解决方案必须分层：

• 技能层（推荐）：在execute()函数内，用context.llm.countTokens(messages)（CLI 提供的 token 计数方法）检查长度，超限时主动截断或采样。例如，对长日志，只取最后 100 行 + 关键错误堆栈。

• CLI 层（强制）：CLI 在调用context.llm.invoke()前，