企业官网建设流程全解析

1. “agent-skills”不是插件包，而是一套可组合、可验证、可交付的智能体能力单元设计范式

你点开 GitHub 搜索 “agent-skills”，大概率会看到一堆空仓库、未维护的 README 或者夹杂在某个 CLI 工具文档里的模糊术语。这不是因为概念不重要，而是因为当前绝大多数人对它的理解还停留在“给 AI 加个功能按钮”的表层——比如“加个天气查询技能”“加个查股票技能”。但真正有工程价值的agent-skills，根本不是这种零散的、一次性的、无法复用的“小功能”，而是一套具备明确契约、独立生命周期、可声明式编排、带内置可观测性的能力单元（Capability Unit）。

我从 2022 年底开始在多个内部 Agent 平台项目中落地这套设计，覆盖金融风控、电商客服、研发辅助三类场景。最深的体会是：所有后期崩盘的 Agent 系统，90% 的根因都出在 skills 的定义方式上——它们被写成黑盒函数、硬编码进主逻辑、没有输入校验、没有失败兜底、没有调用上下文隔离。结果就是：一个天气技能里混着 HTTP 请求、JSON 解析、时区转换、错误重试逻辑；另一个 PDF 解析技能又重复写了三遍 Base64 编码和 MIME 类型判断；更可怕的是，当用户说“把刚才查到的股价发到钉钉群”，系统根本不知道该调用哪个 skill，因为没人定义过“发送消息”这个能力的语义边界和参数契约。

所以，“agent-skills”这个词，首先要剥离掉“技能”这个词带来的生活化误导。它不是“我会做饭”“我会修电脑”那种个人能力，而是像 Linux 中的ls、grep、curl这样的原子命令：每个都只做一件事，输入输出清晰，错误码明确，可以管道串联，可以被 shell 脚本调度，也可以被更高层的自动化流程编排。你不会说“我的 Linux 有 37 个技能”，你会说“我有 37 个符合 POSIX 标准的可执行命令”。

这直接决定了我们后续所有技术选型、目录结构、测试策略和部署方式。比如，为什么不用纯 Python 函数封装？因为函数没有标准入口、没有环境隔离、没有版本元数据、无法跨语言调用；为什么不用 REST API 做唯一载体？因为 HTTP 是网络协议，不是能力抽象层，它把传输细节（headers、status code、body format）和业务语义（“发送通知”“解析文档”）强行耦合，导致前端调用一个 skill 要写 20 行 fetch 配置，后端维护要同时管路由、鉴权、序列化、反序列化四层逻辑。

真正的 agent-skills 必须满足五个刚性条件：

• 可发现性（Discoverable）：能通过统一机制（如 CLI--list-skills或 API/v1/skills）自动枚举所有已注册能力，无需人工维护清单；
• 可验证性（Verifiable）：每个 skill 自带schema.json描述其输入参数类型、必填项、取值范围、输出结构，支持运行时 Schema 校验；
• 可隔离性（Isolated）：执行环境与主 Agent 进程分离（如子进程、容器、WebWorker），避免内存泄漏或异常崩溃影响全局；
• 可审计性（Auditable）：每次调用自动生成 trace_id、输入快照、输出摘要、耗时、状态码，日志格式统一，便于链路追踪；
• 可组合性（Composable）：支持声明式编排（如 YAML 流程定义），A 的输出能直接作为 B 的输入，无需手动 JSON.parse/JSON.stringify 转换。

这五条不是理想主义，而是我在三个项目中踩坑后总结出的生存底线。比如某次金融风控项目，一个“查询企业工商信息”的 skill 因为没做输入校验，被传入了超长字符串，触发了底层数据库的 full-text search 内存溢出，整个 Agent 服务卡死 17 分钟。事后复盘发现，如果当时强制要求每个 skill 提供input_schema.json，并在调用前做 JSON Schema 验证，这个故障根本不会发生——因为校验会在进入业务逻辑前就返回400 Bad Request: field 'company_name' exceeds max length 100，而不是让错误一路穿透到数据库层。

提示：不要试图用“文档约定”代替机器可读的契约。我见过太多团队在 Confluence 上写满“参数说明”，结果开发时还是靠猜、靠问、靠试错。Schema 不是负担，是防止低级错误的第一道防火墙。

2. CLI 是 agent-skills 的天然载体，而非可选外壳

当你看到热搜词里反复出现codex cli、zcode cli、trae cli、deveco cli，这不是偶然。CLI（Command-Line Interface）之所以成为 agent-skills 的事实标准载体，是因为它完美匹配了能力单元的五大刚性条件，且具备其他接口形式无法替代的工程优势。

先说一个反直觉的事实：所有声称“无 CLI 即可使用 skills”的平台，最终都会被迫补上 CLI 支持，而且补得非常痛苦。原因很简单——CLI 是唯一能同时满足“开发者本地调试”“CI/CD 自动化集成”“跨平台能力复用”“最小依赖运行时”的接口形态。GUI 界面太重，API 接口太泛，SDK 太语言绑定，而 CLI 是 Unix 哲学的终极体现：每个程序只做一件事，并做好；程序之间通过文本流协作。

以skills/weather为例，它的 CLI 形态应该是：

$ skills weather --city "Shanghai" --unit "celsius" { "location": "Shanghai", "temperature": 23.5, "condition": "partly cloudy", "humidity": 68, "timestamp": "2024-06-15T14:22:08Z" }

注意这里的关键设计点：

• 参数全部用--key value形式，而非位置参数，保证可读性和可省略性；
• 输出是标准 JSON，可被jq、sed、awk等任意 Unix 工具处理；
• 错误时输出人类可读错误信息 + 机器可解析的 exit code（如exit 1表示参数错误，exit 2表示网络超时）；
• 不依赖任何全局配置文件，所有必要参数必须显式传入或通过环境变量注入（如WEATHER_API_KEY）。

这种设计带来三个实操红利：
第一，本地开发零摩擦。你不需要启动整个 Agent 服务，就能单独测试一个 skill。改完代码，make build && ./dist/skills-weather --city Beijing一行命令跑通，比等 Web 服务热更新快 10 倍。我团队曾用此方式将单个 skill 的平均迭代周期从 42 分钟压缩到 3 分钟。
第二，CI/CD 流水线天然兼容。GitHub Actions、GitLab CI、Jenkins 全部原生支持 shell 命令执行。你可以轻松写出这样的测试步骤：

- name: Test weather skill run: | ./dist/skills-weather --city "Beijing" | jq -e '.temperature > 0' > /dev/null echo "✅ Weather skill returns valid temperature"

这比写一个 HTTP 测试用例简单得多，也更稳定——没有网络抖动、DNS 解析失败、SSL 证书过期等干扰因素。
第三，跨平台能力复用无损耗。一个用 Go 编写的skills/pdf-extractCLI，Windows 用户双击 exe，macOS 用户brew install skills-pdf-extract，Linux 用户apt install skills-pdf-extract，前端 Electron 应用通过child_process.spawn()调用，Node.js 后端用execa调用，Python 服务用subprocess.run()调用……所有调用方看到的都是同一套输入输出契约，完全屏蔽了实现语言和运行时的差异。

对比之下，REST API 就暴露了本质缺陷：它把能力调用变成了网络请求问题。你必须处理超时、重试、连接池、证书信任、代理配置、CORS、CSRF Token……这些全是传输层问题，和“解析 PDF”这个业务能力毫无关系。更糟的是，当你要在离线环境（如客户内网、航空电子设备）部署时，HTTP 服务根本起不来，而 CLI 可以直接运行。

所以，当你看到api error: 400 the supported api model names are deepseek-flash, deepseek-v4这类报错时，别急着去查模型名拼写——先问自己：这个能力是否真的需要走网络？如果只是本地文件解析、正则匹配、日期计算，为什么不用 CLI？网络调用永远是最后的选择，而不是默认选项。

注意：CLI 不等于“命令行工具集合”。一个合格的 agent-skills CLI 必须提供统一的顶层命令入口（如skills），并通过子命令分发（skills weather、skills pdf-extract）。禁止每个 skill 单独发布一个二进制（如weather-cli、pdf-extract-cli），否则会陷入包管理地狱。统一入口是可发现性的基础。

3. Slash Commands 是 skills 的用户侧语法糖，不是能力本身

很多人混淆了agent-skills和slash commands（斜杠命令）的关系，以为在 Slack、Discord 或飞书里敲/weather Shanghai就是在用 skills。这是巨大的认知偏差。Slash commands 只是 skills 在特定 UI 环境下的输入语法映射层，就像键盘按键和底层中断信号的关系——按 Ctrl+C 是用户操作，触发 SIGINT 是系统行为，两者不能等同。

真正的分界线在于：slash command 的解析、参数提取、权限校验、错误反馈，必须全部委托给 skills CLI 执行，而不是在聊天客户端里写业务逻辑。我见过太多团队在 Slack App 后端直接写 HTTP 请求调用天气 API，结果导致：

• 同一个天气逻辑在 Slack、飞书、企业微信里各写一遍；
• 参数校验规则不一致（Slack 版允许空城市名，飞书版报错）；
• 错误提示五花八门（Slack 显示 “Oops, something went wrong”，飞书显示 “网络请求失败，请重试”）；
• 根本无法做统一的调用量统计和熔断控制。

正确的架构必须是三层解耦：

[UI Layer] Slack/DingTalk/Feishu → [Adapter Layer] Slash Command Router → [Capability Layer] skills CLI

Adapter Layer 只做三件事：

1. 接收原始 slash command 字符串（如/weather --city Beijing --unit fahrenheit）；
2. 提取参数并转换为标准 CLI 调用格式（skills weather --city "Beijing" --unit "fahrenheit"）；
3. 捕获 CLI 的 stdout/stderr/exit code，转换为对应平台的消息格式（成功时发卡片，失败时发红色提示）。

这个 Adapter 层代码量极少，通常 200 行以内，且高度可复用。我们开源的skills-adapter-slack项目就提供了开箱即用的实现，核心逻辑只有：

# adapter/slack.py def handle_slash_command(payload): # 1. 解析 slash command cmd = payload['command'] # '/weather' text = payload['text'] # '--city Beijing --unit fahrenheit' # 2. 构建 CLI 命令 cli_cmd = ['skills'] + cmd[1:].split() + shlex.split(text) # 3. 执行并捕获结果 try: result = subprocess.run( cli_cmd, capture_output=True, text=True, timeout=30 ) if result.returncode == 0: return {"response_type": "in_channel", "text": result.stdout} else: return {"response_type": "ephemeral", "text": f"❌ {result.stderr.strip()}"} except subprocess.TimeoutExpired: return {"response_type": "ephemeral", "text": "⏰ Command timed out"}

这种设计带来了两个关键收益：
第一，UI 无关性。当你要接入新平台（比如某银行自研的 IM 系统），只需写一个新的 Adapter（约 150 行），skills CLI 完全不用动。我们曾用此方式在 3 天内完成某国有大行内部 IM 的 skills 接入，而传统方案预估要 3 周。
第二，能力治理集中化。所有 skills 的调用日志、成功率、P95 延迟、错误分布，都集中在 CLI 的 stdout/stderr 日志中，通过统一日志采集（如 Filebeat → Elasticsearch）即可分析，无需在每个 Adapter 里埋点。

更重要的是，这种解耦让你能轻松实现“能力降级”策略。比如当skills weather因网络问题失败时，Adapter 可以自动 fallback 到本地缓存的昨日天气数据，或者返回预设的兜底文案：“当前无法获取实时天气，为您展示上海近 7 日平均气温：22.3°C”。这种策略必须在 Adapter 层实现，因为只有它知道上下文（用户在哪个频道、是否开启调试模式、是否有历史偏好），而 skills CLI 必须保持纯粹——它只负责“给定输入，返回确定输出”，不承担任何业务决策。

提示：永远不要在 slash command 解析逻辑里写业务规则。比如“如果用户是 VIP，返回更详细天气预报”——这应该由 skills CLI 通过--vip true参数接收，而不是 Adapter 根据用户 ID 去查数据库。Adapter 的职责是翻译，不是决策。

4. API 是 skills 的网络扩展层，不是能力定义层

当热搜词里频繁出现api error: 400、api error: 429、api error: request rejected (429)时，很多人第一反应是“API 配置错了”或“限流太严”。但更深层的问题往往是：你把 API 当成了能力的源头，而实际上它只是 skills 的一种发布形态。

一个设计良好的 agent-skills 系统，API 层应该是一个薄薄的、自动生成的胶水层，而不是手写的业务逻辑层。它的唯一职责是：将 HTTP 请求映射为 CLI 调用，并将 CLI 输出包装为 HTTP 响应。中间不应该有任何业务逻辑、状态管理、缓存策略或权限判断——这些都必须下沉到 skills CLI 本身。

我们采用的方案是：所有 skills CLI 必须支持--format http参数。当传入此参数时，CLI 自动切换为 HTTP 服务器模式，监听本地端口，将自身暴露为 REST API：

$ skills weather --format http --port 8080 ✅ Skills weather server started on http://localhost:8080

此时，它会自动生成 OpenAPI 3.0 spec，并提供标准 REST 端点：

POST /v1/weather HTTP/1.1 Content-Type: application/json { "city": "Shanghai", "unit": "celsius" }

响应：

{ "location": "Shanghai", "temperature": 23.5, "condition": "partly cloudy", "humidity": 68, "timestamp": "2024-06-15T14:22:08Z" }

这个机制的关键在于：API 的契约完全由 CLI 的参数定义驱动，而不是手写 Swagger YAML。CLI 解析器（如 Cobra、Clap）在启动时就能生成完整的参数 Schema，--format http模式只是把这个 Schema 转换成 OpenAPI 文档，并启动一个轻量 HTTP 服务器（我们用的是 Rust 的axum，单二进制 < 5MB）。

这种设计彻底解决了api error: 400 this model's maximum context length is 1048576 tokens这类问题的根源——它不是 API 层的错误，而是 skills CLI 对输入长度缺乏校验。正确做法是在 CLI 的参数定义中声明：

// weather/cmd/root.go var cityFlag = pflag.String("city", "", "City name, max 100 chars") pflag.SetAnnotation("city", "max-length", []string{"100"})

然后在--format http模式下，自动生成的 OpenAPI spec 会包含：

components: schemas: WeatherRequest: type: object properties: city: type: string maxLength: 100

这样，当用户传入超长 city 名时，HTTP 服务器在解析请求体时就会返回标准400 Bad Request，并附带精确错误信息，而不是让错误穿透到下游模型 API 导致400 this model's maximum context length...。

同样，api error: 429（请求过多）也不该由 API 网关硬编码限流规则。而应该在 skills CLI 内置速率控制：

$ skills weather --rate-limit "100/hour" --burst 5

--format http模式会自动将此参数转换为令牌桶算法配置，对每个 IP 或 API Key 实施精准限流，错误响应也是标准429 Too Many Requests，并带上Retry-Afterheader。

这种“CLI 为源，API 为衍生物”的架构，让所有能力治理变得极其简单：

• 调用量统计？看 CLI 的 stdout 日志，每行就是一个调用记录；
• 熔断降级？在 CLI 里实现 circuit breaker，失败时返回预设兜底值；
• A/B 测试？发布两个 CLI 版本（skills-weather-v1、skills-weather-v2），Adapter 层按比例路由；
• 安全审计？所有敏感操作（如skills delete-file）必须要求--confirm参数，CLI 强制校验，HTTP API 自然继承。

注意：不要为了“看起来更专业”而强行上 API 网关（如 Kong、Apigee）。对于 skills 系统，网关的唯一价值是 TLS 终止和 DNS 路由，其他所有功能（鉴权、限流、日志）都应该由 skills CLI 自身实现。网关越薄，系统越可靠。

5. 技能开发不是写函数，而是定义能力契约与执行契约

现在回到最根本的问题：如何真正开发一个 agent-skill？不是写一个 Python 函数，也不是配一个 API endpoint，而是定义两个契约——能力契约（What）和执行契约（How）。

5.1 能力契约：用 machine-readable schema 描述“这个能力是什么”

能力契约回答：这个 skill 能做什么？输入什么？输出什么？失败时返回什么？它必须是机器可读、可验证、可生成文档的。我们强制要求每个 skill 目录下必须存在schema.json：

{ "name": "weather", "description": "Get current weather for a city", "version": "1.2.0", "input": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "City name in English or Chinese" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius" } }, "required": ["city"] }, "output": { "type": "object", "properties": { "location": {"type": "string"}, "temperature": {"type": "number"}, "condition": {"type": "string"}, "humidity": {"type": "integer", "minimum": 0, "maximum": 100}, "timestamp": {"type": "string", "format": "date-time"} }, "required": ["location", "temperature", "condition", "humidity", "timestamp"] }, "errors": [ { "code": "INVALID_CITY_NAME", "message": "City name contains invalid characters or is too long", "http_status": 400 }, { "code": "WEATHER_SERVICE_UNAVAILABLE", "message": "External weather API is down", "http_status": 503 } ] }

这个 schema 的价值远超文档：

• CLI 参数解析器（如 Cobra）可据此自动生成--help输出、参数校验逻辑、类型转换；
• HTTP 服务器可据此生成 OpenAPI spec、请求体校验中间件、错误响应模板；
• 前端 SDK可据此生成 TypeScript 类型定义、表单验证规则、错误提示文案；
• 测试框架可据此生成 fuzz test 用例（自动构造边界值、空值、超长值输入）。

我们团队用此 schema 驱动了一个自动化测试流水线：每天凌晨，脚本读取所有 skills 的schema.json，为每个input字段生成 100 个随机合法值 + 50 个非法值，批量调用 CLI，验证输出是否符合outputschema，错误码是否匹配errors定义。这个测试覆盖了 92% 的参数边界场景，比人工写单元测试效率高 20 倍。

5.2 执行契约：用标准化 runtime 描述“这个能力怎么运行”

执行契约回答：这个 skill 如何被安全、可靠、可观测地执行？它定义了运行时约束，而非业务逻辑。我们要求每个 skill 必须在runtime.yaml中声明：

# weather/runtime.yaml language: go version: "1.21" entrypoint: "./cmd/weather" timeout: 30s memory_limit: 256Mi network: false # 禁用网络访问，除非显式声明 secrets: ["WEATHER_API_KEY"] # 声明所需密钥 env: - name: TZ value: "Asia/Shanghai"

这个文件告诉平台：

• 用 Go 1.21 编译，入口是./cmd/weather；
• 最多运行 30 秒，内存不超过 256MB；
• 默认禁用网络（强制最小权限），若需调用外部 API，必须显式写network: true；
• 运行时注入WEATHER_API_KEY密钥，且该密钥只能被此 skill 访问；
• 设置时区环境变量，确保时间戳格式统一。

执行契约的价值在于：它让 skills 成为可移植的“能力容器”，而不是绑定特定环境的脚本。你可以把weatherskill 的代码、schema.json、runtime.yaml打包成一个.skills文件，上传到任何支持 agent-skills 规范的平台，它都能被正确加载、校验、沙箱运行。这正是superpower skills、awesome claude skills等生态能繁荣的基础——不是靠中心化应用商店，而是靠统一的契约标准。

5.3 开发工作流：从 schema 到可交付二进制的完整闭环

基于以上两个契约，我们的标准开发工作流是：

1. 定义 schema：用 JSON Schema 写schema.json，明确输入输出；
2. 生成骨架：运行skills init weather，自动生成 Go 项目结构、CLI 参数解析、schema 校验中间件；
3. 实现业务逻辑：在cmd/weather/main.go中只写核心逻辑（调用天气 API、解析响应），所有参数校验、错误包装、日志格式由骨架代码处理；
4. 声明 runtime：编写runtime.yaml，定义资源约束和依赖；
5. 本地测试：make test运行 schema 驱动的 fuzz test；make run启动 CLI 测试；make serve启动 HTTP 服务测试；
6. 构建发布：make build生成跨平台二进制（Linux/macOS/Windows）；make package打包为.skills文件；
7. 注册上线：skills register ./dist/weather.skills，平台自动解析 schema 和 runtime，加入能力目录。

这个流程中，开发者 90% 的时间都在写第 3 步的业务逻辑，其他所有工程性工作（CLI、API、测试、打包、部署）全部由工具链自动生成。我们统计过，一个中级工程师开发一个中等复杂度 skill（如 PDF 解析），从零开始到上线，平均耗时 3.2 小时，其中业务逻辑编码仅占 1.1 小时，其余全是标准化操作。

实操心得：永远先写schema.json，再写代码。很多团队倒过来，先写完代码再补 schema，结果 schema 总是滞后、不准确、缺少错误定义。schema 是能力的宪法，代码只是执行者。

6. 生产环境避坑指南：那些只有踩过才懂的硬核经验

在真实生产环境中，agent-skills 系统暴露出的问题，往往和理论设计相差甚远。以下是我在金融、电商、政企三个领域落地中，用真金白银换来的六条血泪经验，每一条都对应一个热搜词里的高频报错。

6.1login failed. check api token or gitlab version. log in via git if the versi—— 不是认证问题，是环境隔离缺失

这个报错看似是 GitLab 登录失败，实则是 skills CLI 在执行时，意外读取了宿主机的~/.gitconfig或~/.netrc，导致认证凭据污染。根本原因在于：skills 运行时没有做环境隔离。

解决方案：所有 skills CLI 必须在runtime.yaml中声明env_isolation: true，并在启动时自动创建干净的临时目录，将HOME、XDG_CONFIG_HOME等环境变量重定向至此：

# skills CLI 启动时自动执行 export HOME=$(mktemp -d) export XDG_CONFIG_HOME=$HOME/.config export XDG_CACHE_HOME=$HOME/.cache

这样，skill 就无法读取宿主机的任何配置，所有凭据必须通过secrets字段显式注入。我们曾因此避免了一次重大事故：某电商客服 skill 因读取了开发者的~/.aws/credentials，误将用户订单数据同步到了开发者的个人 AWS S3 桶。

6.2failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen—— 不是 Docker 问题，是能力粒度失控

这个错误出现在 Windows 上，表面是 Docker Desktop 未启动，实则是某个 skill 试图启动 Docker 容器来运行子任务（如用docker run python:3.9执行一段 Python 脚本）。这违反了 skills 的原子性原则——一个 skill 应该是一个可执行文件，而不是一个容器编排器。

正确做法：将“运行 Python 脚本”本身定义为一个独立 skill（skills python-exec），它内部用os/exec调用系统 Python，而不是依赖 Docker。Docker 是部署基础设施，不是能力抽象层。我们强制规定：skills CLI 的runtime.yaml中禁止出现container_runtime: docker字段，所有需要容器化的场景，必须由平台层统一调度，skill 只负责提供可执行二进制。

6.3api error: request rejected (429) you have exceeded the 5-hour usage quot—— 不是限流太严，是调用链路缺乏熔断

这个 429 错误常被归咎于上游 API 限流，但真实原因是：当skills weather失败时，上层 Agent 服务没有做熔断，而是不断重试，导致短时间内发起数百次请求，触发上游限流。这暴露了 skills 缺乏自我保护契约。

解决方案：在schema.json的errors数组中，必须包含RATE_LIMIT_EXCEEDED错误码，并在 CLI 实现中，当检测到上游返回 429 时，主动返回此错误码，而不是透传。上层 Adapter 层捕获此错误码后，立即启用熔断（如 5 分钟内拒绝所有请求），并返回友好提示：“天气服务暂时繁忙，请稍后再试”。我们用此方式将某金融风控系统的 API 调用失败率从 12% 降至 0.3%。

6.4chatgpt failed to start. unable to locate the codex cli binary or required r—— 不是路径问题，是依赖管理混乱

这个错误指向codex cli binary找不到，根源在于 skills 之间存在隐式依赖。比如skills report-gen依赖skills chatgpt的二进制，但没有在runtime.yaml中声明，导致部署时漏装。

解决方案：所有 skills 间的依赖，必须在runtime.yaml的dependencies字段中显式声明：

# report-gen/runtime.yaml dependencies: - name: "chatgpt" version: ">=1.0.0" type: "cli"

平台在安装report-gen时，会自动检查并安装满足版本要求的chatgptCLI。我们用此机制构建了一个 skills 依赖图谱，可视化展示所有能力的调用关系，极大提升了系统可观测性。

6.5api error: 400 this model's maximum context length is 1048576 tokens—— 不是模型限制，是输入未做预处理

这个错误常被当作模型层问题，实则是 skills CLI 没有对输入做长度截断或摘要。比如skills summarize接收一篇 200 万字的 PDF，直接传给 LLM，必然超限。

解决方案：在schema.json的input定义中，必须声明maxLength或maxTokens，并在 CLI 中实现预处理：

// summarize/main.go func preprocessInput(input string) string { tokens := countTokens(input) if tokens > 1000000 { return summarizeLongText(input) // 用 MapReduce 方式分块摘要 } return input }

我们强制要求：所有可能触发 LLM 上下文限制的 skills，必须在schema.json中声明maxTokens，并在 CLI 中实现对应的预处理逻辑，而不是把问题抛给上游。

6.6vs code gemini cli companion 怎么用—— 不是使用问题，是能力发现机制缺失

这个搜索词反映了一个普遍痛点：用户不知道有哪些 skills 可用，更不知道怎么用。根本原因在于：skills 缺乏统一的发现和探索机制。

解决方案：所有 skills CLI 必须支持--list和--help子命令，且--list输出必须是机器可读的 JSON：

$ skills --list [ { "name": "weather", "version": "1.2.0", "description": "Get current weather for a city", "parameters": ["--city", "--unit"] }, { "name": "pdf-extract", "version": "0.8.3", "description": "Extract text and tables from PDF", "parameters": ["--file", "--pages"] } ]

VS Code 插件、Slack Adapter、前端 SDK 全部通过调用skills --list动态获取能力列表，自动生成 UI 控件和帮助文档。用户在 VS Code 里按Ctrl+Shift+P，输入 “Skills:”，就能看到所有可用 commands，选择后自动插入参数占位符——这才是真正的“companion”。

最后分享一个小技巧：在schema.json的description字段里，用 Markdown 写简短教程。CLI 的--help会自动渲染为富文本，用户skills weather --help就能看到带示例的完整用法，无需跳转文档网站。