Skip to content

Codex Skills System

Skills are reusable instructions packaged in a folder. Instead of typing the same complex prompt repeatedly, create a skill once and invoke it by name.

What’s in a Skill

A skill is a directory with at least one file:

my-skill/
├── SKILL.md          # Required: instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: docs to include
└── assets/           # Optional: templates, configs

The SKILL.md file contains metadata and instructions. Codex loads this when the skill activates.

SKILL.md Format

---
name: code-review
description: Review code changes for bugs, security issues, and style violations
---

# Code Review

Review the current diff and provide feedback on:

1. **Bugs** — Logic errors, edge cases, null checks
2. **Security** — Injection vulnerabilities, auth issues, data exposure
3. **Style** — Naming, formatting, consistency with codebase conventions

Format output as a prioritized list. Critical issues first.

Skip praise. Focus on actionable feedback.

The name and description fields are required. Description matters for implicit invocation — Codex matches task descriptions against skill descriptions.

Where to Put Skills

Codex scans these locations in order:

LocationPathScope
Folder.agents/skills/Current directory (scans up to repo root)
Repo root$REPO_ROOT/.agents/skills/Entire repository
User~/.agents/skills/All your projects
Admin/etc/codex/skills/System-wide
SystemBuilt-inOpenAI-provided

Closer scopes override farther ones. A repo skill beats a user skill with the same name.

Invoking Skills

Explicit

Reference directly with $:

$code-review

Or use the command:

/skills

This lists available skills. Select one to run.

Implicit

If allow_implicit_invocation is true (default), Codex picks skills automatically when your request matches a skill’s description.

Ask:

Review my changes for security issues

Codex sees “review” + “security” and activates your code-review skill.

Write clear descriptions. Vague descriptions cause wrong matches or no matches.

Built-in Skills

Codex ships with four built-in skills:

$skill-creator — Helps you build new skills interactively. Generates the folder structure and SKILL.md.

$skill-installer — Installs skills from URLs or local paths.

$openai-docs — Searches OpenAI documentation for answers about Codex and the API.

$plan — A planning skill for structured research and proposal workflows.

Try:

$skill-creator "A skill that generates test files for any function"

Creating a Custom Skill

Example: a skill that writes commit messages.

Create the directory:

mkdir -p ~/.agents/skills/commit-msg

Write SKILL.md:

---
name: commit-msg
description: Generate a commit message from staged changes
---

# Generate Commit Message

1. Run `git diff --staged` to see changes
2. Analyze what changed and why
3. Write a commit message following conventional commits format

Format:
- First line: type(scope): description (max 72 chars)
- Blank line
- Body: explain what and why, not how

Types: feat, fix, docs, style, refactor, test, chore

Output only the commit message. No explanation.

Now $commit-msg generates messages from your staged changes.

Adding Scripts

Skills can include executable code. Codex runs scripts when the skill activates.

commit-msg/
├── SKILL.md
└── scripts/
    └── format-check.sh

scripts/format-check.sh:

#!/bin/bash
# Verify staged changes pass linting before generating message
npm run lint:staged

Reference in SKILL.md:

Before generating the message, run scripts/format-check.sh.
If it fails, tell the user to fix lint errors first.

Metadata File

For advanced configuration, add agents/openai.yaml:

policy:
  allow_implicit_invocation: false
dependencies:
  tools:
    - type: "mcp"
      value: "github_search"

Set allow_implicit_invocation: false under policy for skills that should only run when explicitly called. Good for destructive operations like “delete-unused-files”.

Disabling Skills

Turn off a specific skill in config.toml by pointing to its path:

[[skills.config]]
path = "~/.agents/skills/risky-skill/"
enabled = false

Progressive Loading

Codex uses progressive disclosure. Initially, it loads only skill metadata (name, description). Full instructions load only when the skill activates.

This saves context window space when you have many skills installed.

Debugging Skills

If a skill doesn’t work:

  1. Check the path: run /skills and verify it appears
  2. Check the description: vague descriptions cause matching issues
  3. Try explicit invocation: $exact-skill-name
  4. Restart Codex: skill changes need a refresh

Logs at ~/.codex/log/ show which skills loaded.

Example: Test Generator

A practical skill that generates tests for any function:

---
name: test-gen
description: Generate unit tests for a function or module
---

# Test Generator

When asked to generate tests:

1. Read the target function/module
2. Identify edge cases:
   - Empty inputs
   - Boundary values
   - Error conditions
   - Type coercion issues
3. Generate tests using the project's test framework (detect from package.json or pytest.ini)
4. Follow existing test file conventions in the repo

Output complete test file. Use descriptive test names.
If mocking is needed, prefer the project's existing mock setup.