前言¶

对接第三方服务时，开发者最常见的动作是：翻 API 文档、拼 curl、复制 Bearer Token、在 Postman 里点来点去。任务做完，这段调用链路往往就躺在终端历史里，下次还要从头找。

如果用的是 AI 编程助手，问题更明显——Agent 能写代码，却缺少一个稳定、可组合的「命令层」去反复调用同一个服务。每次让 Agent 查 Slack 消息、拉 CI 日志、搜 Sentry 事件，都可能重新发明一遍 HTTP 请求。

cli-creator 就是 OpenAI 在 skills 仓库 中维护的精选 Skill，专门解决这类问题：从 API 文档、OpenAPI 规范、SDK 说明、curl 示例，甚至浏览器 DevTools 抓到的请求，脚手架生成一套可安装、可组合、输出稳定 JSON 的 CLI，并配套一份 Companion Skill，让后续 Agent 线程能按命令名直接调用。

这是什么¶

cli-creator 的定位很清晰：为 Codex 等 AI Agent 打造持久的命令行工具，而不是在当前仓库里写一次性脚本。

官方 SKILL.md 的描述是：从 API 文档、OpenAPI、现有 curl 示例、SDK、Web 应用、管理后台或本地脚本，构建可组合的 CLI。生成的工具应满足：

• 安装到系统 PATH，在任意工作目录都能用命令名调用；
• 暴露 discovery / resolve / read / write 等可组合子命令；
• 支持 --json 输出机器可读结果；
• 内置 auth 与 config 管理；
• 完成后配一份 Companion Skill，教未来 Agent 如何安全使用。

来源归属：OpenAI，位于 openai/skills 仓库的 skills/.curated/cli-creator 目录。该仓库 README 标注已 deprecated，官方建议新项目参考 OpenAI Plugins 仓库 与 Build plugins 文档；但 cli-creator 的 SKILL.md 与参考文档仍可正常获取和使用。

核心功能与亮点¶

1. 多种输入源，一条生成链路¶

Skill 支持的来源包括：

• REST API 文档、OpenAPI JSON；
• 官方 SDK 文档；
• 现成的 curl 示例、Shell 历史；
• 浏览器里的 Web 应用（配合 DevTools 网络请求）；
• 团队内部脚本或管理工具。

你只需明确三件事：工具名（如 slack-cli）、数据来源、首批要做的读写任务（如 list drafts、download failed job logs）。

2. 按环境选运行时，默认 Rust¶

脚手架前会检查本机工具链：

command -v cargo rustc node pnpm npm python3 uv || true

选择原则（官方默认）：

不选增加摩擦的语言；若首选语言未安装，需征得用户同意再装，或退而求其次。

3. 为 Agent 设计的 Command Contract¶

cli-creator 要求 CLI 遵循可组合命令面，而非只有一个 request 万能入口。核心形状如下：

tool-name --help
tool-name --json doctor
tool-name init ...
tool-name --json accounts list
tool-name --json channels resolve --name codex
tool-name --json messages search "exact phrase"
tool-name --json logs download <build-url> --failed --out ./logs
tool-name --json request get /v2/me

设计要点：

• doctor --json：检查配置、auth、版本、端点可达性；即使缺少 token 也应给出可读诊断，而非直接崩溃。
• Discovery：列出 workspace、project、channel、queue 等顶层容器。
• Resolve：把名称、URL、slug 解析成稳定 ID，避免重复 broad search。
• Read：精确读取对象或分页列表，支持 --limit、cursor、offset。
• Write：每个写操作独立命名（create / update / delete / upload / retry 等），支持 --dry-run 或 draft；禁止把写操作藏在 fix、debug 这类模糊命令里。
• --json：stdout 只输出 JSON，进度与诊断走 stderr；错误结构文档化，且不得泄露凭证。
• Raw escape hatch：如 request get /v2/me，作为补洞手段，不是主接口。

详细模式见官方参考文件 agent-cli-patterns.md。

4. Auth 与 Config 的「无聊但正确」顺序¶

优先级（官方规定）：

1. 环境变量（如 GITHUB_TOKEN）；
2. 用户配置 ~/.<tool>/config.toml 等文档化路径；
3. --api-key 等 flag 仅用于一次性测试（避免进 shell history）。

doctor --json 只报告 token 是否可用、来源类别（flag / env / config / missing），绝不打印完整 token。从 DevTools curl 逆向内部 API 时，须先整理脱敏端点笔记，禁止提交 cookie、Bearer 或生产 payload。

5. Companion Skill：让杠杆效应延续¶

CLI 装好后，cli-creator 要求再写一份 Companion Skill（可用 $skill-creator），教未来 Agent：

• 如何确认命令已安装；
• 第一条该跑什么（通常是 doctor）；
• auth 怎么配、discovery 怎么找 ID；
• 安全读路径 vs 需用户确认的写路径；
• 三条可直接复制的命令示例。

API 细节留在 CLI README；Skill 只保留顺序、安全边界、示例——这正是 Agent Skills 生态里「一次构建、多次复用」的典型模式。

安装与启用¶

在 Codex 中¶

OpenAI 官方文档说明：.system 目录下的 Skill 会随 Codex 自动安装；curated 类 Skill 可通过 $skill-installer 按名称安装：

$skill-installer cli-creator

安装后重启 Codex 以加载新 Skill。也可指定 GitHub 目录 URL：

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/cli-creator

参考：Using skills in Codex

在 Cursor 中¶

Cursor 使用项目或用户目录下的 .cursor/skills/ 加载 Skill。将官方目录中的 SKILL.md 及 references/ 复制到本地即可，例如：

git clone --depth 1 https://github.com/openai/skills.git /tmp/openai-skills
mkdir -p ~/.cursor/skills/cli-creator/references
cp /tmp/openai-skills/skills/.curated/cli-creator/SKILL.md ~/.cursor/skills/cli-creator/
cp /tmp/openai-skills/skills/.curated/cli-creator/references/* ~/.cursor/skills/cli-creator/references/

也可放在项目级 .cursor/skills/cli-creator/，仅当前仓库生效。

通用 skills CLI（skills.sh 收录）¶

第三方技能目录 skills.sh 提供的安装方式为：

npx skills add https://github.com/openai/skills --skill cli-creator

具体行为取决于你使用的 Agent 宿主工具，安装后按该工具文档启用即可。

Claude Code 等兼容 SKILL.md 的工具¶

Agent Skills 遵循开放标准（agentskills.io），SKILL.md 格式通用。将 skill 目录放到对应工具的 skills 路径（如 Claude Code 的 ~/.claude/skills/）即可触发。

典型用法示例¶

启用 cli-creator 后，在对话中描述目标即可，无需手写脚手架。官方建议的开场信息：

工具名：buildkite-logs
来源：https://buildkite.com/docs/apis/rest-api
首批任务：
  - list pipelines
  - download failed job logs for a build URL
安装名：buildkite-logs

Agent 会先检查命令名是否冲突：

command -v buildkite-logs || true

选定 Rust 后，典型构建流程（官方 Build Workflow）：

1. 阅读文档，盘点资源、auth、分页、危险写操作；
2. 在对话中 sketch 命令列表；
3. 脚手架 + README；
4. 实现 doctor、discovery、resolve、read、raw escape hatch，以及可选的 dry-run 写路径；
5. make install-local 装到 ~/.local/bin；
6. 在 /tmp 或其他目录 smoke test：command -v tool-name、--help、--json doctor；
7. 跑 format、typecheck、单元测试与至少一次 fixture 或只读 API 调用。

Rust 默认技术栈：clap、reqwest、serde、toml、anyhow；安装目标示例：

make install-local   # 构建 release 并复制到 ~/.local/bin

生成 CLI 后，Companion Skill 中的使用顺序通常类似：

buildkite-logs --json doctor
buildkite-logs --json pipelines list
buildkite-logs --json logs download <build-url> --failed --out ./logs

适用场景与注意事项¶

适合谁、什么场景：

• 团队或个人需要反复调用同一 SaaS / 内部 API，且希望 Agent 也能稳定调用；
• 已有 curl 或脚本，想升级为带 auth、分页、JSON 输出的正式 CLI；
• 正在搭建 Agent 工具链，希望「CLI + Companion Skill」形成可复用能力层。

不适合的场景：

• 当前仓库里写几十行脚本就能搞定的一次性任务——官方明确说应直接写脚本，不要上 cli-creator；
• 只需要 Postman 点一次、不会再用的接口；
• 无法提供任何文档、OpenAPI、curl 或 DevTools 证据的来源（截图只能辅助 UI 词汇，不能单独当 API 依据）。

其他注意点：

• 写操作默认需用户确认；live write 测试前应先 draft / dry-run；
• raw 非 GET/HEAD 请求视为真实写操作，未经明确要求不应执行；
• 媒体上传等多阶段流程须分步测试：创建 upload → 传字节 → 轮询状态 → 关联 ID；
• 日志类 CLI 应把「确定性片段提取」与「模型解读」分开，优先输出文件名、行号、短 excerpt。

小结¶

cli-creator 把「重复的手工 API 调用」变成「Agent 可按名调用的命令行工具」，是 Agent Skills 里杠杆效应很突出的一类：一次生成 CLI，再配 Companion Skill，后续每个 Codex / Cursor / Claude Code 线程都能复用同一套 discovery → resolve → read → write 流程。

若你手头正好有一份 OpenAPI、一段 curl，或团队里用了半年的 Shell 脚本，不妨把它交给 cli-creator，看能否沉淀成 PATH 上的正式命令。

官方 Skill 地址：https://github.com/openai/skills/tree/main/skills/.curated/cli-creator