---
title: "How to Install a Codex Skill (2026 Guide) · Skillselion"
canonical: https://skillselion.com/guides/how-to-install-a-codex-skill
content_type: text/markdown
description: "Install a Codex skill by copying its folder into .agents/skills, or run $skill-installer inside Codex (example: $skill-installer linear)."
---

# How to Install a Codex Skill (2026 Guide)

Title: How to Install a Codex Skill (2026 Guide) · Skillselion

> Install a Codex skill by copying its folder into .agents/skills, or run $skill-installer inside Codex (example: $skill-installer linear).

Canonical: https://skillselion.com/guides/how-to-install-a-codex-skill

Install a Codex skill by copying its folder into .agents/skills, or run $skill-installer inside Codex (example: $skill-installer linear). Codex scans repo, user, and system skill directories. Restart Codex if a new skill does not appear. Official: developers.openai.com/codex/skills.

## Key facts

- Last updated: August 16, 2026

## Article

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](https://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](/guides/how-to-install-a-claude-skill). Ranked files: [Codex skills](/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:

| Scope | Location |
| --- | --- |
| This folder | `$CWD/.agents/skills` |
| Parent folders in a git repo | `.agents/skills` walking up to `$REPO_ROOT/.agents/skills` |
| Your user account | `$HOME/.agents/skills` |
| This machine | `/etc/codex/skills` |

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](/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](https://developers.openai.com/codex/skills) (OpenAI, retrieved 16 August 2026)
- [What are Codex skills?](/guides/what-are-codex-skills)
- [What is a Codex skill?](/glossary/codex-skill)

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

## Related

- [/codex-skills](https://skillselion.com/guides//codex-skills)
- [/guides/what-are-codex-skills](https://skillselion.com/guides//guides/what-are-codex-skills)
- [/guides/what-are-openai-skills](https://skillselion.com/guides//guides/what-are-openai-skills)
- [/guides/how-to-install-a-claude-skill](https://skillselion.com/guides//guides/how-to-install-a-claude-skill)
- [/guides/what-are-claude-code-skills](https://skillselion.com/guides//guides/what-are-claude-code-skills)
- [/glossary/codex-skill](https://skillselion.com/guides//glossary/codex-skill)
- [/chatgpt-skills](https://skillselion.com/guides//chatgpt-skills)
- [/skills](https://skillselion.com/guides//skills)

## FAQ

### How do I install a Codex skill?

Copy the skill folder into .agents/skills (repo, parent, repo root, or $HOME), or run $skill-installer inside Codex. Restart Codex if the skill does not appear. Official: developers.openai.com/codex/skills.

### What is $skill-installer?

$skill-installer is Codex's built-in command for curated local skills. OpenAI's example is $skill-installer linear. You can also prompt it to download a repository.

### Where should I put a Codex skill on disk?

Codex reads .agents/skills from the current working directory up to the git root, then $HOME/.agents/skills, /etc/codex/skills, and bundled system skills.

### Why doesn't Codex see a skill I installed for Claude Code?

Claude Code writes .claude/skills via npx skills add. Codex reads .agents/skills. Copy the SKILL.md folder into a Codex path, or use $skill-installer.

### How do I disable a Codex skill?

Add a [[skills.config]] entry in ~/.codex/config.toml with path and enabled = false, then restart Codex.

## Machine access

- [Sitemap](https://skillselion.com/sitemap.xml)
- [llms.txt](https://skillselion.com/llms.txt)
- [llms-full.txt](https://skillselion.com/llms-full.txt)
- [Developer resources](https://skillselion.com/developers)
- [OpenAPI spec](https://skillselion.com/openapi.json)
- [MCP handshake](https://skillselion.com/.well-known/mcp)
- [API catalog](https://skillselion.com/.well-known/api-catalog)
- [AI catalog](https://skillselion.com/.well-known/ai-catalog.json)
- [Pricing](https://skillselion.com/pricing.md)
- [Auth](https://skillselion.com/auth.md)
- [AGENTS.md](https://skillselion.com/AGENTS.md)
- [Contact](https://skillselion.com/contact)
- [Home](https://skillselion.com/)
