Codex Skills: How to Install and Use Them (2026)

Codex skills let you package a workflow (how to write a migration, how to triage an issue, how to deploy) so Codex does it your way every time. They’re built on the same open Agent Skills standard as Claude’s, and OpenAI’s docs link to it directly (OpenAI).

Where Codex finds skills

Scope	Location
Repo	.agents/skills in the current folder, every folder above it, up to the repo root
User	$HOME/.agents/skills
Admin	/etc/codex/skills
System	Bundled with Codex (for example skill-creator and plan)

Codex follows symlinked skill folders, and if two skills share a name it shows both rather than merging them. Skills work in the Codex CLI, the IDE extension and the Codex app.

Use a skill

• Explicitly: run /skills, or type $ and the skill’s name.
• Automatically: Codex picks a skill when your request matches its description. To stop that for one skill, set policy.allow_implicit_invocation: false in its agents/openai.yaml.
• In ChatGPT: type @ and select the skill.

Install and create skills

Install a published skill with the built-in installer, for example:

$skill-installer linear

The installer can also fetch skills from other repositories when you ask. To write one, run $skill-creator and describe what you want, or make the folder yourself:

---
name: triage-issue
description: Triages a new GitHub issue. Use when the user pastes an issue or asks to label, reproduce or prioritise a bug.
---

1. Restate the bug in one sentence.
2. Find the code path involved and name the files.
3. Suggest a label (bug, docs, feature) and a priority (P0–P3) with one line of reasoning.

Optional: an agents/openai.yaml file in the skill folder sets a display name, icon, default prompt, invocation policy and dependencies such as MCP servers. OpenAI recommends plugins rather than bare skills when you want to distribute them to others.

To switch a skill off, add a [[skills.config]] entry to ~/.codex/config.toml with the skill’s path and enabled = false, then restart Codex.

One skill for every agent

Because Codex, Cursor, GitHub Copilot and Gemini CLI all read .agents/skills/, keeping a team’s skills there means one copy serves everyone. Claude Code reads .claude/skills/, so add a symlink if your team mixes tools. Community skills are on skills.sh, installable with npx skills add <owner/repo>, which supports Codex among about 20 agents.

Safety

Skills can run scripts on your machine. Read every file before installing a skill you didn’t write, and prefer well-known sources. See the security section of Agent Skills explained.