Codex CLI Skills and AGENTS.md: Complete Setup Guide (2026)

Codex CLI Skills and AGENTS.md: Complete Setup Guide (2026)

Quick Answer: Codex CLI reads skills from ~/.codex/skills/ (personal) and .codex/skills/ (project). AGENTS.md goes in your repo root or ~/.codex/AGENTS.md for global context. Skills provide on-demand task expertise. AGENTS.md provides always-on project context. Use both for the best results.

---

OpenAI's Codex CLI has become one of the fastest-growing AI coding agents in 2026. It runs in your terminal, understands your codebase, and executes multi-step coding tasks autonomously.

What makes Codex CLI different from raw ChatGPT or GPT API calls is its support for structured context: AGENTS.md for project-level instructions and SKILL.md for reusable task expertise. This guide covers how to set up both for maximum effectiveness.

AGENTS.md: your project's instruction manual for Codex

AGENTS.md is a markdown file that tells Codex CLI how your project works. Place it in your repo root or in ~/.codex/AGENTS.md for global instructions that apply everywhere.

What goes in AGENTS.md

Keep it focused on information a new team member would need on day one:

# AGENTS.md

## Build
- `pnpm install` to set up dependencies
- `pnpm run build` for production build
- `pnpm run dev` for local development

## Test
- `pnpm vitest run` for unit tests
- `pnpm playwright test` for E2E

## Conventions
- TypeScript strict mode everywhere
- Functional components only (no class components)
- Use Zod for validation
- Error handling: Result pattern, never throw in async
- Commit messages: Conventional Commits format

## Architecture
- Monorepo with pnpm workspaces
- API: Express + Prisma in packages/api/
- Web: Next.js in packages/web/
- Shared types in packages/shared/

## Don't
- Never modify .env files directly
- Never commit secrets
- Ask before adding new dependencies

Where Codex CLI looks for AGENTS.md

1. ~/.codex/AGENTS.md (global, applies to all projects)
2. Repo root AGENTS.md (project-specific, overrides global)
3. Subdirectory AGENTS.md files (scoped to that directory)

Project-level overrides global. This means you can set general preferences globally and override them per project.

Skills to install right now

code-reviewer

Free

Run a structured code review on your recent changes without waiting for a teammate. This skill checks for security vulnerabilities (SQL injection, XSS, authentication bypasses), logic errors, edge cases, performance issues, and style violations.Findings are organized by severity: Critical, Warning, and Suggestion. Each finding includes the file, line number, a description of the issue, and a concrete fix. Use it as a first pass before peer review, or as your only reviewer on solo projects.

Get this skill

git-commit-writer

Free

Stop writing vague commit messages. This skill reads your actual staged diff and generates precise, informative commit messages following the Conventional Commits specification. It detects the commit type (feat, fix, refactor, docs, chore, etc.), identifies the scope from the changed files, flags breaking changes, and suggests splitting commits when multiple logical changes are staged. Works with any git repository.`

Get this skill

readme-generator

Free

Point this skill at any project and it generates a real README from your actual codebase. It scans package.json, pyproject.toml, Cargo.toml, or equivalent to detect your language, framework, and dependencies. It reads your .env.example for setup instructions, checks for Dockerfiles and CI config, and produces a README with only the sections that apply to your project. No placeholder text, no generic filler. Every line is derived from what it actually finds in your repo.

Get this skill

Browse all skills

SKILL.md: on-demand expertise for specific tasks

While AGENTS.md provides always-on context, SKILL.md skills activate only when relevant. A code review skill loads when you ask for a review. A testing skill loads when you write tests.

Installing skills in Codex CLI

Skills live in ~/.codex/skills/ (personal) or .codex/skills/ (project):

# Install from Agensi with one command
mkdir -p ~/.codex/skills && curl -sL https://www.agensi.io/api/install/code-reviewer | tar xz -C ~/.codex/skills/

# Or manually
mkdir -p ~/.codex/skills/code-reviewer
# Place SKILL.md inside

Skill directory structure

~/.codex/skills/
├── code-reviewer/
│   └── SKILL.md
├── test-generator/
│   ├── SKILL.md
│   └── references/
│       └── testing-patterns.md
└── deploy-checker/
    └── SKILL.md

AGENTS.md + SKILL.md together

The two systems are complementary:

AGENTS.md tells Codex "this is a TypeScript monorepo with pnpm, strict mode, and the Result pattern."

SKILL.md code-reviewer tells Codex "when reviewing code, check security first, then logic, then performance, then style. Output findings in this format."

When you ask "review the auth module," Codex reads AGENTS.md for project context (TypeScript, Result pattern, Prisma) and the code-reviewer skill for methodology (check OWASP top 10, flag breaking changes, verify test coverage). The review is both project-aware and methodologically sound.

Codex CLI-specific features

openai.yaml

Codex CLI supports an additional openai.yaml file inside skill folders. This file adds UI metadata and MCP tool dependencies that are specific to Codex CLI:

# openai.yaml (optional, Codex CLI only)
display_name: "Code Reviewer Pro"
icon: "shield"
mcp_tools:
  - github
  - sentry

Other agents ignore this file. If you're building skills exclusively for Codex CLI, use it. If you want cross-agent compatibility, rely on the SKILL.md frontmatter only.

Sandbox execution

Codex CLI runs in a sandboxed environment by default. Skills that reference external tools or scripts may behave differently than in Claude Code, which runs directly in your terminal. Test skills in both environments if cross-agent compatibility matters.

Cross-agent compatibility

Skills built for Codex CLI work in Claude Code, Cursor, OpenClaw, and other SKILL.md agents. Copy the folder:

# Codex CLI to Claude Code
cp -r ~/.codex/skills/code-reviewer ~/.claude/skills/

# Codex CLI to OpenClaw
cp -r ~/.codex/skills/code-reviewer ~/.openclaw/skills/

AGENTS.md is supported by Codex CLI natively, and Claude Code reads it as additional context. The format is not Codex-specific.

Recommended skills for Codex CLI users

Start with skills that match the tasks you do most frequently:

Code review for structured, consistent reviews. Commit writer for conventional commit messages from staged diffs. Test generator for framework-specific test creation. Deploy checker for pre-deployment verification.

Browse all Codex CLI-compatible skills at agensi.io/skills. Every skill on the marketplace works with Codex CLI out of the box.

---

Install any skill into Codex CLI with one command: mkdir -p ~/.codex/skills && curl -sL https://www.agensi.io/api/install/<slug> | tar xz -C ~/.codex/skills/