Guide · Agent skill

How to use the Codex CLI Automation agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The codex agent skill teaches an AI agent how to run OpenAI's Codex command-line coding tool without a person at the keyboard. It is aimed at developers and teams who want to hand a repository task to Codex from a script, CI/CD job, Docker container or remote server. After following this guide you will know what the skill does, how to install it, how to ask for it in plain language, and which safety limits to apply.

Codex CLI AutomationXiaomiMiMo/MiMo-Code · MIT Download the skill

Quick start

1Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
2Install and sign in to Codex. Make sure the codex binary is on your PATH and authentication is set, such as CODEX_API_KEY or codex login.
3Ask for the skill by name. Request a task and name Codex or codex so the skill loads, for example to fix failing tests in a given repository.
4Choose the sandbox mode. Use read-only for analysis and workspace-write with approvals set to never for autonomous code changes.
5Capture output. Use --json and --output-last-message for harness output, or --output-schema for structured results.
6Review the result. Check the final message, changed files, validation and blockers before accepting the changes.

What the codex skill makes the agent do

Agent skills are folders of instructions and optional files that an AI agent loads when a task matches them. This skill covers running Codex in non-interactive, headless environments. The agent builds a codex exec command, picks a sandbox and approval mode, writes a prompt that avoids interactive questions, and reads back results as JSON events or a final message.

Builds codex exec commands for Bash or PowerShell
Chooses sandbox and approval modes such as read-only or workspace-write
Writes prompts that avoid questions the run cannot answer
Produces JSONL event streams and structured final results
Covers session resume, stdin prompts, and use in Docker, Kubernetes and CI/CD

Install the codex skill

Download the ZIP from this page and unzip it into one of two locations. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside the project. The skill folder contains SKILL.md, references/recipes.md and references/windows.md.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into .claude/skills/ in your repository
Claude apps: upload under Settings → Capabilities → Skills

The skill does not work without the codex binary. Before any command, the agent checks that codex is available and, if it is missing, stops and gives install or authentication guidance. The skill requires the binary to be installed and on your PATH, plus Codex authentication such as a CODEX_API_KEY environment variable.

For a local interactive login, the source uses codex login. On a headless machine with device-code login enabled, it uses codex login --device-auth.

codex binary installed and on PATH
Authentication, such as CODEX_API_KEY set in the environment
Optional: a JSON Schema file if you want structured output

codex login

Trigger the skill with natural requests

The skill loads only when you explicitly authorize it or name Codex or codex in your request. Say what you want done and name the repository. The agent then picks the right mode.

Good requests state the task, the repository, and what output you want back.

"Use codex to fix the failing tests in /srv/app and report what you changed."
"Use the codex skill to analyze this repo for risks. Do not modify files."
"Run Codex in a read-only mode on this checkout and return the findings as JSON."

Run a typical task and read the result

For ordinary unattended code changes, the source recommends workspace-write sandboxing with approvals set to never, and the repository passed with -C. The task is the positional prompt argument. Do not use -p for the prompt, because -p selects a profile.

For CI and harnesses, add --json to get events on stdout and --output-last-message to save the final answer to a file.

Use -C to set the repository path
Use --sandbox read-only for analysis only
Use --sandbox workspace-write --ask-for-approval never for implementation
Use --json plus --output-last-message for harness output

codex exec \
  -C /path/to/repo \
  --sandbox workspace-write \
  --ask-for-approval never \
  "<TASK>"

Get structured results and resume sessions

To make results machine-readable, pass a JSON Schema with --output-schema. A useful schema usually includes status, summary, changed_files, validation, assumptions and blockers. To continue earlier work, use codex exec resume --last for the most recent session in the current working directory, or resume a specific session ID. Use --ephemeral when you do not want the run persisted.

status: success, partial or failed
changed_files: repository-relative paths
assumptions and blockers recorded in the final output

codex exec resume --last "Continue the previous task and fix remaining issues."

Safety notes: scripts, network and credentials

This skill runs scripts and uses the network. Codex calls OpenAI services, so the run needs network access and a valid key. Treat CODEX_API_KEY as a secret and inject it only into the single codex exec process where possible. Never commit or print ~/.codex/auth.json.

Do not use --yolo on a normal developer machine or on a runner that holds secrets, SSH keys, cloud credentials or a Docker socket. The source says --yolo disables Codex approvals and sandboxing, so it should only run inside an externally hardened, disposable environment.

Avoid broad job-level API key variables in jobs that run repository-controlled code
Never use --yolo on a developer machine or a secret-holding runner
On Windows, pick one environment per task: native PowerShell or WSL2

What people use it for

Fixing failing tests in a repository from a CI/CD pipeline
Running read-only repository analysis that reports risks without modifying files
Running Codex as a worker inside Docker, Kubernetes or a remote server in an agent pipeline
Piping test output into Codex so it can analyze failures and propose fixes
Resuming a previous Codex session to finish remaining issues

Frequently asked questions

How do I install the codex agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What does the codex skill require?

It requires the OpenAI Codex CLI (codex binary) installed and on PATH, plus Codex authentication such as a CODEX_API_KEY environment variable. A JSON Schema file is optional for structured output. On Windows, use PowerShell or WSL2.

Is the codex skill free?

The skill is released under the MIT licence. This source does not state pricing for Codex itself, so check OpenAI's terms for any costs related to using Codex.

Why does the agent say the codex binary is missing?

The skill checks for the codex binary before any command. If it is not installed or not on PATH, the agent stops and gives install or authentication guidance instead of running commands.

Is it safe to use --yolo?

Only inside an externally hardened, disposable environment. The source says --yolo disables Codex approvals and sandboxing, so do not use it on a normal developer machine or a runner that holds secrets, SSH keys, cloud credentials or a Docker socket.

How does this compare to using Codex interactively?

The skill targets the non-interactive codex exec command, so runs do not wait for a human to answer questions. For interactive use, you would use the codex terminal interface directly, which this skill tells the agent not to use.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers and teams who want Codex to run unattended in scripts, CI/CD, containers or remote workers, and who can set up authentication and a safe sandbox. It is not a good fit for anyone who has not installed the codex binary or who wants to run unrestricted --yolo mode on a machine holding secrets.

Download the skill