Source: Build skills (OpenAI Codex docs)
How Codex implements the Agent Skills standard: .agents/skills locations, $skill invocation, a 2%-of-context listing budget, openai.yaml policy, and plugins for distribution.
Contents
- What: official product documentation
- Publisher: OpenAI
- Date: living document, read 2026-11-14
- Original: Build skills (formerly developers.openai.com/codex/skills)
Summary
Codex adopted the open skill format and adds an optional agents/openai.yaml sidecar for UI and invocation policy, plus explicit budget controls on how much of the window the skill list may use.
Key claims
- Skill = directory with
SKILL.md(name,description) plus optionalscripts/,references/,assets/,agents/openai.yaml. - Locations: repo
.agents/skills(cwd up to repo root), user$HOME/.agents/skills, admin/etc/codex/skills, system (bundledskill-creator,skill-installer). - Invocation: explicit via
$or/skillsin CLI/IDE (or@in ChatGPT); implicit when the task matches the description. - Budget: the initial list (names, descriptions, paths) uses at most 2% of the context window, or 8,000 chars if unknown; descriptions are shortened first, then skills omitted with a warning.
skills.max_context_tokensraises it up to 10,000 tokens. agents/openai.yaml:interface(display metadata),policy.allow_implicit_invocation(default true),dependencies.tools(e.g. MCP servers).- Disable with
[[skills.config]]entries (enabled = false) in~/.codex/config.toml; bundled skills can be turned off per trusted project. - Plugins distribute skills, optionally bundled with connectors (MCP servers).