Agent Skills

Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the open agent skills standard.

Skills are the authoring format for reusable workflows. Plugins are the installable distribution unit for reusable skills and apps in Codex. Use skills to design the workflow itself, then package it as a plugin when you want other developers to install it.

Skills are available in the Codex CLI, IDE extension, and Codex app.

Skills use progressive disclosure to manage context efficiently: Codex starts with each skill’s metadata (name, description, file path, and optional metadata from agents/openai.yaml). Codex loads the full SKILL.md instructions only when it decides to use a skill.

A skill is a directory with a SKILL.md file plus optional scripts and references. The SKILL.md file must include name and description.

How Codex uses skills

Codex can activate skills in two ways:

1. Explicit invocation: Include the skill directly in your prompt. In CLI/IDE, run /skills or type $ to mention a skill.
2. Implicit invocation: Codex can choose a skill when your task matches the skill description.

Because implicit matching depends on description, write descriptions with clear scope and boundaries.

Create a skill

Use the built-in creator first:

$skill-creator

The creator asks what the skill does, when it should trigger, and whether it should stay instruction-only or include scripts. Instruction-only is the default.

You can also create a skill manually by creating a folder with a SKILL.md file:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

Codex detects skill changes automatically. If an update doesn’t appear, restart Codex.

Where to save skills

Codex reads skills from repository, user, admin, and system locations. For repositories, Codex scans .agents/skills in every directory from your current working directory up to the repository root. If two skills share the same name, Codex doesn’t merge them; both can appear in skill selectors.

Codex supports symlinked skill folders and follows the symlink target when scanning these locations.

These locations are for authoring and local discovery. When you want to distribute reusable skills beyond a single repo, or optionally bundle them with app integrations, use plugins.

Distribute skills with plugins

Direct skill folders are best for local authoring and repo-scoped workflows. If you want to distribute a reusable skill, bundle two or more skills together, or ship a skill alongside an app integration, package them as a plugin.

Plugins can include one or more skills. They can also optionally bundle app mappings, MCP server configuration, and presentation assets in a single package.

Install curated skills for local use

To add curated skills beyond the built-ins for your own local Codex setup, use $skill-installer. For example, to install the $linear skill:

$skill-installer linear

You can also prompt the installer to download skills from other repositories. Codex detects newly installed skills automatically; if one doesn’t appear, restart Codex.

Use this for local setup and experimentation. For reusable distribution of your own skills, prefer plugins.

Enable or disable skills

Use [[skills.config]] entries in ~/.codex/config.toml to disable a skill without deleting it:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Restart Codex after changing ~/.codex/config.toml.

Optional metadata

Add agents/openai.yaml to configure UI metadata in the Codex app, to set invocation policy, and to declare tool dependencies for a more seamless experience with using the skill.

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

allow_implicit_invocation (default: true): When false, Codex won’t implicitly invoke the skill based on user prompt; explicit $skill invocation still works.

Best practices

• Keep each skill focused on one job.
• Prefer instructions over scripts unless you need deterministic behavior or external tooling.
• Write imperative steps with explicit inputs and outputs.
• Test prompts against the skill description to confirm the right trigger behavior.

For more examples, see github.com/openai/skills and the agent skills specification.