让 Codex 能调用你的命令行工具
把重复访问 API、日志、数据库或团队脚本的动作封装成 agent-friendly CLI，并配套 skill 固化调用方法。
当 Codex 总要访问同一个 API、日志来源、导出文件、本地数据库或团队脚本时，不要每次把说明粘进 prompt。更稳的做法是做一个 agent-friendly CLI，让它能搜索、读取、下载、导出，并保持默认输出足够小。
CLI 负责把外部系统变成稳定命令；skill 负责告诉 Codex 什么时候用这个 CLI、怎么缩小输出、哪些写操作必须先确认。
Agent-friendly CLIs
查看 OpenAI 对 Codex 可调用 CLI 的官方建议。
Skills
把 CLI 调用方法沉淀成可复用 skill。
MCP tools
对比 CLI、MCP、browser 和 skill 的职责。
什么时候该做 CLI
适合：
- CI 日志在构建页面后面，需要按 build URL 下载。
- API 响应很大，需要搜索和按 ID 读取。
- 客服工单、Slack 导出、日志包需要索引。
- 团队脚本太大，需要拆成可组合命令。
- Codex 需要把附件、trace、report、video、log bundle 下载到文件。
不适合：
- 一次性任务。
- 只需要读本地 repo。
- 还没想清楚认证和权限。
- 写操作不可审查。
判断标准
一个动作重复出现三次以上，就应该考虑 CLI。判断时不要先问“能不能写脚本”，先问这四件事：
- Codex 是否经常需要从同一个外部系统取数据。
- 这个系统是否有稳定 ID、分页、搜索、下载或导出概念。
- 默认输出能否控制在小范围内，完整数据能否写到文件。
- 写操作是否能拆成
draft和submit两步。
只要其中三项成立，CLI 通常比把长说明塞进 prompt 更稳。CLI 让外部系统有了稳定命令面，skill 再把调用时机和禁区告诉 Codex。
命令面应该小而可组合
flowchart LR
Setup["setup-check"] --> Search["search"]
Search --> Read["read --id"]
Read --> Download["download --out"]
Read --> Draft["draft"]
Draft --> Submit["submit"]推荐把动作拆开：
setup-check：检查认证和环境。search：小结果搜索。read：按稳定 ID 读取单条。download：把大内容导出到文件。draft：准备写入内容。submit：真正写入，需要明确确认。
不要把搜索、下载、写入都塞进一个大命令。动作越小，Codex 越容易保持边界。
推荐 command surface
team-tool setup-check
team-tool search --query "..." --limit 10
team-tool read --id "..."
team-tool download --id "..." --out ./logs
team-tool draft --id "..." --message-file ./draft.md
team-tool submit --draft-id "..." --confirm设计重点：
setup-check先失败清楚，避免任务中途才发现缺 token。search只返回摘要和稳定 ID，不返回整段大 JSON。read按 ID 取精确对象，适合放进上下文。download把大附件、日志、trace 写入文件，再返回路径。draft生成可审查内容。submit是唯一 live write，必须显式确认。
给 Codex 的构建提示词
请创建一个 Codex 可以调用的 CLI，并配套创建一个 skill。
材料：
{文档 URL / OpenAPI spec / 已脱敏 curl / 现有脚本 / 日志目录 / CSV / JSON / SQLite}
第一版只支持：
{只读搜索、按 ID 读取、下载日志到 ./logs}
写入边界：
{暂不写入，或只创建草稿，submit 前必须确认}
要求：
先展示 command surface，不要直接写代码。
只询问会阻塞构建的信息。关键是先看 command surface。CLI 设计错了，后面实现再完整也不好用。
输入材料要真实
可以给：
- 文档 URL。
- OpenAPI spec。
- 已脱敏
curl。 - 示例 JSON / CSV。
- SQLite 数据库。
- 现有脚本。
- 你希望模仿的
--help。
不要给：
- 真实 token。
- 生产账号。
- 未脱敏客户数据。
- 无法验证的口头描述。
认证信息应走环境变量、配置文件或 secret store。CLI 缺认证时要清楚报错。
验收方式
一个 CLI 做完后，不要只在源码目录里跑一次。
验收：
- 安装到
PATH。 - 换一个临时目录运行。
- 缺少认证时错误清楚。
- 搜索默认输出小。
- 大响应能导出到文件。
- 写操作不会直接执行，或有明确确认。
- companion skill 能说明何时使用和何时禁止。
如果 Codex 默认输出巨大 JSON，让它改成摘要 + 文件路径。
后续复用
跑顺后，把 CLI 使用方式写进 skill。以后新任务只需要说：
请使用 $ci-logs 检查这个 build URL 的失败 job。稳定之后再考虑 automation。先有 CLI 和 skill，再谈定时或批量执行。
Skill 要记录什么
companion skill 不是 CLI README 的复读。它应该告诉未来的 Codex 任务：
- 什么时候必须先跑
setup-check。 - 搜索默认
--limit用多少。 - 大输出应该写到哪个目录。
- 哪些命令只读，哪些命令会写入。
submit、上传、删除、重试这类动作需要用户明确确认。- CLI 失败时先修 CLI 还是回退到别的工具。
如果 skill 没有写审批边界，CLI 以后会被误用。尤其是内部工具，一定要把 live write 和 destructive action 写成硬边界。