OpenAI Skills Explained, Installation, and Usage

What Are Skills?

When using AI tools, there will inevitably be moments when you repeatedly enter the same prompt. Asking for code reviews, generating test code, and analyzing logs are all tasks where explaining the same thing every time is less efficient than it seems.

The key to solving this problem is “Skills.” Simply put, a Skill is a feature that turns frequently used work into a single reusable command.

Once created well, you can get the same result with a short trigger instead of explaining it at length every time.

In other words, Skills are a format for writing reusable workflows, and they can be used not only in Codex CLI but also in IDE extensions and the Codex app.

Core Structure

A Skill may look complex, but the structure is simple. The core is the flow of “input -> processing -> output.”

• Input: User request, such as “make tests for this code”
• Processing: Defined prompt logic
• Output: Result, such as test code or an explanation

The important point is that a Skill does not simply save a prompt. It also includes the role, rules, and output format.

For example, the difference between a simple request and a Skill is as follows.

General request:

• “Make test code for this code”

Skill:

• Role: Test code expert
• Rules: Use Kotest and consider WebFlux
• Output: Immediately executable code

This one difference can completely change the quality of the result.

Installing Skills

Skills can be installed easily with commands or by directly placing files.

Method 1: Install from the Official Catalog

The official OpenAI Codex skill catalog is a folder-structured module that bundles instructions, scripts, and resources so AI agents can repeatedly perform specific tasks.

You can find the Codex skill catalog in the official GitHub repository, openai/skills.

• https://github.com/openai/skills

To install a Skill in Codex, run $skill-installer.

$skill-installer {skill-name}

For example, to install a skill named screenshot, run:

$skill-installer screenshot

When executed, files such as the Markdown specification (SKILL.md) are created under ~/.codex/skills/.

The following files are created when the screenshot Skill is installed.

.codex
└── skills
    └── screenshot
        ├── agents
        │   └── openai.yaml
        ├── assets
        │   ├── screenshot-small.svg
        │   └── screenshot.png
        ├── LICENSE.txt
        ├── scripts
        │   ├── ensure_macos_permissions.sh
        │   ├── macos_display_info.swift
        │   ├── macos_permissions.swift
        │   ├── macos_window_info.swift
        │   ├── take_screenshot.ps1
        │   └── take_screenshot.py
        └── SKILL.md

After installation, restart Codex and it can be used immediately.

Method 2: Install by Entering a GitHub URL

You can also install by entering a GitHub URL directly.

$skill-installer https://github.com/openai/skills/tree/main/skills/.curated/{skill-name}

Method 3: Add Directly to the Project Root

Create a .agents/skills/ folder at the project root and place the skill folder there. If this is pushed to Git, all team members can use it immediately.

Using Skills in Codex

Codex can use skills in two ways.

Explicit Invocation

In the CLI or IDE, you can explicitly call a skill by entering ${skill-name} in the prompt.

For example, to use the screenshot skill:

$screenshot https://www.devkuma.com --fullpage

Alternatively, use the /skills command to view and select from the list of available skills.

Implicit Invocation

If you describe the task, Codex automatically finds and runs a suitable skill.

For example, if you say “Apply the comments on this PR,” the gh-address-comments skill is automatically executed.

• If the task matches a skill’s description, Codex automatically selects it.

Implicit matching depends on the description in the skills/SKILL.md file.

Basic Skill File Structure

Codex first refers only to each skill’s name, description, and file path. It loads the full contents of SKILL.md only when it decides to use that skill.

Codex includes a list of available skills in the initial context so it can select the right skill. This list is limited so it does not take up too much prompt space, roughly 2% of the full context or up to 8,000 characters. If there are many skills, descriptions are shortened first. If there are too many, some skills are excluded from the list and a warning is shown.

This limit applies only to the initial skill list. Once Codex selects a specific skill, it reads the full SKILL.md.

A skill is a directory made up of a SKILL.md file plus optional scripts and resources.

my-skill/
├── SKILL.md        # Required: instructions + metadata
├── scripts/        # Optional: executable code
├── references/     # Optional: documents
├── assets/         # Optional: templates, resources
└── agents/
    └── openai.yaml # Optional: UI and dependency settings

• SKILL.md
  • Required file containing name, description, and the core procedure Codex should follow.
• scripts/
  • Optional, used when the same code would otherwise be written repeatedly.
  • Good examples include collecting changed files, organizing PR metadata, or running a specific test.
• references/
  • Optional place for reference materials.
  • Good examples include RLS policy check criteria, a team’s API contract, or deployment policy.
• assets/
  • Optional place for templates or resources used in outputs.
  • Examples include review comment templates, PR description templates, and report format files.

Creating a Skill

Official skills alone may not be enough. You may need custom skills for your own or your team’s workflow.

To create a custom skill, you need to create the SKILL.md file described above.

How to write SKILL.md:

---
name: skill-name
description: Clearly explain when this skill should and should not run
---

Write the skill instructions Codex should follow

The description is the most important part. Since implicit matching depends on this description, it must be clear and concise.

• Put core use cases near the beginning
• Write trigger keywords clearly
• Make it matchable even if the description is shortened
• Include both Korean and English keywords
• List expressions that users are likely to enter
• Also state what the skill does not do to prevent incorrect matching

Description example:

description: "Automatically applies PR review comments. Reacts to '리뷰 반영', 'PR 코멘트', 'address comments', 'fix review'. Does not perform the code review itself."

Create with the Basic Generator

You can write SKILL.md directly, but using the basic generator is recommended.

$skill-creator

The generator asks:

• What the skill does
• When it should run
• Whether to include scripts; the default is instruction-only

Codex automatically detects skill changes. If changes are not reflected, restart Codex.

Skill Storage Locations

Codex loads Skills from several locations.

Codex also supports symlinked skill folders.

These locations are for local development and exploration. If you want external distribution, it is better to use a plugin.

Optional Metadata

If you add agents/openai.yaml, you can configure UI and policy settings.

interface:
  display_name: "Name shown to users"
  short_description: "Short description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Default prompt"

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"

• Default value of allow_implicit_invocation: true
• If set to false, automatic invocation is disabled, while explicit invocation remains possible.

Enabling and Disabling Skills

If there is a skill you do not want, you can disable it in ~/.codex/config.toml instead of deleting it.

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

Restart Codex after changing the setting.

Distributing Skills as Plugins

Local skill folders are suitable for development and testing.

Packaging as a plugin is useful in cases such as:

• Distributing reusable skills
• Bundling multiple skills together
• Including app integrations

A plugin can include:

• Multiple skills
• App mappings
• MCP server settings
• UI assets

Using Claude Skills in Codex

Because both Claude and Codex tools follow the same Agent Skills open standard (agentskills.io), they use the same SKILL.md format, and Anthropic’s Skills repository can also be used in Codex.

The method is simple:

1. Clone the Claude Skills repository into .agents/skills/.
2. Add a list-skills script.
   • It reads SKILL.md files in the skills folder and outputs JSON.
3. Add an instruction to AGENTS.md: “Run list-skills to check available skills.”

This allows skills made for Claude Code to be used in Codex as they are. However, this is a usage method discovered by the community, and it is not an officially supported interoperability feature from OpenAI or Anthropic.

Basic skills can be mutually compatible. However, each tool’s extensions, such as Claude Code’s allowed-tools and Codex’s .system directory, may not be compatible.

Claude Code Skills vs Codex Skills

Practical Productivity Uses

Skills can be used in Codex CLI, IDE extensions, and the Codex app.

What matters more than simply creating them is where they are used. Here are a few cases where the effect was significant.

1. Automated log analysis
   • WebFlux logs are difficult to analyze because of asynchronous flow. If you create a Skill as a “log interpretation expert,” it can explain complex logs structurally.
2. Standardized test code
   • Skills can solve the problem of each team having a different test style. If rules are enforced, all code is generated in the same style.
3. Removing repetitive work
   • API documentation generation
   • Error message analysis
   • Code refactoring suggestions

If these tasks are turned into Skills, they can be handled almost at an automation level.

The key is to set a rule: “Always create a Skill for tasks you do often.”

Summary: Codex Skills Are a Core Tool for Developer Productivity

Codex Skills are not just a prompt-saving feature. They are a powerful tool for automating repetitive work and standardizing output quality.

At first, creating just one is enough. Start with the task you do most often, such as test code generation, log analysis, or code review.

Once you get used to them, the development flow changes enough to make you wonder why you did not use them earlier.

FAQ

Q1. When is it good to use Codex Skills?

If you make the same request more than three times repeatedly, it is better to turn it into a Skill immediately. It is especially effective for tasks such as test code generation, documentation, and log analysis.

Q2. If there are many Skills, does management become difficult?

That is why naming and purpose definition are important. Clear names such as “test-webflux” and “log-analyzer” make management easier.

Q3. Can beginners use them right away?

Yes. You only need to clearly define Role, Rules, and Output without complex logic. In fact, Skills can be especially helpful for beginners because they reduce repetitive work.