# What are Codex skills? How to install and use them > A Codex skill is a folder with a SKILL.md file: a name, a description and the steps Codex follows when your task fits. Codex reads the name and description first and loads the rest only when it picks the skill. Install curated ones with `$skill-installer`, mention one with `$`, or drop a folder into `.agents/skills`. Mindket editors · Published 2026-11-03 · Updated 2026-11-03 · https://mindket.com/blog/codex-skills ## In short - Keep a team's skills in the repository's `.agents/skills`, and your own in `$HOME/.agents/skills`. - Write each description for the match: the job first, then the phrases people type when they want it. - Copy any `openai/skills` skill you depend on into a repository you control. The source is deprecated. ## Install a Codex skill with the skill installer Codex installs skills with a skill of its own. You type a `$skill-installer` line inside Codex, and the installer fetches the folder. The short names, such as `linear`, come from OpenAI's `openai/skills` repository. Its [README](https://github.com/openai/skills) now opens with a deprecation notice that points to OpenAI's plugins repository for current examples, but the install commands below were still in it when we read it on November 3, 2026. ````text $skill-installer linear $skill-installer gh-address-comments $skill-installer install the create-plan skill from the .experimental folder $skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan ```` 1. Start Codex in the project where you want the skill. 2. Type one of the lines above. A bare name installs from the curated folder, and a GitHub URL installs the folder it points to. 3. Read what Codex reports. The installer stops if a skill with that name is already in its folder, and it tells you the skill is available on your next turn. 4. If the skill doesn't appear, restart Codex. The README asks for a restart after every install, though the build guide says Codex usually picks up new skills by itself. 5. Run `/skills` or type `$` to mention the new skill by name. [![OpenAI Developers (@OpenAIDevs) on X, 19 December 2025. Codex now officially supports skills, which are reusable bundles of instructions, scripts and resources. You can call a skill directly or let Codex choose one from your prompt.](https://mindket.com/blog/shots/x-openaidevs-codex-skills.webp?v=a7ff5af51d63)](https://x.com/OpenAIDevs/status/2002099762536010235) OpenAI Developers on X, 19 December 2025 > Still missing after a restart? The [installer's own SKILL.md](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/SKILL.md) puts each skill under `$CODEX_HOME/skills`, `~/.codex/skills` by default. The build guide's table doesn't list that folder, and none of the pages we read says Codex scans it, so the skill may sit where Codex doesn't look. Copy it into `$HOME/.agents/skills`, the personal location the guide documents. The post above is X's own embed, shown without its video. ## What is inside a Codex skill Only `SKILL.md` is required, and it must carry a `name` and a `description`. Every other part of the layout in OpenAI's [Build skills guide](https://learn.chatgpt.com/docs/build-skills) is optional, from scripts to an `agents/openai.yaml`. OpenAI's name for Codex's two-step reading is progressive disclosure. Until a task calls for a skill, Codex holds only its name, description and file path. The [open standard](https://agentskills.io/home) behind it counts three stages: discovery, activation and execution. ````text my-skill/ ├── SKILL.md Required: instructions + metadata ├── scripts/ Optional: executable code ├── references/ Optional: documentation ├── assets/ Optional: templates, resources └── agents/ └── openai.yaml Optional: appearance and dependencies ```` **From Claude's skills launch to Codex** 1. **October 16, 2025** Claude gets Skills. Claude's own account posted that Claude can now use Skills, packaged instructions that teach it your way of working. 2. **December 19, 2025** Codex officially supports skills. OpenAI Developers called them reusable bundles of instructions, scripts and resources, which you call with `$` or let Codex choose from your prompt. Sources: [Claude on X](https://x.com/claudeai/status/1978855432123723909) (read 2026-11-03), [OpenAI Developers on X](https://x.com/OpenAIDevs/status/2002099762536010235) (read 2026-11-03) > `agents/openai.yaml` is the optional metadata file: a display name and icon for the ChatGPT desktop app, an invocation policy, and the tools the skill depends on. ## Use a skill, and what to check when Codex ignores it Codex picks a skill by itself when your task fits its `description`, which OpenAI calls implicit invocation. Naming it with `$` in Codex CLI or the IDE extension, explicit invocation, skips the match. Put the main use case and the words a user would say at the front of the description, since implicit matching depends on that one line. Say where the skill stops, too: a skill that writes PR descriptions can state that it doesn't review code. Codex may shorten a long description, and the part that survives still has to match. **The budget for the skills list in Codex** - **2%** of the model's context window is the most the starting list of skills may use (Source: [ChatGPT Learn: Build skills](https://learn.chatgpt.com/docs/build-skills), read 2026-11-03) - **8,000** characters is the budget when the window size is unknown (Source: [ChatGPT Learn: Build skills](https://learn.chatgpt.com/docs/build-skills), read 2026-11-03) - **10,000** tokens is the most `skills.max_context_tokens` can set in their place (Source: [ChatGPT Learn: Build skills](https://learn.chatgpt.com/docs/build-skills), read 2026-11-03) - Codex never picks the skill: rewrite the description, then try [prompts that should match and prompts that shouldn't](https://mindket.com/blog/how-to-create-agent-skill). - The skill runs only when you mention it: look for `allow_implicit_invocation: false` in its `agents/openai.yaml`. That setting turns off matching and leaves `$skill` working. - Skills go missing after you install many: the starting list gets at most 2% of the model's context window, or 8,000 characters when the window size is unknown. Codex shortens descriptions first and, for large sets, may leave skills out and show a warning. `skills.max_context_tokens` sets another budget, up to 10,000 tokens. ## Write a skill of your own By hand, a skill is one folder and one file. The [open specification](https://agentskills.io/specification) sets the rules: the name must match the folder, use lowercase letters, numbers and hyphens, and stay within 64 characters, and the description may run to 1,024. OpenAI also asks for one job per skill and imperative steps with explicit inputs and outputs. Record & Replay drafts a skill from a workflow you demonstrate. `$skill-creator`, the built-in creator, asks what the skill does, when it should trigger, and whether it stays instruction-only or includes scripts. ````markdown --- name: writing-pr-descriptions description: Writes a pull request description from the current branch's changes. Use when the user asks for a PR description, a PR summary or what to put in a pull request. --- # Writing PR descriptions 1. Run git diff main...HEAD --stat, then read the changed files. 2. Open with one sentence on what changed and why. 3. List the areas touched, one line each. 4. End with how to test it. If the diff adds no tests, say so. Never invent an issue number. If the branch name has none, ask for it. ```` 1. Create `.agents/skills/writing-pr-descriptions` in your repository, or `$HOME/.agents/skills/writing-pr-descriptions` for a personal skill. 2. Save the sample as `SKILL.md` inside it. 3. Check that Codex lists it: run `/skills` or type `$`. 4. Try "write a PR description for this branch", which should match, and "review this diff", which shouldn't. If the second one loads the skill, the description reaches too far. > For a finished skill to read, the guide points to [gh-fix-ci](https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci). Its folder holds SKILL.md beside agents/, assets/ and scripts/, plus a LICENSE.txt, and its description opens "Use when a user asks to debug or fix failing GitHub PR checks that run in GitHub Actions". ## Where to find Codex skills, and how to share yours Any repository can be a source, since the installer takes any GitHub folder URL. That is also the risk. [A skill can bundle scripts](https://mindket.com/blog/what-are-agent-skills), so read `SKILL.md` and everything in `scripts/` before you install one from a stranger. Its license sits in a `LICENSE.txt` in the skill's own folder, per the README. A deprecated repository like `openai/skills` can stop changing at any time. A copy saved in your own repository's `.agents/skills` doesn't depend on it, and it reaches anyone who works in that repository. When a skill has to work outside the repository it lives in, OpenAI recommends packaging it as a plugin, which can bundle two or more skills or ship one next to a connector. OpenAI's examples sit in [openai/plugins](https://github.com/openai/plugins), one folder per plugin under `plugins/`, with any skills in a `skills/` folder next to the MCP configuration. The smallest, the example in OpenAI's plugin guide, is a folder with a `plugin.json` and one skill at `skills/hello/SKILL.md`. To add a GitHub repository as a plugin marketplace, run `codex plugin marketplace add owner/repo`. Public plugins also show up in a directory shared with ChatGPT and in the plugin browser in Codex CLI. Mindket, an independent store not affiliated with OpenAI, lists skills as [kits](https://mindket.com/kits): zipped folders of text files for AI tools, so a kit built for Codex unzips into `.agents/skills`. Its [skills page](https://mindket.com/skills) holds something else, prompt skills you paste into an AI chat. > We read every page linked here and listed under Sources on November 3, 2026, and Mindket's own pages for what Mindket does. Nothing here was tested hands-on, and the sample skill was written for this guide. A deprecation notice or a folder listing can change after that day. ## Reference: where Codex looks for skills Codex reads skills from repository, user, admin and system locations. Inside a Git repository it scans `.agents/skills` in every folder from where you launched Codex up to the repository root. A skill for one microservice can sit beside that service, and a skill for the whole team sits at the root. | Scope | Location | What it is for | | --- | --- | --- | | REPO | `$CWD/.agents/skills` | The folder where you launch Codex. Skills for one microservice or module. | | REPO | `$CWD/../.agents/skills` | A folder above it, when you launch inside a Git repository. A shared area in a parent folder. | | REPO | `$REPO_ROOT/.agents/skills` | The repository's topmost folder. Root skills, available to every subfolder. | | USER | `$HOME/.agents/skills` | Your personal skills, for any repository you work in. | | ADMIN | `/etc/codex/skills` | A shared system location on a machine or container, for SDK scripts, automation and default admin skills. | | SYSTEM | Bundled with Codex | `skill-creator` and `skill-installer`, enabled by default. | > Two skills with the same `name` aren't merged: both can appear in the skill selectors. Codex also follows symlinked skill folders, so one copy can serve several projects. ## Frequently asked questions ### Can Codex use a skill written for Claude Code? Usually, because Codex skills build on the same open Agent Skills format, and the standard is meant to let one skill work in any compatible agent. Each product scans its own folders, though, so move the folder to where Codex looks. Fields only one product reads are the risk: the specification marks `allowed-tools` experimental and says support varies between agents. ### What is the difference between a skill and a plugin in Codex? A plugin is an installable package that can carry MCP servers, hooks and presentation assets beside one or more skills. OpenAI suggests one once a skill's instructions need connected services or other tools beside them. ### Do Codex skills work in the ChatGPT app? In the ChatGPT desktop app, yes: standalone skills run there, and the Skills entry in its sidebar shows the ones created across your projects. Skills bundled in a plugin also work in Chat and Work on ChatGPT's web, desktop and mobile versions. The IDE extension doesn't support plugins, so a skill that has to work there should stay a plain folder. ### How do I turn a skill off without deleting it? Add a `[[skills.config]]` entry to `~/.codex/config.toml` with the `path` to the skill's `SKILL.md` and `enabled = false`. Use exactly one selector per entry, a `path` or a `name`, and when several entries match, the last one wins. Restart Codex afterwards. To turn off the bundled system skills for one project, set `enabled = false` under `[skills.bundled]` in its trusted `.codex/config.toml`. ### Which skills come with Codex? OpenAI's build guide names two, `skill-creator` and `skill-installer`, enabled by default. The [.system folder](https://github.com/openai/skills/tree/main/skills/.system) of the openai/skills repository lists three more, `imagegen`, `openai-docs` and `plugin-creator`, when we read it, and the README says skills in that folder install automatically in the latest Codex. ### Can a Codex skill run scripts? Yes. A skill folder can hold a `scripts/` directory of executable code, and its `SKILL.md` can tell Codex to run it, as OpenAI's gh-fix-ci skill does with a Python script. OpenAI's advice is to prefer instructions unless you need deterministic behavior or external tooling, and `$skill-creator` stays instruction-only unless you ask for scripts. ## Sources - [ChatGPT Learn: Build skills](https://learn.chatgpt.com/docs/build-skills) (read 2026-11-03) - [ChatGPT Learn: Skills & Plugins](https://learn.chatgpt.com/docs/skills-and-plugins) (read 2026-11-03) - [ChatGPT Learn: Plugins](https://learn.chatgpt.com/docs/plugins) (read 2026-11-03) - [ChatGPT Learn: Skill controls](https://learn.chatgpt.com/docs/enterprise/skills) (read 2026-11-03) - [OpenAI Developers: Package your plugin](https://developers.openai.com/plugins/build/plugins) (read 2026-11-03) - [GitHub: openai/skills README](https://github.com/openai/skills) (read 2026-11-03) - [GitHub: openai/skills skill-installer SKILL.md](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/SKILL.md) (read 2026-11-03) - [GitHub: openai/skills .system folder](https://github.com/openai/skills/tree/main/skills/.system) (read 2026-11-03) - [GitHub: openai/skills .curated folder](https://github.com/openai/skills/tree/main/skills/.curated) (read 2026-11-03) - [GitHub: openai/skills gh-fix-ci](https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci) (read 2026-11-03) - [GitHub: openai/plugins README](https://github.com/openai/plugins) (read 2026-11-03) - [Agent Skills specification](https://agentskills.io/specification) (read 2026-11-03) - [Agent Skills overview](https://agentskills.io/home) (read 2026-11-03) - [Claude on X: Claude can now use Skills](https://x.com/claudeai/status/1978855432123723909) (read 2026-11-03) - [OpenAI Developers on X: Codex now officially supports skills](https://x.com/OpenAIDevs/status/2002099762536010235) (read 2026-11-03) [Browse GitHub projects](https://mindket.com/github)