让 Codex 能调用你的命令行工具

当 Codex 总是要访问同一个 API、日志来源、导出文件、本地数据库或团队脚本时，不要每次都把说明重新贴进对话。更好的做法是给它一个可组合的命令行工具，让它

当 Codex 总是要访问同一个 API、日志来源、导出文件、本地数据库或团队脚本时，不要每次都把说明重新贴进对话。更好的做法是给它一个可组合的命令行工具，让它能在任意目录运行、缩小结果、下载文件，并和 git、gh、rg、测试命令以及项目脚本配合使用。

这一类工作通常还应该配一个 companion skill。CLI 负责把外部系统变成稳定命令；skill 负责告诉以后进入同类任务的 Codex：什么时候先用这个 CLI、先跑哪条命令、输出如何保持小、下载文件放哪里、哪些写操作必须先确认。

官方页面：https://developers.openai.com/codex/use-cases/agent-friendly-clis

适合什么任务

适合把重复的读取、搜索、下载、导出、草稿、上传、轮询或安全写入动作，封装成 Codex 能稳定调用的命令。

场景	CLI 应该让 Codex 做什么
CI 日志藏在构建页面后面	接收 build URL，把失败 job 的日志下载到 `./logs`，返回文件路径和关键片段
客服工单以周度 CSV 或 JSON 导出	索引最新导出，按客户或关键词搜索，再用稳定 ID 读取单条工单
API 响应太大，放不进上下文	默认只列出需要字段，按 ID 读取完整对象，并把完整响应导出到文件
Slack 导出包含很长线程	用 `--limit` 搜索，再读取单个 thread，返回附近上下文而不是整包归档
团队脚本把四个步骤揉在一起	拆成 setup、discovery、download、draft、upload、poll、live write 等独立命令
plugin 能找到记录，但 Codex 需要文件	plugin 留在对话里找对象；CLI 负责下载附件、trace、report、video 或 log bundle，并返回路径

使用的能力

能力	用法	链接
`$cli-creator`	设计 command surface，构建 CLI，加入 setup/auth 检查，把命令安装到 `PATH`，并从另一个目录验证	https://github.com/openai/skills/tree/main/skills/.curated/cli-creator
`$skill-creator`	创建 companion skill，让后续 Codex 任务知道应该先跑哪些 CLI 命令，哪些写操作需要确认	https://github.com/openai/skills/tree/main/skills/.system/skill-creator

起始提示词

可以把下面的模板发给 Codex，再按你的场景替换方括号内容：

请使用 $cli-creator 创建一个 Codex 可以调用的 CLI，并在同一个线程里使用 $skill-creator 创建配套 skill。

可学习的材料：[docs URL、OpenAPI spec、已脱敏的 curl 命令、现有脚本路径、日志目录、CSV 或 JSON 导出、SQLite 数据库路径，或者粘贴的 --help 输出]。

CLI 首先要支持的任务：[从 build URL 下载失败 CI 日志、搜索客服工单并按 ID 读取单条记录、查询 admin API、读取本地数据库，或运行现有脚本里的一个步骤]。

可选写入任务：[创建评论草稿、上传媒体、重试失败任务；如果暂时只读，也请明确只读]。

命令名称：[cli-name；如果不确定，请推荐一个]。

写代码前，先展示你建议的 command surface；只询问会阻塞构建的缺失信息。

关键点是最后一句：先让 Codex 展示命令设计，只问真正会阻塞构建的信息。不要一上来就让它直接写代码。

给 Codex 的输入要具体

Codex 需要可学习的材料。可以提供：

文档 URL 或 OpenAPI spec。
已脱敏的 curl 命令。
导出的 CSV、JSON、SQLite 数据库或日志目录。
现有脚本路径。
你希望模仿的 --help 输出，比如 gh、kubectl 或团队内部工具。

如果命令需要认证，告诉 Codex 应该支持的环境变量名、配置文件路径或登录流程。密钥由你自己写入 shell 或配置文件，不要贴到对话里。CLI 的 setup check 应该在缺少认证时给出清楚错误，而不是运行到一半才失败。

构建前先看命令面

好的 CLI 不是一个大而全的脚本，而是一组可以组合的小命令。让 Codex 先给出 command surface，例如：

tool setup-check
tool search --query "..."
tool read --id ...
tool download --id ... --out ./logs
tool draft-comment --id ...
tool submit --draft-id ...

读取、搜索、下载、草稿和真正写入要分开。这样 Codex 后续执行时更容易保持边界，也方便你在写操作前检查。

验证方式

不要让 Codex 只跑 cargo run、python path/to/script.py 或未安装包命令就结束。CLI 的验收应该模拟未来 agent 的真实使用方式：

安装命令，确保它在 PATH 上。
从另一个 repo 或临时目录运行。
检查 setup/auth 缺失时的报错是否清楚。
搜索类命令默认输出要小。
大响应要支持导出文件，而不是把巨大 JSON 直接塞进对话。
写操作要通过 companion skill 说明确认边界。

如果 Codex 返回巨大 JSON，让它缩小默认响应，并补一个 full payload export。若它漏掉审批边界，先更新 companion skill，再把这个 CLI 用到其他线程。

后续复用

以后再需要同一个 CLI，不要重新粘贴文档，直接调用对应 skill。

例如你把 CI 日志处理做成了 $ci-logs，后续就可以在新线程里说：

请使用 $ci-logs 检查这个 build URL 里的 failed jobs：...

跑顺一次普通任务后，再让 Codex 把这类调用变成 automation。