包含98条规则的设计规范，用于构建AI代理可以安全使用的CLI工具。涵盖结构化JSON输出、错误处理、输入契约、安全护栏、退出代码和代理自我描述。
技能概述
ai-native-cli 技能用于构建AI原生CLI工具的综合设计规范。它定义了跨三个认证级别（Agent-Friendly、Agent-Ready、Agent-Native）的98条规则，具有优先级要求（P0/P1/P2）。该规范涵盖结构化JSON输出、错误处理、输入契约、安全护栏、退出代码、自我描述以及通过内置问题系统的反馈循环。
下载地址：agentic-awesome-skills/skills/ai-native-cli at main · sickn33/agentic-awesome-skills · GitHub
触发条件
- 构建AI代理将调用的新CLI工具
- 改造现有CLI使其对代理友好
- 为自动化管道设计命令行界面
- 审计CLI工具对代理安全标准的合规性
核心理念
- 代理优先：默认输出是JSON；人类友好通过
--human选择加入 - 代理不受信任：在与公共API相同的级别验证所有输入
- 失败关闭：当验证逻辑本身出错时，默认拒绝
- 可验证：每条规则的编写都可以自动检查
层模型
此规范使用两个正交轴：
- 层回答推出范围：
core、recommended、ecosystem - 优先级回答严重性：
P0、P1、P2
认证级别
| 级别 | 要求 | 描述 |
|---|---|---|
| Agent-Friendly | 所有core规则通过 | CLI是稳定的、可调用的API |
| Agent-Ready | 所有core + recommended规则通过 | CLI是自我描述的、命名良好的、管道友好的 |
| Agent-Native | 所有层通过 | 完整的代理原生集成 |
工作原理
步骤1：输出模式
默认是代理模式（JSON）。显式标志切换：
$ mycli list # 默认 = JSON输出（代理模式） $ mycli list --human # 人类友好：彩色、表格、格式化 $ mycli list --agent # 显式代理模式（如果需要，覆盖配置）
步骤2：agent/目录约定
每个CLI工具必须在其项目根目录下有一个agent/目录。这是工具的身份和行为契约。
agent/ brief.md # 一段话：我是谁，我能做什么 rules/ # 行为约束（自动注册） trigger.md # 代理何时应使用此工具 workflow.md # 逐步使用流程 writeback.md # 如何写回反馈 skills/ # 扩展能力（自动注册） getting-started.md
步骤3：四个级别的自我描述
- --brief（名片，注入代理配置）
- 每个命令响应（始终在线上下文：数据+规则+技能+问题）
- --help（完整自我描述：简介+命令+规则+技能+问题）
- skills <name>（按需深入特定技能）
Level 1：Agent-Friendly（core - 20条规则）
目标：CLI是稳定的、可调用的API。代理可以调用、解析和处理错误。
输出
- [P0] O1：默认输出是JSON。无需
--json标志 - [P0] O2：JSON必须通过
jq .验证 - [P0] O3：JSON模式在相同版本内不得更改
错误
- [P0] E1：错误→stderr的
{"error":true, "code":"...", "message":"...", "suggestion":"..."} - [P0] E4：错误具有机器可读的
code（例如MISSING_REQUIRED） - [P0] E5：错误具有人类可读的
message - [P0] E7：出错时，永不进入交互模式——立即退出
- [P0] E8：错误代码是API契约——版本间不得重命名
退出代码
- [P0] X3：参数/用法错误必须退出2
- [P0] X9：失败必须退出非零——永不退出0然后在stdout中报告错误
可组合性
- [P0] C1：stdout仅用于数据
- [P0] C2：日志、进度、警告仅进入stderr
输入
- [P1] I4：缺少必需参数→结构化错误，永不交互式提示
- [P1] I5：类型不匹配→退出2 + 结构化错误
安全
- [P1] S1：破坏性操作需要
--yes确认 - [P1] S4：拒绝
../../路径遍历、控制字符
护栏
- [P1] G1：未知标志被拒绝并退出2
- [P1] G2：检测参数中的API密钥/令牌模式，拒绝执行
- [P1] G3：拒绝敏感文件路径（*.env、*.key、*.pem）
- [P1] G8：拒绝参数中的shell元字符（; | && $()）
最佳实践
- 默认使用JSON输出，人类友好格式通过标志选择
- 所有错误输出到stderr，使用结构化JSON格式
- 实现全面的输入验证和安全护栏
- 使用一致的退出代码约定
- 提供agent/目录进行自我描述
- 支持四个级别的自我描述
技能元数据
- 风险等级：safe
- 来源：https://github.com/ChaosRealmsAI/agent-cli-spec
