Codex CLI skills · AI coding agents

Codex supports agent skills built on the open agent skills standard: packaged, reusable workflows that Codex can load on demand.

SKILL.md structure

A skill is a directory containing a SKILL.md with required frontmatter (name, description), plus optional supporting files:

my-skill/
├── SKILL.md          # required: frontmatter with name + description
├── scripts/          # optional helper scripts
├── references/       # optional reference material
├── assets/           # optional assets
└── agents/
    └── openai.yaml   # optional UI metadata, policy.allow_implicit_invocation,
                      # tool/MCP dependencies

---
name: changelog-writer
description: Draft a changelog entry from the commits since the last tag
---

# Changelog writer

1. Run `git log --oneline $(git describe --tags --abbrev=0)..HEAD`.
2. Group commits by type (feat, fix, chore).
3. ...

Progressive disclosure: Codex initially sees only each skill’s name, description, and path (capped at 2% of the model’s context window, or 8,000 chars when unknown; tunable via skills.max_context_tokens, cap 10,000 tokens). The full SKILL.md is read only when the skill is actually used.

Discovery paths

Codex scans .agents/skills from the cwd up to the repo root (following symlinks):

Scope	Location
Repo	`$CWD/.agents/skills` and every directory up to `$REPO_ROOT/.agents/skills`
User	`$HOME/.agents/skills`
Admin	`/etc/codex/skills`
System	Bundled with Codex (e.g. `skill-creator`, plan skills)

Note: skills live under .agents/skills — not .codex/skills. And <writable_root>/.agents is a protected read-only path in workspace-write sandbox mode.

Invocation

Explicit: /skills in the TUI to browse and pick one, or mention $skill-name in a prompt.
Implicit: Codex picks a skill itself when the task matches its description (unless the skill restricts implicit invocation).

Built-in helpers:

$skill-creator — author a new skill interactively.
$skill-installer — install a skill, e.g. $skill-installer linear.

Disable a skill without deleting it via ~/.codex/config.toml:

[[skills.config]]
path = "/Users/you/.agents/skills/changelog-writer/SKILL.md"
enabled = false

Distribution via plugins

Plugins distribute skills (plus optional MCP servers/connectors) through marketplaces:

codex plugin marketplace add owner/repo
codex plugin add <plugin>
codex plugin list
codex plugin remove <plugin>

Plugin sources can be GitHub shorthand (owner/repo[@ref]), Git URLs, or local directories (--ref, --sparse). Plugin-provided MCP servers are configured under plugins.<plugin>.mcp_servers.<server>.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.