前言¶

對接第三方服務時，開發者最常見的動作是：翻 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