Quick Start: Codex Skills

Install Codex skills when you want Codex to follow a reusable workflow, load task-specific instructions, or bring supporting scripts and references into a session.

For the official reference, see Agent Skills in the OpenAI Codex docs.

What a skill is

A skill is a folder with a required SKILL.md file and optional supporting files:

my-skill/
  SKILL.md
  scripts/
  references/
  assets/
  agents/
    openai.yaml

SKILL.md contains the skill metadata and instructions. It must include name and description frontmatter so Codex can decide when to use it.

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

Skill instructions for Codex to follow.

Codex uses progressive disclosure for skills. It starts with each skill's name, description, and file path, then reads the full SKILL.md only when the skill is selected.

Install curated skills

For local setup and experimentation, use the built-in installer from a Codex session:

$skill-installer linear

You can also ask $skill-installer to install skills from another repository:

$skill-installer install a skill from github.com/{owner}/{repo}

Codex detects newly installed skills automatically. If a skill does not appear, restart Codex.

Install a repo skill

Use repo-scoped skills when the workflow belongs with the codebase and should be shared by the team.

Create the folder under the repository root:

.agents/skills/my-skill/SKILL.md

Example:

mkdir -p .agents/skills/release-checklist

Then add .agents/skills/release-checklist/SKILL.md:

---
name: release-checklist
description: Use when preparing a release branch, verifying changelog entries, and checking release gates.
---

Follow the repository release checklist before marking a release ready.

Codex scans .agents/skills from the current working directory up to the repository root, so nested projects can have local skills while the root can provide shared team skills.

Install a user skill

Use user-scoped skills for personal workflows that should be available across repositories.

$HOME/.agents/skills/my-skill/SKILL.md

Example:

mkdir -p ~/.agents/skills/personal-review

Then add ~/.agents/skills/personal-review/SKILL.md.

Admin and system skills

Codex also reads admin and system-level skills:

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

Enable or disable a skill

Disable a skill without deleting it by adding a [[skills.config]] entry to ~/.codex/config.toml:

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

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

Optional app metadata

Add agents/openai.yaml when you want Codex app metadata, invocation policy, or declared tool dependencies:

interface:
  display_name: "Release Checklist"
  short_description: "Release readiness workflow"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Run the release checklist."

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "private-mcp"
      description: "Private MCP server"
      transport: "streamable_http"
      url: "https://{your-private-mcp-host}/mcp"

Set allow_implicit_invocation: false when the skill should only run after an explicit $skill-name mention.

Skills vs plugins

Use direct skill folders for local authoring, repo-scoped workflows, and personal setup.

Use plugins when you want to distribute reusable skills, bundle multiple skills together, or ship skills alongside app mappings, MCP server configuration, or presentation assets.

Verify installation

In Codex CLI or the IDE extension:

1. Run /skills or type $ to open the skill selector.
2. Confirm the new skill appears by name.
3. Invoke it directly with $skill-name.
4. If it does not appear, restart Codex and check the skill path.

For skills that depend on MCP tools, verify the MCP server separately with /mcp. See the Codex MCP quick start for MCP setup.