How to Install a Codex Skill (2026 Guide)

The install path for a Codex skill is a folder in .agents/skills. OpenAI Codex reads SKILL.md from that tree. For curated skills OpenAI already knows, run $skill-installer inside Codex. Official steps: developers.openai.com/codex/skills (retrieved 16 August 2026).

This is a different command than Claude Code's npx skills add, which writes .claude/skills/. Same SKILL.md files, different folders. Claude install: How to install a Claude Code skill. Ranked files: Codex skills.

Key takeaways

• Copy a skill folder into .agents/skills at the repo, a parent folder, the repo root, or $HOME.
• Curated install inside Codex: $skill-installer linear (replace linear with the skill you want). You can also prompt the installer to pull a GitHub repo.
• Codex detects new folders. Restart Codex if one is missing.
• Disable without deleting: [[skills.config]] in ~/.codex/config.toml with enabled = false, then restart.
• Plugins are the distribution format when you want other people to install the skill. Local .agents/skills is for your machine and your repo.

Copy a skill folder into .agents/skills

A skill is a directory with a SKILL.md file. Place that directory in one of the paths Codex scans:

Example layout:

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

Symlinked skill folders work. If two skills share a name, Codex keeps both in selectors instead of merging them.

Open any listing on Codex skills to read the SKILL.md before you copy it. Do not treat a Claude marketplace or plugin row as a Codex install.

Install a curated skill with $skill-installer

Inside Codex CLI or the IDE extension:

$skill-installer linear

OpenAI's documented example installs the Linear skill. You can also ask the installer to download skills from other repositories. Codex should pick up the new folder; restart Codex if it does not.

Use $skill-installer for local setup. OpenAI tells authors to package plugins when they want other people to install the skill.

Create a skill instead of installing one

If you are writing the workflow:

• Invoke $skill-creator in Codex.
• Or create the folder and SKILL.md by hand. Frontmatter needs name and description.

Optional agents/openai.yaml sets display name, icon, and allow_implicit_invocation (default true). Set that flag to false if you only want $skill mentions to fire the skill.

Turn a skill off

In ~/.codex/config.toml:

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

Restart Codex after you edit the file.

Common pitfalls

• Running npx skills add and expecting Codex to see the skill. That command writes .claude/skills/. Codex does not load that tree as its skill path.
• Copying a marketplace or plugin bundle into .agents/skills. OpenAI plugins can include skills plus connectors. A plugin is not a drop-in SKILL.md folder.
• Skipping a restart after a copy or a config.toml edit.

Sources

• Use skills with ChatGPT and Codex (OpenAI, retrieved 16 August 2026)
• What are Codex skills?
• What is a Codex skill?

Skillselion is an independent directory. We are not affiliated with OpenAI, Anthropic, or Cursor.

Common questions