Codex skills: where Codex reads them, how to install one and how to write your own

Codex skills are folders with a SKILL.md file that teach OpenAI's Codex how to do one specific task. Codex reads them from .agents/skills in your repository and from ~/.agents/skills in your home folder, picks one when your request matches its description, and lets you call one directly with $ and its name. They use the same open Agent Skills format as Claude, so most skills work in both.

Everything below reflects OpenAI's Codex docs as of October 2026.

Where Codex reads skills from

Codex looks in these places:

If two skills share a name, Codex doesn't merge them; both can show up when you pick a skill. The user folder isn't named after Codex, which makes it a natural place for skills you also use with other agents that follow the standard. Check each agent's docs for the folders it reads.

Standalone skills work in the Codex CLI, the IDE extension and Codex in the ChatGPT desktop app, which absorbed the separate Codex desktop app in 2026. Skills packaged in plugins also work in ChatGPT on the web and on mobile.

How to use a skill in Codex

There are two ways to run one:

• Let Codex choose. When your request matches a skill's description, Codex loads it on its own. Ask "what shipped this week?" and a changelog skill can run without being named.
• Call it by name. In the CLI or the IDE extension, type $ and pick the skill, or run /skills to browse what is installed. $weekly-seo-report last week only runs that skill with your note attached.

Codex loads skills progressively. At the start of a session it reads only each skill's name, description and path, and opens the full SKILL.md once it decides to use one. That initial list is capped at about 2% of the context window by default; skills.max_context_tokens in config.toml raises the cap to at most 10,000 tokens if you install many skills.

New and edited skills are usually picked up automatically. If one doesn't appear, restart Codex.

How to install Codex skills

With the built-in installer. Codex ships a $skill-installer skill. $skill-installer linear installs OpenAI's curated Linear skill, and you can ask the installer to fetch a skill from another repository.

By copying a folder. A skill is just a directory, so installing one means putting it in the right place:

mkdir -p ~/.agents/skills/release-notes
cp -R ./release-notes/. ~/.agents/skills/release-notes/

From this site's library. Every skill in the skills library has a one-line installer. It writes the skill to ~/.agents/skills/ for Codex, and to ~/.claude/skills/ as well when Claude Code is installed:

curl -fsSL https://briefkin.dev/skills/jira-weekly-status-report/install | sh

For a team, commit the skill folder to .agents/skills/ in the repository instead, so everyone who opens the project in Codex gets the same version.

Turn a skill off without deleting it

To keep a skill on disk but stop Codex from using it, add an entry to ~/.codex/config.toml with the path to its SKILL.md, then restart Codex:

[[skills.config]]
path = "/Users/you/.agents/skills/release-notes/SKILL.md"
enabled = false

How to write a Codex skill

The format is the open Agent Skills standard, the same one Claude uses. name and description are required, and the body is plain Markdown:

---
name: release-notes
description: Drafts release notes from pull requests merged since the last tag. Use when the user asks for release notes, a changelog or what shipped.
---

1. Find the last tag with `git describe --tags --abbrev=0` and the date it was created.
2. List PRs merged since then with `gh pr list --state merged --search "merged:>=YYYY-MM-DD"`.
3. Group them under Features, Fixes and Internal, one line each with the PR number.
4. Leave out dependency bumps unless they fix a security issue.

A few habits make a skill trigger reliably and run well:

• Make the description specific. It is all Codex sees when it decides, so include the phrases people actually type.
• Name real commands and filters. "Use gh pr list --state merged" beats "look at recent PRs".
• Say what to do when data is missing, so the agent stops and reports instead of guessing.
• Keep SKILL.md short and move long references into files next to it, which Codex opens only when needed.

For interface labels, or to stop Codex from picking a skill on its own, add an optional agents/openai.yaml beside SKILL.md. Its policy.allow_implicit_invocation setting defaults to true; set it to false for a skill that should run only when called by name.

You can also let Codex write the file: $skill-creator asks what the skill should do, when it should trigger and whether it needs scripts, then creates it. Instruction-only skills are its default.

Codex skills compared with Claude skills

Codex and Claude Code read the same SKILL.md format, so a skill written for one usually runs in the other. The differences sit around the edges:

When you move a skill from Claude Code to Codex, check for instructions that name Claude-only tools and for frontmatter keys Codex ignores, such as disable-model-invocation. Skills written as plain steps with real commands travel best. For the format itself, see what Claude skills are.

Run a Codex skill on a schedule

Many skills are reports you want every Monday, not on request. codex exec runs Codex without the interactive interface, so cron can start it:

0 10 * * 1 cd ~/reports && codex exec --sandbox workspace-write "Run the weekly-seo-report skill"

Two things trip people up. First, the workspace-write sandbox has no network access by default, so a skill that calls an API or posts its result fails until you allow it in ~/.codex/config.toml:

[sandbox_workspace_write]
network_access = true

Second, codex exec expects to run inside a Git repository. Add --skip-git-repo-check when you run it from a plain folder like ~/reports.

If the skill reads an app through MCP, add that server to Codex as well; Claude Code MCP setup covers codex mcp add next to the Claude Code commands. The library's skills end by posting one card to your Briefkin board when BRIEFKIN_TOKEN is set, so Monday's report is waiting on your phone instead of in a terminal log. Without a token, they simply print the report.