)
Last updated: November 12, 2026
What are Codex skills? Codex skills are folders that teach OpenAI's Codex agent a repeatable job. Each folder holds a SKILL.md file with a name and a description, plus optional scripts, references and assets. Codex reads the description first and loads the full instructions only when a task matches. The trade-off is trust: a skill brings text the agent obeys and code it may run.
TL;DR: Key Takeaways
- A Codex skill is a directory with a SKILL.md file, and only the name and description fields are required (OpenAI, 2026).
- Codex starts with each skill's name, description and path only, and keeps that initial list to a small budget of about 2% of the context window or 8,000 characters (OpenAI, 2026).
- Skills live in 4 scopes, repository, user, admin and system, and a repository scan runs from the working directory up to the repository root (OpenAI, 2026).
- The SKILL.md layout follows the open Agent Skills specification, so other agents that adopt it share the format (Agent Skills, 2026).
- Snyk's February 2026 audit of 3,984 public skills found a flaw in 36.82% and 76 confirmed malicious payloads. It is vendor-reported and not Codex-specific (Cloud Security Alliance, 2026).
- Codex's default sandbox keeps network access off, and CVE-2025-59532, a sandbox bypass rated CVSS 8.6, was fixed in version 0.39.0 (GitHub Advisory, 2025).
At a glance: Codex skills in 60 seconds
Quick Answer
What is inside a Codex skill, and how does Codex use it?
A skill is a directory built around one required file, SKILL.md. Codex lists each skill by name and description, then opens the body, scripts and references only when it uses the skill. Anything executable sits in scripts/, so a skill is both instructions and code.
| Part | Required | What it does |
|---|---|---|
| SKILL.md | Yes | Frontmatter with name and description, then the instructions |
| scripts/ | No | Executable code the skill can ask Codex to run |
| references/ | No | Longer documents Codex reads only when needed |
| assets/ | No | Templates and other files used in the output |
| agents/openai.yaml | No | Codex settings, such as whether implicit invocation is allowed |
How we researched
On November 12, 2026 we read OpenAI's Codex documentation on skills, approvals and security, and managed configuration. We also read the open Agent Skills specification, the openai/skills repository, GitHub's advisory for CVE-2025-59532, the Cloud Security Alliance note on SKILL.md poisoning and the OWASP 2026 lists. Documentation changes often.
What are Codex skills and how does Codex use them?
Codex skills are directories that package instructions, and optionally scripts and reference files, for one repeatable task. Codex loads each skill's name, description and path first, then reads the full SKILL.md only when it uses the skill. This progressive disclosure keeps context small while many skills stay installed.
You can call a skill explicitly by typing $skill-name or browsing /skills. Codex can also pick one implicitly when your task matches a description, so the description decides routing. Setting allow_implicit_invocation to false in agents/openai.yaml turns implicit use off for that skill.
According to OpenAI (2026), the initial list is capped at about 2% of the context window or 8,000 characters, and the skills.max_context_tokens setting can raise it up to 10,000. Too many long descriptions get trimmed. For standing project rules, see our AGENTS.md guide.
| Mechanism | What it is | When it loads |
|---|---|---|
| Skill | Task-specific instructions, with optional scripts | Name and description at start, body on use |
| AGENTS.md | Standing guidance for a project | As project guidance in every run |
| MCP server | Tools and data from an external system | When configured, as tools the agent can call |
| Plugin | A package that distributes skills and other components | Installed, then its parts load as usual |
)
How to create a Codex skill
The fastest route is to ask Codex to run $skill-creator, which scaffolds the folder. By hand, create a directory with a SKILL.md file holding a name and a description, then add scripts or references only when the task needs them. Start a new session if Codex does not list the skill.
- Run $skill-creator, or create .agents/skills/your-skill/SKILL.md in your repository.
- Write the frontmatter. Say when the skill should trigger, not only what it does.
- Keep the body to the steps Codex needs. The specification suggests under 500 lines, with long material moved to references/.
- Add scripts/ only for steps that must be exact every time.
- Test with $your-skill, then with a plain request to check implicit invocation.
- Run skills-ref validate from the specification's reference library to check the format.
Where Codex skills live and how to share them
Codex reads skills from four scopes. Repository skills sit in .agents/skills and travel with the code, user skills sit in $HOME/.agents/skills, administrators can place skills in /etc/codex/skills, and OpenAI bundles system skills. To share a skill beyond one repository, package it in a plugin.
| Scope | Location | Typical use |
|---|---|---|
| REPO | .agents/skills in the working directory, its parents and the repository root | Team workflows that ship with the code |
| USER | $HOME/.agents/skills | Personal skills in every project |
| ADMIN | /etc/codex/skills | Skills an administrator provides to a machine |
| SYSTEM | Bundled with Codex | Built-in skills, including the creator and installer |
To add someone else's skill, use $skill-installer. According to the openai/skills repository (2026), the GitHub catalog of curated skills is now deprecated, and OpenAI points to plugins for distribution. To switch a skill off, set enabled to false in a [[skills.config]] entry, or in [skills.bundled] for the bundled ones.
Codex skills vs Claude Code skills and other agents
Codex and Claude Code both read a SKILL.md folder from the open Agent Skills format, so a simple skill often moves between them. What differs is the folder names, the call syntax and the controls around execution. Codex adds a sandbox and approval policies, and each tool has its own administrator settings.
| Codex | Claude Code | |
|---|---|---|
| Personal skill folder | $HOME/.agents/skills | ~/.claude/skills/ |
| Project skill folder | .agents/skills | .claude/skills/ |
| Explicit call | $skill-name | /skill-name |
| Distribution | Plugins and the ADMIN scope | Plugins from marketplaces |
For Claude Code's side, read our Claude Code skills guide and the Claude Code plugins guide. For ChatGPT's own skills, see best ChatGPT skills, and for the OpenClaw ecosystem, OpenClaw skills. For results rather than formats, see our Codex vs Claude Code benchmark.
What can go wrong with a Codex skill
A Codex skill is natural-language instruction the agent follows, plus code it may run, so it behaves like a dependency that can act as you. The main risks are hostile instructions, scripts, untrusted sources and persistence in other files. Most public evidence comes from other agents, but the format is shared.
| Risk | What the evidence says | Why it matters in Codex |
|---|---|---|
| Hidden instructions | The CSA note says a payload can sit in prose, invisible Unicode characters, external references or conditional instructions | The description and body enter Codex's context, and a reviewer sees only the visible text |
| Untrusted sources | Snyk's audit: 36.82% of 3,984 skills had a flaw, 13.4% critical, 76 malicious (vendor-reported) | Public skills are the main source, and the openai/skills catalog is deprecated |
| Scripts | Command execution payloads were a recurring family in that audit | Files in scripts/ run as commands, so the sandbox is the only containment |
| Persistence | Payloads told agents to write instructions into other context files | A poisoned AGENTS.md or skill can outlive the skill that wrote it |
| Sandbox flaws | CVE-2025-59532, CVSS 8.6, fixed in 0.39.0 | A skill is only as contained as the Codex version you run |
According to the Cloud Security Alliance (2026), the audit covered skills from ClawHub and skills.sh, not Codex, so read the percentages as a signal about the ecosystem. According to GitHub's advisory (2025), CVE-2025-59532 is a sandbox bypass with a CVSS score of 8.6, fixed in Codex 0.39.0. Review a skill before you use it:
- Read SKILL.md and every referenced file as instructions that act with your authority.
- Open scripts/ and check for network calls, credential reads and writes outside the workspace.
- Search for invisible Unicode characters in the text files.
- Copy the skill into your repository and review it in a pull request, instead of installing live.
- Run it first with network access off.
Security and governance: control Codex skills in production
Codex gives you three layers: a sandbox that limits what skill scripts can touch, approval policies that decide when to ask, and managed configuration that administrators set for everyone. None of them reads a skill's intent, so add runtime inspection of the agent's tool calls.
| Control | What it does | Limit |
|---|---|---|
| Sandbox | Network off by default, workspace-write, and protected paths such as .git, .agents and .codex stay read-only | Does not judge what instructions ask for inside the allowed area |
| Approval policy | A granular policy includes a skill_approval option | Approval prompts depend on a person reading them |
| Web search | Cached results by default | Results are still untrusted input |
| Managed requirements.toml | Fixes approval policy, sandbox and permission profiles, web search, hooks, the MCP allowlist and plugin marketplace sources | We found no skill-level allowlist on the pages we read, so confirm it in the current docs |
| Skill switches | enabled = false per skill or for bundled skills | Set in config files, not a review process |
| OpenTelemetry events | Codex can emit events for monitoring | Observes, does not block |
According to OpenAI (2026), administrators can fix approval, sandbox and related settings for everyone through requirements.toml. Treat a skill change as a code change. Require pull request review on .agents/skills and assign an owner per skill. This is our recommendation, not an OpenAI setting.
The OWASP 2026 lists give a shared vocabulary. This is our mapping of skill risks to the LLM Top 10 and the Top 10 for Agentic Applications. OWASP also runs an incubator Agentic Skills Top 10, version 1.0-2026, aimed at skills.
| Skill risk | OWASP 2026 ID | Codex example |
|---|---|---|
| Prompt injection | LLM01 | A hostile instruction in SKILL.md or in a file the skill reads |
| Supply chain | LLM04, ASI04 (Agentic Supply Chain Vulnerabilities) | A skill copied from a public registry |
| Excessive agency | LLM03 | A skill that bundles broad scripts and permissions |
| Agent goal hijack | ASI01 | Text that redirects the task toward the attacker's goal |
| Tool misuse | ASI02 | A skill that drives shell or MCP tools beyond its purpose |
| Identity and privilege abuse | ASI03 | A script that reads credentials from the environment |
| Unexpected code execution | ASI05 | A scripts/ command, or a sandbox flaw |
NeuralTrust treats this as a runtime problem. Agent Runtime Security (TrustGuard) inspects agent interactions as they happen and can allow, block or transform them in flight. Its Codex integration uses Codex lifecycle hooks on prompt submission and around tool calls such as Bash, apply_patch and MCP, and connects the Agent Gateway (TrustGate) as an MCP server. Hooks see only what Codex emits, and the docs list the integration's limits, so read them before relying on it.
Where should you start?
Start by listing the skills Codex can already see, then restrict where new ones come from, review each one like code, and add runtime control last. You cannot govern skills you have not inventoried, and a review does not stop a script from behaving differently on a later run.
| Phase | Goal | Key actions |
|---|---|---|
| 1. Inventory | Know which skills load | List .agents/skills, $HOME/.agents/skills and /etc/codex/skills on each machine |
| 2. Restriction | Limit sources and reach | Keep network off, disable bundled skills you do not use, apply managed requirements |
| 3. Review | Vet what you approve | Pull request review, read scripts/, search for invisible characters |
| 4. Runtime control | Govern what skills do | Export OpenTelemetry events, inspect tool calls and MCP traffic |
Conclusion
Codex skills are a light way to give the agent repeatable procedures, and they are also instructions and code that run with your access. Write precise descriptions, keep skills in the repository, and review scripts and text like a dependency. Administrators should fix the sandbox and approval policy centrally, update Codex, and add runtime inspection, because configuration decides what can run, not what a skill asks for.
Secure Codex Skills in Production with NeuralTrust
Inspect agent and MCP traffic from Codex skills with runtime controls and tool-level access policies.
)
Related Comparisons
- Claude Code Skills: The Complete Guide
- Best ChatGPT Skills
- OpenClaw Skills
- AGENTS.md Guide
- Codex vs Claude Code Benchmark
- Claude Code Plugins
FAQs about Codex Skills
1. What are Codex skills?
Codex skills are directories that package instructions for a repeatable task. Each one has a SKILL.md file with a name and description, and may add scripts, references and assets. Codex lists skills by name and description, and loads the full instructions only when it uses a skill, explicitly or because the task matches.
2. How do I create a Codex skill?
Run $skill-creator, or create a folder such as .agents/skills/your-skill with a SKILL.md file that has a name and a description. Describe when the skill should trigger, keep the body short, and move long material into references/. Test it with $your-skill and with a plain request.
3. Where do Codex skills go?
Repository skills go in .agents/skills, user skills in $HOME/.agents/skills, and administrator skills in /etc/codex/skills. Codex also bundles system skills. For a repository, Codex scans from the working directory up through parent folders to the repository root, so a skill can apply to one subfolder.
4. What is the difference between a Codex skill and AGENTS.md?
AGENTS.md holds standing guidance for a project, such as conventions and commands. A skill holds a task-specific procedure that Codex loads by name and description only when needed, and it can carry scripts. Use AGENTS.md for rules that always apply and a skill for a workflow you repeat.
5. Are Codex skills safe?
Not by default. A skill is text the agent obeys and may include scripts it can run. Public audits of other agents' skill ecosystems found flaws and malicious payloads. Read skills like code, keep Codex updated, leave the sandbox network off, and use managed configuration and runtime inspection in organizations.
6. How do I disable a Codex skill?
Set enabled to false in a [[skills.config]] entry for that skill, or in [skills.bundled] for the bundled ones. To stop Codex from picking a skill on its own, set allow_implicit_invocation to false in the skill's agents/openai.yaml, so it runs only when you call it by name.
7. Do Codex skills work in Claude Code?
Often, for simple ones. Both tools read a SKILL.md folder from the open Agent Skills format. The folder locations and call syntax differ, and scripts or settings written for one tool may not run in the other, so test a copied skill before you rely on it.
About the Author
Roger Howroyd is Head of Global SEO and AI at NeuralTrust, where he leads the company's search strategy across SEO, AEO, GEO, and LLM optimization. He specializes in AI-powered search, content strategy, and SEM. Connect on LinkedIn.
NeuralTrust is the leading platform for securing and scaling AI agents. Named a Pioneer in the Gartner Emerging Market Quadrant for AI Application Security 2026, recognized across four Gartner Hype Cycle reports in 2026, and featured in the Gartner Market Guide for Guardian Agents 2026, the Gartner Market Guide for AI Gateways 2025 and the KuppingerCole Leadership Compass for Generative AI Defense 2025. Headquartered in Barcelona with offices in London and New York. ISO 27001 certified.
Sources
Accessed on November 12, 2026.
- OpenAI, "Build skills", Codex documentation, 2026.
- OpenAI, "Agent approvals and security", Codex documentation, 2026.
- OpenAI, "Managed configuration", Codex documentation, 2026.
- OpenAI, "openai/skills", GitHub, read on November 12, 2026.
- OpenAI, "Sandbox bypass advisory GHSA-w5fx-fh39-j5rw", GitHub Security Advisories, 2025.
- Agent Skills, "Specification", 2026.
- Cloud Security Alliance AI Safety Initiative, "Agent Context Poisoning: SKILL.md and the New AI Supply Chain Attack Surface", May 6, 2026.
- OWASP GenAI Security Project, "OWASP Top 10 for LLM Applications 2026", 2026.
- OWASP GenAI Security Project, "OWASP Top 10 for Agentic Applications for 2026", 2026.
- OWASP Foundation, "OWASP Agentic Skills Top 10", version 1.0-2026.
)
)
)
)