cli-for-agent 是一套用于设计或审查命令行界面(CLI)的规范,目标是让 AI 编码智能体能够可靠地运行这些 CLI。其核心判断是:面向人类设计的 CLI 会阻碍智能体,包括交互式提示、运行前倾泻大量文档、帮助文本缺少可直接复制粘贴的示例。技能建议采用可在无头(headless)环境运行、可在管道中组合的模式。
主要能力与设计要点:
-
非交互优先。每个输入都应能通过参数或参数值表达,不应要求方向键、菜单或定时提示。参数缺失时才回退到交互模式,而不是反过来。示例:差的做法是 mycli deploy 后弹出“Which environment?”菜单;好的做法是 mycli deploy --env staging。
-
按需发现,避免倾泻上下文。智能体应能逐级发现子命令:先运行 mycli,再运行 mycli deploy --help。不要在每次运行时打印整本手册,让每个子命令拥有自己的文档,使未使用的命令不占用上下文。
-
可用的 --help。每个子命令都要有 --help,并且每个 --help 都要包含带真实调用的 Examples 段落。示例对模式匹配的作用大于散文描述。示例中会列出选项(如 --env、--tag、--force)及其说明,并给出多条可直接执行的调用示例。
-
stdin、参数与管道。在合理场景接受 stdin,例如通过管道导入配置;避免奇怪的位置参数顺序,避免在缺少值时回退到交互提示。支持链式调用,例如把构建命令的输出作为标签传给部署命令。
-
快速失败与可操作错误。缺少必需参数时立即退出,给出清晰信息和正确示例调用,而不是挂起。示例错误信息会说明未指定镜像标签,并给出可执行命令与可用标签的查询方式。
-
幂等性。智能体经常重试,同一成功命令运行两次应当安全(无操作或明确提示“已完成”),不产生重复副作用。
-
破坏性操作。提供 --dry-run 或等价能力,让智能体在提交前预览计划;提供 --yes/--force 跳过确认,同时为人类保留安全默认值。
-
可预测的结构。全局采用一致模式,例如“资源+动词”:若存在 service list,则 deploy list、config list 也应遵循相同形状。
-
成功输出。成功时返回对机器有用的数据:ID、URL、时长等。纯文本即可,避免只依赖装饰性输出。
使用方式:该技能可用于新 CLI 的设计评审,或对现有 CLI 做审查。审查时检查:非交互路径、分层帮助、--help 中的示例、stdin/管道支持、带调用示例的错误信息、幂等性、dry-run、确认绕过参数、一致的命令结构、结构化成功输出。
该内容改编自 cursor/plugins 中的 SKILL.md(MIT,© Cursor),按 superskills 的导入技能规则内置,此处改动不跟踪上游。适用场景为需要让 AI 编码智能体自动化调用、组合和重试 CLI 的开发与运维工作流。限制方面:资料未提供具体支持的编程语言、CLI 框架、安装方式或运行环境要求,这些信息暂未提供。