讓 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 寫成硬邊界。