Using agents and skills in OpenAI Codex CLI (AGENTS.md, skills, prompts)

Codex CLI has no subagent files. If you come from Claude Code, the short version is: project rules go in AGENTS.md, reusable roles and workflows (your "agents") become skills, which are folders with a SKILL.md, and slash commands become custom prompts, Markdown files in ~/.codex/prompts/ that you run as /prompts:<name>.

That mapping covers most of what people actually use agents for. This post walks through each piece with real files you can copy, shows how to convert a Claude Code subagent into a Codex skill, and explains how to keep both tools working in the same repo.

The mental model: Claude Code to Codex

Here is how the pieces line up. The right column is what you should reach for in Codex when you would have used the left column in Claude Code.

The biggest difference is the agent row. A Claude Code subagent runs in its own context window and returns a result to the main conversation. A Codex skill is instructions the same session picks up and follows. You get the role and the checklist, not the isolation. The Claude Code subagents guide covers what that isolation buys you.

Writing a useful AGENTS.md

AGENTS.md sits at the root of your repo and tells Codex how this project works. Codex reads it before doing work, so treat it like onboarding notes for a new teammate who is fast but has never seen your codebase.

What belongs in it:

• The commands that prove the code works (test, typecheck, lint, build)
• Layout: where things live and what not to touch
• Conventions that are not obvious from the code
• Rules for finishing a task

What does not belong: long style essays, anything a linter already enforces, and step-by-step workflows you only need sometimes. Those are better as skills, because a skill's body only loads when it is relevant.

Here is a real-shaped example for a TypeScript web app:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
- Build: `pnpm build`

## Layout
- `src/app/` routes and pages
- `src/lib/` shared logic, no React imports here
- `src/db/` schema and migrations. Never edit an existing migration, add a new one.
- `scripts/` one-off tooling, not shipped

## Conventions
- Use the `Result` type in `src/lib/result.ts` for fallible functions, don't throw across module boundaries.
- Dates are stored as UTC ISO strings.
- New environment variables must be added to `.env.example`.

## Done means
- Tests, typecheck, and lint pass.
- No `console.log` left in `src/`.
- Summarize what changed and anything you could not verify.

Keep it short enough that you would read it yourself. Current Codex docs also describe a global ~/.codex/AGENTS.md and nested AGENTS.md files for subdirectories, plus a size cap on combined instructions. Check the docs for your version before relying on exact precedence and limits.

Writing a skill: a security reviewer

A skill is a folder containing a SKILL.md. The frontmatter has name and description. The description is what Codex matches against your task to decide whether to use the skill, so it carries the same weight a subagent description does in Claude Code. Write it as "when to use this", not as a job title.

security-reviewer/
  SKILL.md
  references/
    checklist.md

---
name: security-reviewer
description: Review code changes for security issues. Use when the user asks for a security review, before merging auth, payments, file upload, or input-handling changes, or when a diff touches secrets, SQL, or shell commands.
---

You are acting as a security reviewer for this change. You review, you do not rewrite.

## Process
1. Find the change set: run `git diff --stat` and `git diff` against the main branch.
2. For each changed file, check the items in `references/checklist.md`.
3. Trace user input from where it enters (request params, form data, env, files) to where it is used (queries, shell, file paths, HTML output).
4. Check that secrets are read from the environment and never logged or committed.

## Output
Report findings as a list, most severe first:

- **Severity**: critical / high / medium / low
- **Location**: file and line
- **Issue**: one sentence
- **Fix**: the smallest change that closes it

If you find nothing, say so and list what you checked. Do not pad the report with style comments.

A few things that make role-style skills work:

• A narrow job. "Security reviewer" beats "senior engineer."
• A concrete process. Numbered steps with real commands beat adjectives like "thorough."
• A defined output. Give the result a shape and you can scan it quickly.
• Supporting files for bulk. Long checklists go in references/.

Codex can pick a skill up on its own when your request matches the description, or you can call it explicitly. At the time of writing, the docs say you can type $ to mention a skill or run /skills in the CLI, so $security-reviewer check this branch works.

Where skills live

The current Codex docs list .agents/skills/ in the repo (scanned from your working directory up to the repo root) and ~/.agents/skills/ for personal skills. Older guides and some tools mention .codex/skills/; if a skill doesn't show up, check which locations your Codex version scans, and restart Codex.

Writing a custom prompt

Custom prompts are the Codex version of slash commands: a Markdown file whose content gets sent as your message when you run it. They live in ~/.codex/prompts/ in your home directory, which means they are personal and global, not committed with the repo.

Create ~/.codex/prompts/fix-issue.md:

---
description: Investigate and fix a bug from a short description
argument-hint: [description of the bug]
---

Fix this bug: $ARGUMENTS

1. Reproduce it first. Find or write a failing test that shows the problem.
2. Find the root cause. Explain it in two or three sentences before changing code.
3. Make the smallest fix that makes the test pass.
4. Run the test, typecheck, and lint commands from AGENTS.md.
5. Report what you changed and what you verified.

Run it from Codex:

/prompts:fix-issue checkout total is wrong when a coupon and free shipping both apply

$ARGUMENTS expands to everything you typed after the command. The docs also describe positional placeholders like $1 and named ones like $FILE passed as FILE=value.

If the prompt doesn't appear in the slash menu, restart Codex or start a new session. Prompts are loaded when a session starts. Two more things worth knowing, both from the current docs and worth re-checking for your version: Codex only reads top-level Markdown files in ~/.codex/prompts/ (no subfolders), and OpenAI now marks custom prompts as deprecated in favor of skills. They still work as documented at the time of writing, but for anything you want to share with a team, a skill in the repo is the safer home.

Converting a Claude Code subagent into a Codex skill

Take a typical Claude Code subagent:

---
name: code-reviewer
description: Reviews code for correctness, readability, and missing tests. Use proactively after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent changes,
then review each modified file. Report issues grouped by severity with file and line.

Here is what carries over and what doesn't:

The converted version, saved as code-reviewer/SKILL.md in your skills folder:

---
name: code-reviewer
description: Review code for correctness, readability, and missing tests. Use after writing or modifying code, or when the user asks for a review.
---

Act as a code reviewer. Do not edit files during the review.

1. Run `git diff` to see recent changes.
2. Review each modified file for correctness, readability, and missing tests.
3. Report issues grouped by severity, with file and line. Keep the report short.

The lost isolation matters more than the lost frontmatter. In Claude Code, a reviewer subagent reads a lot of files and hands back a summary, and your main context stays clean. In Codex, everything the skill reads stays in the conversation. For long tasks, run the review in a fresh session, or ask for the review at a natural break.

If you are still deciding which Claude Code primitive a piece should be, skills vs subagents vs slash commands breaks that down.

Keeping Claude Code and Codex in one repo

You don't need two copies of your project knowledge. A layout that works:

CLAUDE.md            # Claude Code project memory
AGENTS.md            # Codex project instructions
.claude/
  agents/            # Claude Code subagents
  skills/            # Claude Code skills
  commands/          # Claude Code slash commands
.agents/skills/      # Codex skills (check your version's path)

Some practical rules:

• One source of truth for project facts. Put commands, layout, and conventions in AGENTS.md, then import it from CLAUDE.md with an @AGENTS.md line, so both tools read the same rules.
• Skills port almost as-is. Both tools use a folder with a SKILL.md that has name and description. You can often copy a skill folder between the two directories unchanged.
• Agents need the conversion above. Keep the Claude Code version with its tools and model, and a trimmed Codex version without them.
• Commands are personal on Codex. Codex custom prompts live in your home directory, so teammates won't get them from a git pull.

How the SlashKits installer handles Codex

I built this mapping into the SlashKits installer, since every agent and command in the kit needed a Codex form. Running node slashkits/bin/slashkits.mjs install sets up both tools:

• Claude Code: agents to .claude/agents, skills to .claude/skills, commands to .claude/commands, a routing file at .claude/slashkits.md, and an import line in CLAUDE.md.
• Codex: agents and skills installed as Codex skills in .agents/skills (or ~/.agents/skills with --global), commands as custom prompts in ~/.codex/prompts, and a line in AGENTS.md pointing to the routing file.

Install per project or with --global. Note that the Codex prompts always land in ~/.codex/prompts, so they are global even on a per-project install. Given the skill location note above, if Codex doesn't list the installed skills, check which skill folders your version scans. Reinstalling never overwrites files you have edited, and doctor and uninstall commands handle checking and removal.

Whichever way you set it up, the pattern is the same: AGENTS.md for the rules that always apply, skills for roles and workflows that apply sometimes, and prompts for the things you type often enough to save.