create-cli

设计命令行界面参数和用户体验：参数、标志、子命令、 帮助文本、输出格式、错误消息、退出代码、提示、配置/环境 优先级和安全/空运行行为。在设计 CLI 规范时使用 （实施之前）或重构现有 CLI 的表面积 一致性、可组合性和可发现性。

# Create CLI

Design CLI surface area (syntax + behavior), human-first, script-friendly.

## Do This First

- Read `agent-scripts/skills/create-cli/references/cli-guidelines.md` and apply it as the default rubric.
- Upstream/full guidelines: https://clig.dev/ (propose changes: https://github.com/cli-guidelines/cli-guidelines)
- Ask only the minimum clarifying questions needed to lock the interface.

## Clarify (fast)

Ask, then proceed with best-guess defaults if user is unsure:

- Command name + one-sentence purpose.
- Primary user: humans, scripts, or both.
- Input sources: args vs stdin; files vs URLs; secrets (never via flags).
- Output contract: human text, `--json`, `--plain`, exit codes.
- Interactivity: prompts allowed? need `--no-input`? confirmations for destructive ops?
- Config model: flags/env/config-file; precedence; XDG vs repo-local.
- Platform/runtime constraints: macOS/Linux/Windows; single binary vs runtime.

## Deliverables (what to output)

When designing a CLI, produce a compact spec the user can implement:

- Command tree + USAGE synopsis.
- Args/flags table (types, defaults, required/optional, examples).
- Subcommand semantics (what each does; idempotence; state changes).
- Output rules: stdout vs stderr; TTY detection; `--json`/`--plain`; `--quiet`/`--verbose`.
- Error + exit code map (top failure modes).
- Safety rules: `--dry-run`, confirmations, `--force`, `--no-input`.
- Config/env rules + precedence (flags > env > project config > user config > system).
- Shell completion story (if relevant): install/discoverability; generation command or bundled scripts.
- 5–10 example invocations (common flows; include piped/stdin examples).

## Default Conventions (unless user says otherwise)

- `-h/--help` always shows help and ignores other args.
- `--version` prints version to stdout.
- Primary data to stdout; diagnostics/errors to stderr.
- Add `--json` for machine output; consider `--plain` for stable line-based text.
- Prompts only when stdin is a TTY; `--no-input` disables prompts.
- Destructive operations: interactive confirmation + non-interactive requires `--force` or explicit `--confirm=...`.
- Respect `NO_COLOR`, `TERM=dumb`; provide `--no-color`.
- Handle Ctrl-C: exit fast; bounded cleanup; be crash-only when possible.

## Templates (copy into your answer)

### CLI spec skeleton

Fill these sections, drop anything irrelevant:

1. **Name**: `mycmd`
2. **One-liner**: `...`
3. **USAGE**:
   - `mycmd [global flags] <subcommand> [args]`
4. **Subcommands**:
   - `mycmd init ...`
   - `mycmd run ...`
5. **Global flags**:
   - `-h, --help`
   - `--version`
   - `-q, --quiet` / `-v, --verbose` (define exactly)
   - `--json` / `--plain` (if applicable)
6. **I/O contract**:
   - stdout:
   - stderr:
7. **Exit codes**:
   - `0` success
   - `1` generic failure
   - `2` invalid usage (parse/validation)
   - (add command-specific codes only when actually useful)
8. **Env/config**:
   - env vars:
   - config file path + precedence:
9. **Examples**:
   - …

## Notes

- Prefer recommending a parsing library (language-specific) only when asked; otherwise keep this skill language-agnostic.
- If the request is “design parameters”, do not drift into implementation.

---

## 中文说明

# Create CLI

设计 CLI 的表面积（语法 + 行为），以人为先，对脚本友好。

## 首先执行

- 阅读 `agent-scripts/skills/create-cli/references/cli-guidelines.md`，并将其作为默认评分标准应用。
- 上游/完整指南：https://clig.dev/ （提交修改建议：https://github.com/cli-guidelines/cli-guidelines）
- 只问锁定接口所需的最少澄清问题。

## 澄清（快速）

先询问，如果用户不确定，则采用最佳猜测的默认值继续：

- 命令名称 + 一句话用途。
- 主要用户：人类、脚本，还是两者皆有。
- 输入来源：args 还是 stdin；文件还是 URL；密钥（绝不通过 flags 传递）。
- 输出约定：人类可读文本、`--json`、`--plain`、退出代码。
- 交互性：是否允许提示？是否需要 `--no-input`？破坏性操作是否需要确认？
- 配置模型：flags/env/配置文件；优先级；XDG 还是仓库本地。
- 平台/运行时约束：macOS/Linux/Windows；单一二进制还是依赖运行时。

## 交付物（应输出什么）

设计 CLI 时，产出一份用户可以实现的紧凑规范：

- 命令树 + USAGE 概要。
- 参数/标志表（类型、默认值、必填/可选、示例）。
- 子命令语义（各自的作用；幂等性；状态变更）。
- 输出规则：stdout 还是 stderr；TTY 检测；`--json`/`--plain`；`--quiet`/`--verbose`。
- 错误 + 退出代码映射（主要失败模式）。
- 安全规则：`--dry-run`、确认、`--force`、`--no-input`。
- 配置/环境规则 + 优先级（flags > env > 项目配置 > 用户配置 > 系统）。
- Shell 补全方案（如相关）：安装/可发现性；生成命令或捆绑脚本。
- 5–10 个示例调用（常见流程；包含管道/stdin 示例）。

## 默认约定（除非用户另有说明）

- `-h/--help` 始终显示帮助并忽略其他参数。
- `--version` 将版本打印到 stdout。
- 主要数据输出到 stdout；诊断/错误输出到 stderr。
- 为机器输出添加 `--json`；考虑用 `--plain` 提供稳定的基于行的文本。
- 仅当 stdin 是 TTY 时才提示；`--no-input` 禁用提示。
- 破坏性操作：交互式确认 + 非交互式则要求 `--force` 或显式的 `--confirm=...`。
- 尊重 `NO_COLOR`、`TERM=dumb`；提供 `--no-color`。
- 处理 Ctrl-C：快速退出；有界清理；尽可能做到 crash-only。

## 模板（复制到你的回答中）

### CLI 规范骨架

填写这些部分，删除任何不相关的内容：

1. **Name**: `mycmd`
2. **One-liner**: `...`
3. **USAGE**:
   - `mycmd [global flags] <subcommand> [args]`
4. **Subcommands**:
   - `mycmd init ...`
   - `mycmd run ...`
5. **Global flags**:
   - `-h, --help`
   - `--version`
   - `-q, --quiet` / `-v, --verbose` (define exactly)
   - `--json` / `--plain` (if applicable)
6. **I/O contract**:
   - stdout:
   - stderr:
7. **Exit codes**:
   - `0` success
   - `1` generic failure
   - `2` invalid usage (parse/validation)
   - (add command-specific codes only when actually useful)
8. **Env/config**:
   - env vars:
   - config file path + precedence:
9. **Examples**:
   - …

## 注意事项

- 只有在被要求时才推荐解析库（特定于语言）；否则保持本技能与语言无关。
- 如果请求是“设计参数”，不要偏离到实现层面。