Preface¶
When integrating with third-party services, the most common actions developers take are: flipping through API documentation, crafting curl commands, copying Bearer Tokens, and clicking around in Postman. Once the task is done, this call chain often lingers in the terminal history, and developers have to search from scratch next time they need it.
The problem is even more obvious when using AI programming assistants: while Agents can write code, they lack a stable, composable “command layer” to repeatedly call the same service. Every time you ask an Agent to check Slack messages, pull CI logs, or search Sentry events, it may reinvent the HTTP request wheel.
cli-creator is a curated Skill maintained by OpenAI in the skills repository, specifically designed to solve this type of problem: scaffolding a set of installable, composable, stable JSON-outputting CLIs from API documentation, OpenAPI specs, SDK instructions, curl examples, or even requests captured in browser DevTools, along with a Companion Skill so that subsequent Agent threads can call it directly by command name.
What It Is¶
The positioning of cli-creator is very clear: Create persistent command-line tools for AI Agents like Codex, rather than writing one-off scripts in the current repository.
The official SKILL.md description states: Build composable CLIs from API documentation, OpenAPI, existing curl examples, SDKs, web applications, admin dashboards, or local scripts. The generated tools should meet the following requirements:
- Be installed to the system PATH so they can be called by command name in any working directory
- Expose composable subcommands like discovery / resolve / read / write
- Support --json for machine-readable output
- Have built-in auth and config management
- Come with a Companion Skill to teach future Agents how to use it safely
Source attribution: OpenAI, located in the skills/.curated/cli-creator directory of the openai/skills repository. The repository’s README marks it as deprecated, and the official recommendation for new projects is to refer to the OpenAI Plugins repository and Build plugins documentation; however, the SKILL.md and reference documents for cli-creator are still available and usable.
Core Features and Highlights¶
1. Multiple Input Sources, One Single Generation Pipeline¶
The Skill supports the following sources:
- REST API documentation, OpenAPI JSON
- Official SDK documentation
- Ready-made curl examples, shell history
- Web applications in browsers (paired with DevTools network requests)
- Internal team scripts or management tools
You only need to clarify three things: tool name (e.g. slack-cli), data source, and the first batch of read/write tasks (e.g. list drafts, download failed job logs).
2. Choose Runtime Based on Environment, Rust is Default¶
The scaffolding will check the local toolchain first:
command -v cargo rustc node pnpm npm python3 uv || true
The selection principles (official default) are as follows:
| Runtime | Applicable Scenarios |
|--------|----------|
| Rust (default) | Requires fast single-file binaries, strong parameter parsing, JSON processing, suitable for persistent CLIs called across repositories |
| TypeScript/Node | Official SDKs, browser automation libraries, or existing Node toolchains are the best path |
| Python | Data analysis, SQLite/CSV/JSON local processing, Notebook workflows |
Do not choose languages that add friction; if the preferred language is not installed, you must obtain user consent before installing it, or fall back to an alternative.
3. Command Contract Designed for Agents¶
cli-creator requires the CLI to follow a composable command surface, rather than having only a single request universal entry point. The core command structure is as follows:
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
Key design points:
- doctor --json: Checks configuration, auth, version, and endpoint reachability; should provide readable diagnostics even when tokens are missing, rather than crashing directly.
- Discovery: Lists top-level containers like workspaces, projects, channels, queues, etc.
- Resolve: Resolves names, URLs, slugs into stable IDs to avoid repeated broad searches.
- Read: Accurately reads objects or paginated lists, supports --limit, cursor, offset.
- Write: Each write operation is independently named (create / update / delete / upload / retry, etc.), supports --dry-run or draft mode; hiding write operations in vague commands like fix or debug is prohibited.
- --json: Only outputs JSON to stdout, progress and diagnostics go to stderr; error structures are documented, and credentials must not be leaked.
- Raw escape hatch: Such as request get /v2/me, as a fallback measure, not the main interface.
For detailed patterns, see the official reference document agent-cli-patterns.md.
4. “Boring but Correct” Auth and Config Priority¶
Official priority order:
1. Environment variables (e.g. GITHUB_TOKEN)
2. User configuration files in documented paths like ~/.<tool>/config.toml
3. Flags like --api-key only for one-time testing (to avoid being saved in shell history)
doctor --json only reports whether the token is available and its source category (flag / env / config / missing), never prints the full token. When reverse-engineering internal APIs from DevTools curl requests, you must first organize anonymized endpoint notes, and never commit cookies, Bearer tokens, or production payloads.
5. Companion Skill: Extend the Leverage Effect¶
After the CLI is installed, cli-creator requires you to write a Companion Skill (available via $skill-creator) to teach future Agents:
- How to confirm the command is installed
- What the first command to run should be (usually doctor)
- How to configure auth and find IDs via discovery
- Safe read paths vs. write paths that require user confirmation
- Three directly copyable command examples
API details stay in the CLI README; the Skill only retains order, security boundaries, and examples — this is the typical pattern of “build once, reuse multiple times” in the Agent Skills ecosystem.
Installation and Activation¶
In Codex¶
According to OpenAI’s official documentation: Skills in the .system directory will be automatically installed with Codex; curated skills can be installed by name via $skill-installer:
$skill-installer cli-creator
Restart Codex after installation to load the new Skill. You can also specify a GitHub directory URL:
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/cli-creator
Reference: Using skills in Codex
In Cursor¶
Cursor loads Skills from the .cursor/skills/ directory under the project or user directory. Copy the SKILL.md and references/ from the official directory to your local machine, for example:
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/
You can also place it in the project-level .cursor/skills/cli-creator/ directory to make it only effective for the current repository.
Universal Skills CLI (Included in skills.sh)¶
The third-party skill directory skills.sh provides the following installation method:
npx skills add https://github.com/openai/skills --skill cli-creator
The specific behavior depends on the Agent host tool you are using, and you can enable it according to that tool’s documentation after installation.
Tools Compatible with SKILL.md like Claude Code¶
Agent Skills follow an open standard (agentskills.io), and the SKILL.md format is universal. Place the skill directory in the corresponding tool’s skills path (such as Claude Code’s ~/.claude/skills/) to trigger loading.
Typical Usage Examples¶
After enabling cli-creator, you can describe your goal in the conversation without writing scaffolding by hand. The official recommended opening message is:
Tool name: buildkite-logs
Source: https://buildkite.com/docs/apis/rest-api
First batch of tasks:
- list pipelines
- download failed job logs for a build URL
Installation name: buildkite-logs
The Agent will first check for command name conflicts:
command -v buildkite-logs || true
After selecting Rust, the typical build workflow (official Build Workflow) is as follows:
1. Read the documentation, inventory resources, auth, pagination, and dangerous write operations
2. Sketch the command list in the conversation
3. Scaffold and generate README
4. Implement doctor, discovery, resolve, read, raw escape hatch, and optional dry-run write paths
5. Run make install-local to install to ~/.local/bin
6. Perform smoke tests in /tmp or another directory: command -v tool-name, --help, --json doctor
7. Run formatting, type checking, unit tests, and at least one fixture or read-only API call
The default Rust tech stack includes: clap, reqwest, serde, toml, anyhow; example installation target:
make install-local # Build release version and copy to ~/.local/bin
After generating the CLI, the usage sequence in the Companion Skill usually looks like this:
buildkite-logs --json doctor
buildkite-logs --json pipelines list
buildkite-logs --json logs download <build-url> --failed --out ./logs
Applicable Scenarios and Notes¶
Who and what scenarios it is suitable for:
- Teams or individuals who need to repeatedly call the same SaaS/internal API and want Agents to be able to call it stably
- Already have curl commands or scripts and want to upgrade them to formal CLIs with auth, pagination, and JSON output
- Building an Agent toolchain and hoping to form a reusable capability layer with “CLI + Companion Skill”
Scenarios that are not suitable for:
- One-off tasks that can be handled with tens of lines of scripts in the current repository — the official clearly states that you should write scripts directly instead of using cli-creator
- Interfaces that only need to be clicked once in Postman and will not be used again
- Sources that cannot provide any documentation, OpenAPI, curl, or DevTools evidence (screenshots can only assist with UI vocabulary and cannot be used as the sole API basis)
Other notes:
- Write operations require user confirmation by default; perform a draft/dry-run before live write testing
- Raw non-GET/HEAD requests are considered real write operations and should not be executed without explicit requirements
- Multi-stage processes like media uploads must be tested step by step: create upload → transfer bytes → poll status → associate ID
- Logging CLIs should separate “deterministic fragment extraction” from “model interpretation”, and prioritize outputting file names, line numbers, and short excerpts.
Summary¶
cli-creator turns “repeated manual API calls” into “command-line tools that Agents can call by name”, which is a type of Skill with prominent leverage effect in the Agent Skills ecosystem: generate the CLI once, pair it with a Companion Skill, and every subsequent Codex / Cursor / Claude Code thread can reuse the same discovery → resolve → read → write process.
If you happen to have an OpenAPI spec, a curl command, or a Shell script that your team has been using for half a year, you might as well hand it over to cli-creator to see if it can be polished into a formal command on your PATH.
Official Skill address: https://github.com/openai/skills/tree/main/skills/.curated/cli-creator