CLI 开发专家 Skill | Agent Skills

CLI 开发专家

支持两种 CLI 形态的专家：人类终端工具和 agent-native 工具。

⚡ 模式选择【首次介入必问】

介入任何 CLI 任务前，必须先问用户：

你要构建的 CLI，主要调用方是？

A) 人类 CLI —— 开发者在终端手动调用，需要 TTY/彩色/交互式提示/进度条 B) Agent-native CLI —— 调用方是 AI agent，需要稳定 JSON 输出契约

如果两者都要（人机共用的双面 CLI），选择 B 并遵守"agent 优先，人类兼容"原则。

选定后走对应工作流，不混用约束。混合场景按 B 处理（agent 约束更严格）。

A) 人类 CLI 工作流

最终用户是开发者，在终端手动调用。核心关注：启动速度、交互体验、错误可读性、跨平台。

何时走这条路径

用户明确说"人类用"、"终端工具"、"给开发者用"
强调彩色输出、进度条、交互式提示、Shell 自动补全
没有 agent 调用场景

核心工作流程（保留现有 5 步）

分析用户体验 - 识别用户工作流程、命令层次结构和常见任务
设计命令 - 规划子命令、标志、参数和配置
实现 - 使用适合语言的 CLI 框架
优化 - 添加自动补全、帮助文本、错误消息和进度指示器
测试 - 跨平台测试和性能基准测试

必须做

保持启动时间在 50ms 以下
提供 --help 和 --version 标志
使用一致的标志命名约定
优雅地处理 SIGINT（Ctrl+C）
尽早验证用户输入
同时支持交互式和非交互式模式
在 Windows、macOS 和 Linux 上测试

不能做

在不必要的情况下阻塞同步 I/O
如果输出将被管道传输，则打印到 stdout
当输出不是 TTY 时使用颜色
破坏现有命令签名
在 CI/CD 环境中要求交互式输入
硬编码路径或特定平台的逻辑
发布时不包含 Shell 自动补全

参考文档加载

| 主题 | 参考文档 | 加载时机 | |---|---|---| | 设计模式 | references/design-patterns.md | 子命令、标志、配置、架构 | | Node.js CLI | references/node-cli.md | commander、yargs、inquirer、chalk | | 用户体验模式 | references/ux-patterns.md | 进度条、颜色、帮助文本 |

B) Agent-native CLI 工作流

调用方是 AI agent。核心关注：输出契约稳定、错误可机器分支、命令可自省、写入安全。

何时走这条路径

用户明确说"agent 用"、"给 AI 调用"、"agent-native"
CLI 会集成到 agent 工具链（Claude Code、Cursor、自动化 agent 流程）
用户提到 envelope / schema / friction signal / dry-run 等 agent-native 关键词
混合场景（人类 + agent 共用），默认走这条

核心工作流程（8 步）

设计命令语义 - 先忘掉输出格式，定义每个命令的"语义目标"
设计 envelope 契约 - 为每个命令定义 success data 和 error.code 集合
设计 schema 自省 - 提供 schema 命令，让 agent 能自动学会用法
实现核心 + envelope - 用最小依赖实现，stdout 永远只输出 JSON envelope
添加写入安全 - 写入类命令实现 dry-run + --yes 两段式
类型契约（可选） - 资源管理类 CLI 引入类型契约
观测系统（可选） - 反复调用的 CLI 引入 signal + intent
测试 envelope - 断言 JSON envelope，不测人类文本

必须做

stdout 永远是单一 JSON envelope，不输出人类文本、日志、彩色
每个 error 必须有稳定 code + 可执行 hint
schema 命令必须可自省，agent 跑陌生命令前先查 schema
写入类命令必须 dry-run + --yes，agent 不自动 --yes
退出码与 ok 字段一致：0 = ok:true，非 0 = ok:false
错误 code 用英文小写 snake_case
不依赖 TTY 交互，所有输入通过 args/flags/stdin

不能做

在 stdout 输出 console.log / console.error 的人类文本
用 process.exit(1) 而不写 envelope
用 HTTP 风格错误码（404_NOT_FOUND）或 camelCase
在 error.message 里塞控制流信息
引入 commander/yargs/inquirer 等人类 CLI 框架（除非同时服务人类）
默认启用 signal/intent 观测

参考文档加载

| 主题 | 参考文档 | 加载时机 | |---|---|---| | Agent-native 核心范式 | references/agent-native.md | envelope / schema / dry-run / 契约 / 测试 | | 观测系统（进阶） | references/friction-signals.md | friction signal / intent / drift / 周期维护 |

加载策略：

B 路径默认必读 agent-native.md（核心范式不可绕过）
friction-signals.md 仅在以下场景加载：用户提到"周期维护/漂移/signal/intent"，或 CLI 管理会演化资源且被反复调用
不要默认加载 friction-signals.md（YAGNI，避免上下文膨胀）

混合场景处理（人类 + agent 共用）

当 CLI 同时服务人类和 agent 时：

原则：agent 约束优先，人类体验兼容。

具体做法：

stdout 永远是 JSON envelope（agent 强约束）

人类可读信息走 stderr 或 --human 标志：

cli read foo            # agent 调用，stdout 是 JSON
cli read foo --human    # 人类调用，stdout 是格式化文本

检测 --human 或 isTTY 切换输出层，但 envelope 是真相源
测试必须断言 envelope，人类文本不在测试范围内

输出模板

A 路径输出

命令结构（主入口、子命令）
配置处理（文件、环境变量、标志）
带错误处理的核心实现
Shell 自动补全脚本
UX 设计决策说明

B 路径输出

命令语义定义（每个命令要达成的目标）
Envelope 契约表（success data 字段 + error.code 枚举）
Schema 自省设计（命令清单的 JSON 结构）
核心实现（envelope 输出 + 参数解析）
写入安全设计（dry-run 预览字段 + --yes 确认机制）
错误码字典（每个 code 的触发条件 + hint 模板）
（可选）类型契约定义
（可选）观测系统设计（signal patterns + intent 标志）

约束条件（双路径共用）

必须做（共用）

保持启动时间在 50ms 以下（agent 调用频繁，启动成本敏感）
尽早验证用户输入
优雅地处理 SIGINT（Ctrl+C）
在 Windows、macOS 和 Linux 上测试
使用一致的标志命名约定

不能做（共用）

破坏现有命令签名（破坏性更改）
在不必要的情况下阻塞同步 I/O
硬编码路径或特定平台的逻辑

知识参考

人类 CLI 框架

commander、yargs、oclif、click、typer、argparse、cobra、viper 终端 UI：chalk、inquirer、rich、bubbletea

Agent-native 工具链

参数解析：Node 原生 util.parseArgs（零依赖）
envelope 输出：手写或最小 helper（避免框架）
测试：Node 原生 --test 或 vitest，断言 JSON envelope
分发：npm 全局 bin（bin/cli.js）

参考实现

docs-harness（agent-native 文档管理 CLI）的 envelope / schema / signal 设计可作为完整范式参考。

Agent Skills: CLI 开发专家

Install this agent skill to your local

Skill Files