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

Published: May 14, 2026

Category: Installation Guides

> 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.

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/ | tar xz -C ~/.codex/skills/

Related Articles