On this page
Codex Agent Skills
Learn how Codex Agent Skills use .agents/skills, progressive disclosure, plugins, optional metadata, and how they differ from AGENTS.md.
12 min readHow Codex Agent Skills Work
Codex Agent Skills are official reusable workflow packages for Codex. They complement AGENTS.md: skills codify task-specific procedures, while AGENTS.md layers standing project instructions and repository context.
Source checked against OpenAI Codex skills docs
OpenAI documents Agent Skills as reusable workflow packages for Codex CLI, IDE extension, and app.
Codex skills use progressive disclosure: initial context includes name, description, and path; full SKILL.md loads when selected.
Codex AGENTS.md is a separate custom-instruction mechanism that Codex reads before doing work.
Primary file
SKILL.md
Repo path
.agents/skills
Distribution
Direct folders for local authoring; plugins for reusable distribution
Related file
AGENTS.md for project instructions
Good fit
Repeatable Codex workflows such as reviews, migrations, docs updates, frontend checks, and operational runbooks.
Watch closely
Do not collapse AGENTS.md, plugins, MCP dependencies, and skills into one concept; each has a different job.
Governance move
Review .agents/skills changes, plugin bundles, optional scripts, and AGENTS.md overrides in the same approval trail.
OpenAI's Codex documentation describes Agent Skills as reusable workflows that package instructions, resources, and optional scripts. Skills are available in the Codex CLI, IDE extension, and Codex app.
Codex uses progressive disclosure. It starts with compact skill metadata, then reads the full SKILL.md when a skill is selected for the task.
Where Codex Skills Live
OpenAI Codex guide
Codex reads skills from repository, user, admin, and system locations. For repositories, it scans .agents/skills in directories from the current working directory up to the repository root.
Direct skill folders are best for local authoring and repo-scoped workflows. Plugins are the installable distribution unit when teams want to share reusable skills or bundle skills with app integrations.
$CWD/.agents/skills for skills relevant to the current working folder.
Parent .agents/skills folders for shared monorepo areas.
$REPO_ROOT/.agents/skills for repo-wide skills.
$HOME/.agents/skills for user-level skills.
/etc/codex/skills and bundled system skills for admin or OpenAI-provided capabilities.
Codex Skills vs AGENTS.md
OpenAI Codex guide
AGENTS.md is not the same thing as a Codex skill. Codex reads AGENTS.md before doing work so it has project instructions, working agreements, and context for the repository.
A skill is a reusable task package. Use AGENTS.md for standing rules that should always apply in a directory. Use a skill for a workflow that should load only when a matching task appears.
Do not over-port platform behavior
Plugins and Optional Metadata
OpenAI Codex guide
Codex documentation positions plugins as the way to distribute reusable skills and apps beyond a single repo. Plugins can include skills, app mappings, MCP server configuration, and presentation assets.
Codex also documents optional agents/openai.yaml metadata for UI metadata, invocation policy, and tool dependencies such as MCP servers.
Permissions and Security
OpenAI Codex guide
Codex skills can include optional scripts and references, and plugins can declare tool dependencies. Treat those additions like production automation, not passive documentation.
Teams should review skill folders, plugin manifests, MCP dependencies, and AGENTS.md files together because all of them can steer Codex's behavior.
Keep skill descriptions precise so implicit matching does not trigger too broadly.
Prefer instructions over scripts unless deterministic behavior or external tooling is required.
Disable implicit invocation when a skill should be used only by explicit request.
Audit plugins before installing them across a team.
Enterprise Governance Checklist
OpenAI Codex guide
The Codex governance model should answer which AGENTS.md files were loaded, which skill was selected, whether a plugin contributed it, and which tools or MCP dependencies were available.
VibeFlow-style work tracking pairs well with Codex skills because each reusable workflow can be tied to a work item, execution log, commit, security review, and QA gate.
Govern Codex Skills with tracked agent work
VibeFlow connects reusable agent workflows to work items, execution logs, commit records, security review, QA, and durable project context. That audit trail makes skills reviewable instead of invisible prompt behavior.
Ready to get started?
See how Axiom Studio can transform your AI infrastructure with enterprise-grade governance, security, and cost optimization.
Contact UsContinue Learning
What Are Agent Skills?
The SKILL.md anatomy and progressive-disclosure foundation.
Skills vs Agents vs MCP
How skills differ from AGENTS.md, tools, MCP, and subagents.
Claude Skills
Compare Codex's .agents model with Claude Code's .claude skills.
What is an AI Software Developer?
Where Codex fits in autonomous coding-agent workflows.
Documentation Skill
A practical reusable skill for source-grounded documentation.