Create Cli

核心定位

create-cli 是一项面向 CLI 设计的前置规范技能，聚焦于命令行界面的「表面区域」设计——即用户实际接触的语法、行为与交互契约，而非底层实现。其核心目标是让人类用户感到直观、让脚本调用可预测。

显著优点

1. 权威来源背书
默认引用 clig.dev 作为上游规范，该文档由业界实践者维护，代表了现代 CLI 设计的共识标准。内置的 cli-guidelines.md 参考文件降低了认知启动成本。

2. 完整的交付物框架
从命令树、参数表、退出码映射，到配置优先级（flags > env > 项目配置 > 用户配置 > 系统配置）、shell 补全策略，形成可直接落地的规格文档，避免设计与实现脱节。

3. 安全与鲁棒性内置

• 破坏性操作强制交互确认，非交互场景需显式 --force 或 --confirm
• 敏感信息禁止通过 flags 传递（防范 ps 泄漏）
• 默认支持 --dry-run、--no-input、NO_COLOR 等生产环境刚需
• Ctrl-C 处理建议「快速退出 + 有界清理 + crash-only」

4. 人机双模式友好
TTY 检测决定交互行为；--json/--plain 区分机器/人类输出；stdout/stderr 职责分离明确。

潜在局限

实现层留白
文档明确声明「语言无关」，不绑定具体解析库（如 Python 的 argparse/Click、Rust 的 clap）。这对于需要即插即用代码片段的用户可能不够直接，需自行桥接规范到实现。

场景覆盖偏向通用工具
对特定领域 CLI（如 kubectl 式的资源操作、交互式 TUI 工具）的专项模式提及较少，深度定制需额外推导。

适合人群

• 正在从 0 设计 CLI 的开发者（避免后期大规模重构接口）
• 需要统一团队/组织内多 CLI 工具风格的架构师
• 开源项目维护者（追求与 Unix 哲学、现代生态的一致性）
• 安全审计人员（检查 CLI 设计中的敏感信息处理、破坏性操作防护）

常规风险

| 风险点 | 说明 |

|--------|------|

| 规范被架空 | 若团队未建立「设计 → 代码审查」闭环，交付物可能沦为文档装饰 |

| 过度设计 | 对简单脚本强行套用完整规范（如复杂的配置层级、shell 补全）增加维护负担 |

| 跨平台假设 | 默认提及 macOS/Linux/Windows，但对 Windows 特有的路径处理、权限模型细节指引有限 |

| 退出码冲突 | 自定义退出码（如 3-125）需与 shell 保留值、CI 系统预期协调，文档仅给框架未给映射建议 |

核心用法

create-cli 是一个纯文档型 Skill，专注于指导用户设计命令行界面（CLI）的「表面区域」——即语法与行为规范。它不涉及具体代码实现，而是提供一套完整的接口设计框架，涵盖参数（arguments）、标志（flags）、子命令（subcommands）、帮助文本、输出格式、错误消息、退出码、交互提示、配置/环境变量优先级，以及安全/试运行行为。

典型工作流：
1. 明确命令名称、目标用户（人类/脚本/两者）、输入来源、输出契约
2. 快速澄清最小必要问题后，输出紧凑的 CLI 规格文档
3. 交付物包括：命令树结构、参数/标志表格、子命令语义、输入输出规则、退出码映射、安全规则（--dry-run、确认机制）、配置/环境优先级、Shell 补全方案、5-10 个示例调用

显著优点

• 权威性高：默认引用 clig.dev（CLI Guidelines）作为设计基准，这是业界广泛认可的 CLI 设计标准
• 人本优先：强调「human-first, script-friendly」，平衡人类可读性与机器可解析性
• 安全内置：强制要求破坏性操作需交互确认，提供 --no-input、--force、--dry-run 等安全机制
• 语言无关：不绑定特定解析库，规格可被任何语言实现
• 模板完备：提供可直接填充的 CLI spec skeleton，降低设计决策负担
• 平台友好：考虑 TTY 检测、NO_COLOR、跨平台差异（macOS/Linux/Windows）

潜在局限

• 纯设计阶段：明确声明「If the request is 'design parameters', do not drift into implementation」，不提供实现代码
• 无运行时反馈：作为 Markdown Skill，无法验证设计的 CLI 在实际使用中的可用性
• 模板偏向通用：特定领域（如容器工具、云 CLI）可能需要额外定制
• 社区规范依赖：部分约定（如退出码 2 表示用法错误）虽成惯例但非绝对标准

适合人群

• 正在设计新 CLI 工具的开发者或技术产品经理
• 需要统一团队 CLI 接口风格的 Tech Lead
• 重构遗留 CLI 以提升一致性和可组合性的工程师
• 学习 CLI 设计最佳实践的开发者

常规风险

• 设计偏差风险：若未充分澄清「Primary user: humans, scripts, or both」，可能导致输出格式偏向某一方
• 过度设计：丰富的配置层级（flags > env > project config > user config > system）可能对小工具过重
• 确认疲劳：若对所有操作强制确认，可能损害脚本友好性；需合理界定「破坏性操作」范围

该 Skill 本身零安全风险（纯 Markdown），但设计的 CLI 若未遵循其安全建议（如将 secrets 传入 flags），则会产生实际安全隐患。