Codex Skills & Plugins: Extend Your Agent

Key Takeaways#

• Skills are the atomic extension unit in Codex, defined by a SKILL.md file with YAML frontmatter and markdown instructions.
• Five storage locations determine where skills live and their scope: REPO, USER, ADMIN, SYSTEM, and bundled defaults.
• Implicit invocation activates skills automatically when relevant; explicit invocation uses $skill-name for precise control.
• $skill-creator is a built-in skill for scaffolding new skills; $skill-installer installs curated skills from the community registry.
• Plugins bundle skills, apps, and MCP servers into a single distributable package, managed via /plugins or the Codex app.
• agents/openai.yaml carries metadata like display_name, dependencies, and policy that govern how OpenAI agents interact with the skill.
• Skills can be enabled or disabled per-project in config.toml under the [skills] section.

---

Understanding the Codex Skills System#

Codex's extensibility model centers on skills -- self-contained units of instruction that teach the agent how to perform specialized tasks. A skill is not a function call or a traditional plugin hook; it is a structured document that injects context, procedures, and reference material into the agent's working memory at the right moment. This design lets you extend what Codex knows and how it behaves without modifying core code.

The SKILL.md Format#

Every skill is anchored by a SKILL.md file. This file uses YAML frontmatter for machine-readable metadata followed by a markdown body that the agent reads as instructions. The frontmatter typically includes:

• name: A unique identifier for the skill, used in explicit invocation (e.g., deploy-kubernetes).
• description: A concise summary that Codex uses to decide whether the skill is relevant to the current task.

The markdown body contains the actual instructions -- step-by-step procedures, decision trees, code templates, constraints, and any contextual knowledge the agent needs. Because this is standard markdown, you can use headers, code blocks, tables, and embedded references to make the instructions as rich and structured as necessary.

---
name: deploy-kubernetes
description: Deploy containerized applications to Kubernetes clusters with best-practice manifests
---

## Deployment Workflow

1. Verify kubectl context points to the target cluster.
2. Generate or retrieve manifests from the references/ directory.
3. Apply manifests with kubectl apply -f.
4. Wait for rollout and validate with kubectl rollout status.

Directory Structure#

A well-organized skill follows this layout:

my-skill/
  SKILL.md          # Required: frontmatter + instructions
  scripts/          # Executable scripts the skill can invoke
  references/       # Templates, schemas, config examples
  assets/           # Non-code resources (diagrams, sample data)
  agents/
    openai.yaml     # Agent-specific metadata

• SKILL.md is the only required file. Everything else is optional but strongly recommended for non-trivial skills.
• scripts/ holds shell scripts, Python files, or any executable the skill references. Codex can run these directly when the skill instructs it to.
• references/ stores static assets like YAML templates, JSON schemas, or configuration snippets that the skill injects into prompts or passes to scripts.
• assets/ contains supplementary files -- architecture diagrams, example datasets, or documentation images that help the agent reason about the task.
• agents/openai.yaml provides agent-specific configuration. This is where you declare how OpenAI-powered agents should interact with the skill, including display naming, dependency declarations, and execution policy (see below).

Skill Storage Locations#

Codex resolves skills from five distinct locations, each with a different scope and management model:

When multiple locations define a skill with the same name, precedence follows the order REPO > USER > ADMIN > SYSTEM. This lets project-specific skills override user or system-level ones, similar to how .env files layer in configuration.

Invocation: Implicit vs. Explicit#

Skills can be activated in two ways:

Implicit invocation is the default. When a user request matches a skill description, Codex automatically loads the skill instructions into context. For example, if you have a skill with description: "Set up CI/CD pipelines using GitHub Actions", asking Codex to "create a CI pipeline for my repo" will implicitly activate that skill. No special syntax is required.

Explicit invocation gives you direct control. Type $skill-name (with the dollar sign prefix) to force-load a specific skill regardless of context relevance. This is useful when you want to use a skill that might not match the natural language of your request, or when multiple skills could apply and you want to be precise. For instance, $deploy-kubernetes guarantees that the Kubernetes deployment skill is loaded even if your prompt is simply "ship this."

Built-in Skills: $skill-creator and $skill-installer#

Codex ships with two built-in skills designed to help you manage the skill ecosystem:

$skill-creator scaffolds a new skill from scratch. When you invoke $skill-creator, Codex prompts you for a name and description, then generates the full directory structure -- SKILL.md with proper frontmatter, empty scripts/, references/, and assets/ directories, and a starter agents/openai.yaml. This ensures every new skill follows the standard layout from day one.

$skill-installer installs curated skills from the community registry. Running $skill-installer presents a searchable catalog of vetted skills contributed by other users. Select one, and Codex downloads it into the appropriate location (USER by default, or REPO if you specify --local). The installer also resolves dependencies -- if a skill requires another skill or an MCP server, $skill-installer will prompt you to install those as well.

Plugins: Bundling Skills, Apps, and MCP Servers#

While skills are powerful on their own, plugins provide a higher-level packaging mechanism. A plugin bundles one or more skills together with:

• Apps: Pre-configured application integrations (e.g., a PostgreSQL app that provides connection details and schema introspection).
• MCP Servers: Model Context Protocol servers that expose additional tools and data sources to the agent.

This bundling means a single plugin install can give Codex the ability to, say, deploy to AWS -- the skill provides the instructions, the app holds AWS credentials and region configuration, and the MCP server exposes CloudFormation and EC2 tools.

Installing Plugins#

Plugins can be installed in two ways:

1. Via the /plugins CLI command: Run /plugins install to fetch and install a plugin from the registry. Codex handles downloading the package, placing skills in the correct directories, registering MCP servers, and configuring apps.

2. Via the Codex app: The desktop or web app includes a plugin browser where you can search, preview, and install plugins with a single click. The app also shows dependency trees and permissions before installation.

Enabling and Disabling Plugins and Skills#

Not every installed skill or plugin needs to be active all the time. Codex uses config.toml for fine-grained control:

[skills]
# Explicitly enable or disable skills by name
deploy-kubernetes = true
legacy-deploy = false

[plugins]
# Enable or disable entire plugins
aws-toolkit = true
experimental-ml = false

When a skill is disabled, it will not be considered for implicit invocation and cannot be called with explicit invocation. When a plugin is disabled, all its bundled skills, apps, and MCP servers are deactivated together. This is useful for managing performance (fewer skills means less context overhead) and for turning off skills that conflict with a particular project conventions.

Building Custom Plugins#

Creating your own plugin involves three steps:

1. Define the skills -- Write one or more SKILL.md files following the standard format and directory structure.
2. Add agent metadata -- Create agents/openai.yaml for each skill (or a shared one for the plugin) that specifies how OpenAI agents should handle the skill.
3. Package and distribute -- Bundle the skills, any supporting apps, and MCP server configurations into a plugin directory. Publish to the community registry or distribute the directory privately.

The agents/openai.yaml file is particularly important for OpenAI-compatible agents. It contains:

• display_name: A human-readable name shown in the Codex UI (e.g., "AWS Deployment Toolkit").
• dependencies: A list of other skills, apps, or MCP servers this skill requires. Codex checks these at load time and warns if any are missing.
• policy: Execution policy rules -- for example, whether the skill requires user confirmation before running scripts, or whether it is allowed to modify files outside the project directory.

display_name: "AWS Deployment Toolkit"
dependencies:
  - skill: docker-build
  - mcp: aws-cloudformation
policy:
  require_confirmation: true
  file_scope: project-only
  max_execution_time: 300

Skills in config.toml: Full Control#

Beyond the simple enable/disable toggle, config.toml supports advanced skill configuration:

[skills.deploy-kubernetes]
enabled = true
invocation = "explicit"   # Force explicit-only; never auto-activate
priority = 10             # Higher priority wins when multiple skills match

[skills.code-review]
enabled = true
invocation = "implicit"   # Auto-activate when relevant
priority = 5

Setting invocation = "explicit" for a skill means it will never be implicitly activated -- it can only be invoked with $skill-name. The priority field resolves conflicts when two skills could both apply to a request; higher-priority skills are preferred.

Best Practices#

• Keep skills focused: Each skill should handle one domain or workflow. A "deploy" skill that covers Kubernetes, ECS, and bare metal is harder to maintain than three separate skills.
• Use references over inline content: Store large templates and schemas in references/ rather than embedding them in SKILL.md. This keeps the instruction body concise and the agent context window efficient.
• Test with explicit invocation first: When developing a new skill, invoke it explicitly to verify behavior before relying on implicit activation. This isolates issues and speeds iteration.
• Leverage $skill-creator: Do not hand-create the directory structure. $skill-creator ensures consistency and catches common mistakes like missing frontmatter fields.
• Version your REPO skills: Since REPO-level skills live in .agents/skills/, they are checked into git. Tag them in your changelog and treat them like any other project artifact.
• Document dependencies in openai.yaml: Always declare what your skill needs in the dependencies field. This prevents cryptic failures when a required MCP server or companion skill is missing.