optimize-agentic-cli 是一个专注于让命令行工具（CLI）能够被智能体（agent）或大语言模型（LLM）可靠驱动、无需人工介入的技能。它把 CLI 与智能体之间的接口视为一份契约，要求 CLI 提供纯机器可读的标准输出、语义化退出码、非交互式默认行为、带重试指引的结构化错误，以及针对可修复产物的迭代反馈循环。
用途
当用户进行仅针对 CLI 的智能体可用性改造时，应触发该技能。典型场景包括：要求“让我的 CLI 对智能体友好”或“为 LLM 使用审计 CLI”；智能体持续无法解析 CLI 结果；标准输出混入进度文本或加载动画；所有失败都以退出码 1 结束且没有结构化错误体；命令因等待交互式提示而挂起；工作流需要校验、拒绝、修复并重新提交生成产物；新 CLI 从第一天就需要面向智能体的约束；帮助文本作为智能体调用方的契约不可靠。
该技能不适用于：界面形态选择（CLI 与 MCP 与混合方式），应先完成界面形态决策，确定使用 CLI 后才适用本技能；MCP 服务器审计、模式、传输、认证或上下文预算，应转到 optimize-agentic-mcp 进行审计与架构，或使用 build-mcp-server-sdk-v1、build-mcp-server-sdk-v2、build-mcp-use-server 进行实现，以及 test-by-mcpc-cli 进行实时 MCP 验证；存在厂商技能时的厂商 CLI 操作，应改用 use-railway 或 use-linear-cli；与 CLI 智能体契约无关的通用脚本编写。
主要能力与核心检查
技能要求在推荐新功能前，先验证五项核心审计检查：存在 --json 或等价选项，且标准输出为纯机器输出，没有进度、横幅或散文；日志、加载动画、横幅和进度输出到标准错误；退出码能区分成功、用法错误、认证失败、未找到、冲突、校验失败以及瞬时/可重试失败，而不是全部为 0 或 1；无头运行不会在没有显式 --no-input/--yes 路径或清晰非交互错误的情况下阻塞；错误响应包含稳定的错误码和 retryable 布尔值（或等价指引）。当命令必须输出非 JSON 产物（如补丁、差异、查询、提示、翻译）时，标准输出应保持一种规范的产物格式，状态信息放到标准错误或附属文件中，绝不能把散文混入数据通道。
技能还给出了以智能体视角而非人类 UX 视角的严重性分级标准：严重（智能体无法安全解析、继续或避免意外副作用）、高（智能体会执行但很可能失败、错误重试或阻塞）、中（智能体只能通过额外探测或脆弱假设完成）、低（仅为打磨或一致性）。以及最小输出信封，力求所有命令使用统一的 JSON 信封，成功形如 {"ok": true, "result": {}, "error": null, "schema_version": "v1"}，失败则包含 error 对象，含 class、code、message、retryable、suggestion 等字段。标准输出是数据通道，标准错误是操作者通道，退出码是语义类别，三者必须一致。
使用方式与审计流程
修复现有 CLI 时，技能要求按顺序进行，避免浪费精力：1）纯 JSON 输出与 stdout/stderr 分离；2）结构化错误与语义退出码；3）非交互标志与安全默认值（--no-input、--yes、--dry-run）；4）为智能体可能需要修复产物的命令提供迭代反馈循环；5）完善发现能力，包括帮助文本、示例、文档化的退出码与输出字段；6）为长时间运行操作提供异步/JSONL/作业式流程。
审计工作流要求：先检查顶层帮助与相关子命令，使用 scripts/audit-cli-help.sh（先读 scripts/audit-cli-help.md）捕获标准标志、示例和缺失能力；查找机器可读输出标志，如 --json、--output json、--quiet、--fields、--jq；在安全的只读命令上测试 stdout/stderr 分离；跨成功、用法、认证、未找到、校验、冲突和瞬时路径对退出码分类；在易出现提示的命令上探测非交互行为；检查破坏性流程的安全性：--dry-run、--yes、--force、显式确认语义；验证帮助文档包含真实示例、输出字段和退出码；若审计此前快照过的 CLI，使用 scripts/diff-cli-help.sh（先读 scripts/diff-cli-help.md）进行差异比较，发现命令/标志漂移。
迭代修复循环
当智能体生成产物、CLI 进行校验、智能体必须在拒绝后修复时，使用该模式：输入产物 -> CLI 校验 -> 结构化差异/错误 -> 智能体修复 -> 重试 -> 接受 -> 最终确定。典型适用场景：翻译/本地化批次、带校验门的代码生成、清单/配置/迁移生成、批量导入或同步。每一轮迭代必须告诉智能体：当前阶段；已接受/已拒绝/部分接受；失败内容，含标识符或位置；失败是否可重试；下一步要运行的命令（next_action.command）；已完成进度与剩余工作。一次性读取/列表/获取/状态命令不需要此模式，使用更简单的信封即可。
设计规则与输出契约
设计规则包括：所有命令使用统一的信封形状；stdout 为数据，stderr 为操作者，退出码为语义类别；命令名称和字段类型跨版本保持一致；破坏性流程显式提供 --yes、--force、--dry-run；--help 记录示例、输出字段和退出码；对于可修复工作流，返回足够结构让智能体无需人工解释即可修复并重试。
交付形态按任务三选一：审计报告，包含按审计维度的评分卡、按严重性排序的发现、命令证据（确切的安全命令与观察到的 stdout/stderr/退出码）、对智能体的意义、建议修复、验证命令；重构后的 CLI 契约，包含提议的命令语法、标志与非交互行为、stdout/stderr 规则、JSON 信封与流格式、退出码映射、面向现有用户和脚本的迁移说明；迭代修复循环设计，包含阶段与命令族、产物通道、校验响应形状、重试预算、next_action.command、最终确定标准。
本地范例与参考资料
本地范例包括 use-linear-cli（具备 JSON 全量输出、--dry-run、--id-only、非分页标志、退出码契约、批量变更门控的强智能体就绪 CLI）和 use-railway（具备已安装帮助快照、上游与本地区分、刷新脚本、版本漂移路由的漂移感知 CLI）。
参考资料按问题路由：JSON 信封、模式、错误字段、流分离、退出码分类，读 references/output-contracts.md；重试、幂等性、异步作业、批处理、超时、分页、速率限制，读 references/execution-patterns.md；帮助、认证、配置、标志、环境检测，读 references/discovery-and-auth.md；迭代修复循环 CLI 设计与案例研究，读 references/iterative-cli.md；CLI 与 MCP 与混合方式（界面仍存疑时），读 references/mcp-vs-cli-decision.md；可运行代码示例（Go、Python、Node、Rust、Shell）和真实审计，读 references/examples.md；调用 CLI 的智能体或服务的模式，读 references/agent-integration.md。这些是规范位置，不应在此重复其内容。
打包脚本与完成标准
打包脚本为只读发现支持，不能视为智能体就绪的证明：scripts/audit-cli-help.sh（先读 scripts/audit-cli-help.md）用于检查顶层和子命令帮助中的标准标志、示例、退出码文档和缺失能力；scripts/diff-cli-help.sh（先读 scripts/diff-cli-help.md）用于比较捕获的帮助快照，找出命令/标志的新增、移除和可能的破坏性变更。这些脚本只覆盖可发现性和漂移，不能替代手工运行的 stdout/stderr、退出码、非交互和破坏性流程检查。
完成标准：在五项核心审计检查通过之前，不应称 CLI 已具备智能体就绪；JSON 信封在不同命令间足够稳定，可以针对其编写脚本；--help 记录了命令契约（示例、输出字段、退出码）；非交互式运行能够在没有人工按键的情况下确定性地成功或失败；任何迭代工作流返回足够结构化反馈让智能体无需人工解释即可修复。
限制
本技能不负责 CLI 与 MCP 之间的界面形态选择、MCP 服务器审计与实现、厂商 CLI 操作（当存在厂商技能时）以及与智能体契约无关的通用脚本编写。原始资料未提供具体的安装命令、收费信息、价格或平台支持范围，这些事实暂未提供。