Primary navigation

Agent Skills

Give Codex new capabilities and expertise

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. You can share skills across teams or with the community. Skills build on the open agent skills standard.

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.

  • my-skill/
    • SKILL.md Required: instructions + metadata
    • scripts/ Optional: executable code
    • references/ Optional: documentation
    • assets/ Optional: templates, resources
    • agents/
      • openai.yaml Optional: appearance and dependencies

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.

Skill ScopeLocationSuggested use
REPO$CWD/.agents/skills
Current working directory: where you launch Codex.		If you’re in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module.
REPO$CWD/../.agents/skills
A folder above CWD when you launch Codex inside a Git repository.		If you’re in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder.
REPO$REPO_ROOT/.agents/skills
The topmost root folder when you launch Codex inside a Git repository.		If you’re in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository.
USER$HOME/.agents/skills
Any skills checked into the user’s personal folder.		Use to curate skills relevant to a user that apply to any repository the user may work in.
ADMIN/etc/codex/skills
Any skills checked into the machine or container in a shared, system location.		Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine.
SYSTEMBundled with Codex by OpenAI.Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start Codex.

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

Install skills

To install skills beyond the built-ins, use $skill-installer:

$skill-installer install the linear skill from the .experimental folder

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.

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 for UI and dependencies

To configure skill appearance in the Codex app or declare MCP dependencies, add agents/openai.yaml:

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"

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

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.