OpenAI Codex supports a skill system that lets you package task-specific instructions, scripts, and resources into reusable modules. Instead of repeating the same context in every prompt, you create a skill once and Codex loads it when needed. This guide covers everything you need to build, install, and configure skills for Codex.

#What Are Skills?

A skill is a directory containing instructions that extend Codex with domain-specific capabilities. Think of it as a plugin system for your AI coding agent. Each skill has a SKILL.md file with a name, description, and the actual instructions Codex follows.

Codex uses progressive disclosure to manage context efficiently. It reads skill metadata first (name + description) and only loads the full instructions when it decides the skill is relevant to your task.

#How Codex Activates Skills

Two mechanisms:

Explicit invocation — Use $skill-name or /skills in your prompt to directly trigger a skill
Implicit invocation — Codex automatically selects a skill when your task matches its description. This is enabled by default but can be turned off per-skill.

#Skill File Structure

my-skill/
  SKILL.md          # Required — name, description, instructions
  scripts/          # Optional — executable scripts the skill can run
  references/       # Optional — reference docs the skill can read
  assets/           # Optional — icons, images, brand assets
  agents/
    openai.yaml     # Optional — UI metadata, invocation policy, tool deps

The only required file is SKILL.md. Everything else is optional.

#Creating a Skill

#The Quick Way

Codex has a built-in skill creator:

bash

$skill-creator

It walks you through what the skill does, when it should trigger, and whether it needs scripts.

#The Manual Way

Create a directory with a SKILL.md:

markdown

---
name: deploy-preview
description: Deploys the current branch to a preview environment with Vercel. Use when the user asks to deploy, preview, or ship a branch.
---
 
## Steps
 
1. Run `npx vercel --yes` to deploy to preview
2. Wait for the deployment URL
3. Run a basic health check: `curl -f <deployment-url>/api/health`
4. Report the preview URL and health check result

The frontmatter name and description are required. The description is critical — it determines when Codex activates the skill implicitly. Write it like a trigger condition: "Use when X, Y, or Z."

#Skill Scoping

Skills can be scoped to different levels. Codex scans from your current directory up to the repo root:

| Scope | Location | When to use | |-------|----------|-------------| | Repo | .agents/skills/ in current dir | Project-specific workflows | | Repo | .agents/skills/ in parent dirs | Monorepo shared skills | | Repo | .agents/skills/ at repo root | Org-wide standards | | User | ~/.agents/skills/ | Personal skills across all projects | | Admin | /etc/codex/skills/ | Machine or container defaults | | System | Bundled with Codex | Built-in OpenAI skills |

If two skills have the same name at different scopes, both appear in the skill selector — they don't merge.

Codex supports symlinked skill folders. This means you can maintain a central skills repo and symlink individual skills into different projects.

#Installing Community Skills

Use the built-in installer to pull skills from the community:

bash

$skill-installer linear

The installer downloads skills from public repos. Codex detects new skills automatically — restart your session if a newly installed skill doesn't appear.

The OpenAI Skills Catalog is the official repository of community-contributed skills.

#Advanced Configuration: openai.yaml

For skills that need UI customization, invocation control, or tool dependencies, add an agents/openai.yaml file:

yaml

interface:
  display_name: "Deploy Preview"
  short_description: "Deploy current branch to Vercel preview"
  icon_small: "./assets/vercel-icon.svg"
  brand_color: "#000000"
  default_prompt: "Deploy this branch to preview"
 
policy:
  allow_implicit_invocation: false  # Require explicit $skill invocation
 
dependencies:
  tools:
    - type: "mcp"
      value: "vercel"
      description: "Vercel deployment MCP server"
      transport: "streamable_http"
      url: "https://api.vercel.com/mcp"

Key configuration options:

allow_implicit_invocation (default: true) — Set to false if the skill should only run when explicitly called with $skill-name. Use this for destructive operations like deployments or database migrations.
dependencies.tools — Declare MCP servers the skill needs. Codex ensures they're available before activating the skill.

#Enabling and Disabling Skills

Edit ~/.codex/config.toml:

toml

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

Restart Codex after making changes.

#Best Practices

One skill, one task. Don't create a "do everything" skill. A skill that deploys AND runs tests AND generates docs is three skills pretending to be one.
Descriptions are trigger conditions. Write the description as "Use when..." not "This skill..." — Codex uses the description to decide whether to activate the skill, so be specific about when it should and shouldn't trigger.
Prefer instructions over scripts unless you need deterministic behavior or external tool integration. Natural language instructions are more flexible and easier to maintain.
Write imperative steps. "Run X, then Y, then Z" is better than "The skill should consider running X." Codex follows instructions more reliably when they're direct.
Test your descriptions. Try prompts that should and shouldn't trigger the skill. If it triggers when it shouldn't, tighten the description. If it doesn't trigger when it should, broaden it.

#Using Orellius Skills with Codex

Every skill in the Orellius AI Library can be used with Codex:

Download the .md file from any skill page
Create a directory in .agents/skills/ with the skill name
Rename the file to SKILL.md
Restart Codex

bash

mkdir -p .agents/skills/code-reviewer
cp ~/Downloads/code-reviewer.md .agents/skills/code-reviewer/SKILL.md

The skill will be available in your next Codex session.

#What's Next

Browse the OpenAI Skills Catalog for official and community skills
Read the full Agent Skills Specification for the complete standard
Explore the Orellius Skills Library for production-ready skills you can drop into any AI tool

Implementing Agent Skills for OpenAI Codex

#What Are Skills?

#How Codex Activates Skills

#Skill File Structure

#Creating a Skill

#The Quick Way

#The Manual Way

#Skill Scoping

#Installing Community Skills

#Advanced Configuration: openai.yaml

#Enabling and Disabling Skills

#Best Practices

#Using Orellius Skills with Codex

#What's Next