Getting Started with OpenAI Codex CLI Skills — Setup, Install & Best Picks

Learn how to install and use agent skills with OpenAI's Codex CLI — from initial setup to discovering the best community-built skills that make your terminal-based coding agent dramatically more productive.

What Is Codex CLI?

Codex CLI is OpenAI's open-source command-line coding agent. It connects to OpenAI models (GPT-4.1 and o3 by default) and operates directly in your terminal — reading your codebase, writing code, running commands, and iterating on changes with your approval.

Unlike browser-based coding assistants, Codex CLI works where developers already live: the terminal. It understands your project structure by scanning files, and you can teach it project-specific workflows through a file called AGENTS.md.

Key characteristics:

Open source — MIT licensed, fully inspectable on GitHub
Terminal native — runs as a CLI tool, no browser or IDE plugin needed
Multi-model — supports GPT-4.1, o3, o4-mini, and other OpenAI models
Sandboxed execution — runs commands in an isolated environment for safety
Skill-aware — reads AGENTS.md files to learn project-specific instructions

If you have used Claude Code or plan to try Gemini CLI, Codex CLI is the OpenAI equivalent — and skills work across all three with minor format adjustments.

Install Codex CLI

Prerequisites

Node.js 22 or later
An OpenAI API key with access to GPT-4.1 or o3

Step 1: Install via npm

npm install -g @openai/codex

Step 2: Set your API key

export OPENAI_API_KEY="sk-..."

Add this to your shell profile (~/.zshrc or ~/.bashrc) so it persists across sessions:

echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

Step 3: Verify the installation

codex --version

Step 4: Run your first command

Navigate to any project directory and run:

codex "explain the structure of this project"

Codex will scan your files and provide a detailed overview. From here, you can ask it to write code, fix bugs, refactor, or run any workflow you describe.

Approval Modes

Codex CLI offers three modes that control how much autonomy the agent has:

suggest (default) — Codex reads files and suggests changes, but you approve every edit and command
auto-edit — Codex can edit files automatically, but still asks before running commands
full-auto — Codex reads, writes, and executes commands without asking (use with caution in sandboxed environments)

codex --approval-mode full-auto "add unit tests for the auth module"

How Codex CLI Reads Skills

Codex CLI uses a file called AGENTS.md to discover project-specific instructions. This is its equivalent of Claude Code's .claude/commands/ directory or custom instructions files.

The AGENTS.md Format

Place an AGENTS.md file in your project root (or any subdirectory — Codex discovers them recursively). The file uses standard Markdown:

# AGENTS.md

## Project Overview
This is a Nuxt 3 + Go-Zero full-stack application.
The frontend is in /frontend-nuxt and the backend is in /backend-go.

## Code Style
- Use TypeScript strict mode
- Prefer composition API over options API
- All API responses follow the {code, data, message} format

## Testing
- Run `npm test` before committing
- Use Vitest for unit tests
- E2E tests live in /tests/e2e/

## Deployment
- Never modify production configs directly
- Use `bash deploy.sh frontend` for frontend deploys
- Backend deploys require a PR review first

Auto-Discovery Rules

Codex CLI automatically discovers AGENTS.md files through a hierarchy:

Root AGENTS.md — applies to the entire project
Subdirectory AGENTS.md — applies only within that directory and its children
Multiple files merge — if both exist, Codex combines them (subdirectory instructions take priority for conflicts)

This means you can have a top-level AGENTS.md for global conventions and a frontend/AGENTS.md with frontend-specific rules.

What to Put in AGENTS.md

The best AGENTS.md files cover:

Project architecture — what lives where, key directories
Code conventions — naming, formatting, patterns to follow
Common commands — how to build, test, deploy, lint
Gotchas — things the agent should never do, edge cases to watch for
Workflow instructions — step-by-step playbooks for recurring tasks

Think of it as onboarding documentation for an AI teammate. The more specific you are, the better Codex performs.

Install Skills from TokRepo

TokRepo is a community registry for agent skills. Skills published on TokRepo work with Claude Code, Codex CLI, and Gemini CLI — you just need to place them in the right location.

Method 1: TokRepo CLI (Recommended)

The fastest way to install a skill:

npx tokrepo install <asset-uuid>

This downloads the skill file and places it in your project's skill directory. For Codex CLI, you may want to consolidate instructions into your AGENTS.md or place skill files where Codex can reference them.

Method 2: Manual Copy

Visit the skill page on TokRepo
Copy the Markdown content
Paste it into your project's AGENTS.md file, or save it as a separate .md file in your project

For Codex CLI specifically, the cleanest approach is to merge skill instructions into your AGENTS.md under clearly labeled sections:

# AGENTS.md

## Debugging Workflow
<!-- Pasted from Systematic Debugging skill -->
When debugging, follow these steps:
1. Reproduce the issue with a minimal test case
2. Add strategic logging at key decision points
3. Form a hypothesis before changing code
4. Verify the fix doesn't introduce regressions

Method 3: Symlink for Multi-Agent Projects

If you use both Claude Code and Codex CLI on the same project, you can maintain a single source of truth:

# Skills live in .claude/commands/ for Claude Code
# Symlink key content into AGENTS.md for Codex CLI
cat .claude/commands/*.md >> AGENTS.md

8 Recommended Skills for Codex CLI

These skills have been tested with Codex CLI and provide immediate productivity gains. Each one is available on TokRepo and can be installed or copied into your AGENTS.md.

1. Get Shit Done (GSD)

What it does: A comprehensive project management framework that breaks large projects into milestones, phases, and tasks. Tracks progress across sessions with persistent .planning/ directories.

Why it matters for Codex: Codex CLI excels at focused tasks but can lose track of multi-step projects. GSD provides the scaffolding to keep complex work on track.

npx tokrepo install e108cf5c-c34e-4d27-a694-66a693301e87

View on TokRepo

2. Vercel Skills — Agent Skill Ecosystem

What it does: A curated collection of 13,000+ community-contributed skills covering Next.js, React, deployment patterns, and full-stack development workflows.

Why it matters for Codex: If you work with Vercel, Next.js, or React, this collection gives Codex domain-specific knowledge that dramatically improves code quality.

npx tokrepo install d1eba6f1-5166-4762-bbbd-cf00f14892b7

View on TokRepo

3. Claude SEO — Complete SEO Skill

What it does: Runs comprehensive SEO audits — keyword research, on-page analysis, content gap identification, technical checks, and competitor comparison.

Why it matters for Codex: SEO requires following a structured checklist. This skill ensures Codex covers all the bases instead of improvising an incomplete audit.

npx tokrepo install cb068086-48bc-4dc2-b53e-9a16eba5b51f

View on TokRepo

4. Systematic Debugging

What it does: A structured debugging methodology — reproduce, isolate, hypothesize, fix, verify. Prevents the common trap of changing code randomly until something works.

Why it matters for Codex: When Codex runs in full-auto mode, a debugging skill prevents it from spiraling into trial-and-error loops. It forces methodical investigation.

npx tokrepo install 78ed006e-0c05-4bab-91de-c0c72c3e4cc4

View on TokRepo

5. Planning with Files

What it does: Creates structured plan files before executing complex tasks. Writes the plan to disk so it persists across context windows and sessions.

Why it matters for Codex: Codex CLI sessions can be long-running. Planning skills ensure the agent thinks before acting and maintains a written record of its approach.

npx tokrepo install 034be597-dbb5-4649-ad6e-98f9ff6332b8

View on TokRepo

6. Web Access

What it does: Gives the agent structured methods for fetching and parsing web content — documentation pages, API references, and live data.

Why it matters for Codex: By default, Codex CLI cannot browse the web. This skill provides patterns for incorporating external information when the agent needs to reference docs or check live endpoints.

npx tokrepo install 5766b7f4-bfdb-4048-87e7-50af1e5f6f88

View on TokRepo

7. Skill Creator

What it does: A meta-skill that guides you through creating new agent skills — writing the frontmatter, triggers, instructions, and testing steps.

Why it matters for Codex: Once you have used a few skills, you will want to create your own. This skill makes the process repeatable and ensures your custom skills follow best practices.

npx tokrepo install 0b7c0a41-97e1-4187-9cc5-4dc32d91a9cd

View on TokRepo

8. Agent Skills Standard

What it does: Defines the universal standard for agent skill files — metadata fields, instruction format, trigger conventions, and compatibility rules across different AI agents.

Why it matters for Codex: If you want your skills to work across Codex CLI, Claude Code, and Gemini CLI, this standard tells you exactly what fields to include and how to structure them.

npx tokrepo install 1a1292f5-c88b-4eb5-b7dd-a3bf7bb29ee8

View on TokRepo

Codex CLI vs Claude Code: Skill Compatibility

Both Codex CLI and Claude Code support agent skills, but they read them differently. Understanding the differences helps you write skills that work with both.

Feature	Codex CLI	Claude Code
Skill file format	AGENTS.md (Markdown)	.md files in .claude/commands/
Discovery method	Auto-scan from project root	Fixed directory lookup
Activation	Always active (merged into context)	On-demand (slash commands / NL)
Frontmatter	Not required	Optional (name, description, triggers)
Subdirectory scoping	Yes (directory-level AGENTS.md)	No (global only)
Multiple skills	Single file with sections	One file per skill
Skill registry	TokRepo / manual copy	TokRepo / tokrepo install
Model provider	OpenAI (GPT-4.1, o3, o4-mini)	Anthropic (Claude Sonnet/Opus)

Key Takeaway

Skills written for Claude Code can be adapted for Codex CLI by copying the instruction content into AGENTS.md. The core logic — the steps, rules, and workflows — transfers directly. Only the packaging differs.

For a deeper comparison of skill formats across all major AI coding agents, see Skills vs MCP vs Rules.

FAQ

Can I use Claude Code skills directly with Codex CLI?

Yes, with minor adaptation. Claude Code skills are Markdown files with instructions — the same format Codex CLI reads from AGENTS.md. Copy the instruction content (everything below the frontmatter) into your AGENTS.md file. The frontmatter fields like triggers are Claude Code-specific and can be removed for Codex.

Does Codex CLI support slash commands like Claude Code?

No. Codex CLI does not have a slash command system. Instead, all instructions from AGENTS.md are loaded into context automatically. You activate specific workflows by describing what you want in natural language — for example, "debug this issue using the systematic debugging approach" instead of typing /debug.

Is Codex CLI free to use?

Codex CLI itself is free and open source. However, it calls OpenAI's API, which requires a paid API key. Costs depend on the model you use — GPT-4.1 is more affordable for routine tasks, while o3 provides stronger reasoning for complex problems. Check OpenAI's pricing page for current rates.

Next Steps

Now that you have Codex CLI installed and configured with skills, explore these related guides:

How to Create Your First Agent Skill — build a custom skill from scratch
Skills vs MCP vs Rules — Complete Guide — understand when to use each approach
15 Best Claude Code Skills — more skill recommendations (most work with Codex too)
Gemini CLI Skills Guide — set up skills for Google's CLI agent

Browse the full skill catalog on TokRepo to find skills for your specific tech stack and workflow.