How to install Codex skills

The cleanest way to install a curated Codex skill is to use $skill-installer. For a skill folder you already downloaded, copy the complete directory into $HOME/.agents/skills/ for personal use or .agents/skills/ inside a repository. Current Codex versions discover skills from .agents/skills, not .codex/skills.

This guide covers both installation paths and the checks to run when a skill does not appear.

Know what a Codex skill contains

A Codex skill is a directory with a required SKILL.md entrypoint. It can also carry supporting material:

seo-landing-page-audit/
├── SKILL.md
├── references/
│   └── audit-rubric.md
├── scripts/
│   └── collect-page-data.sh
├── assets/
│   └── report-template.md
└── agents/
    └── openai.yaml

The SKILL.md frontmatter needs a name and description. Codex initially sees that metadata and loads the full instructions when the skill is selected. Supporting files stay out of the main context until the workflow needs them.

Read the entrypoint and any scripts before installing an unfamiliar skill. Check its tool dependencies, expected permissions, external services, and output paths. A useful skill should make those boundaries obvious.

Install with the built-in skill installer

Use the built-in installer when the skill is in a supported curated list or a GitHub repository. In Codex, invoke:

$skill-installer

Then ask it to list available skills or install the specific skill you want. You can also give it a GitHub repository path. For example:

Use $skill-installer to install the linear skill.

The installer is the easiest path because it handles the destination and folder layout for you. Codex should detect the installed skill automatically. If it does not appear, restart Codex.

OpenAI documents this workflow in its current Codex skills guide.

Install a personal Codex skill manually

Personal skills are available across repositories for your user account. Copy the skill directory into $HOME/.agents/skills/:

mkdir -p ~/.agents/skills
cp -R seo-landing-page-audit ~/.agents/skills/

Verify that SKILL.md sits directly inside the installed directory:

ls ~/.agents/skills/seo-landing-page-audit/SKILL.md

Avoid an extra wrapper directory created by some ZIP tools. Codex expects this:

~/.agents/skills/seo-landing-page-audit/SKILL.md

Not this:

~/.agents/skills/seo-landing-page-audit/seo-landing-page-audit/SKILL.md

Install a repository Codex skill

Repository skills travel with the codebase and can be reviewed through normal pull requests. From the repository root:

mkdir -p .agents/skills
cp -R /path/to/seo-landing-page-audit .agents/skills/

Check the result:

ls .agents/skills/seo-landing-page-audit/SKILL.md

Codex scans .agents/skills/ from your current working directory up to the repository root. That means a monorepo can keep a shared skill at the root and a narrower skill beside one app or service.

Before committing a third-party skill, confirm that its license permits team distribution. Remove any secrets, private examples, generated output, or local machine paths.

Verify that Codex can use the skill

In the CLI or IDE extension, open the skill selector with:

/skills

You can also type $ to mention a skill explicitly. Start with explicit invocation because it separates installation problems from weak automatic matching:

Use $seo-landing-page-audit to audit this page and return findings in priority order.

Then test a natural request that matches the description:

Audit this landing page for search intent, technical SEO, proof, and conversion gaps.

If the explicit mention works but the natural request does not trigger the skill, improve the description. Put the main job and likely trigger words near the beginning.

Fix a Codex skill that does not appear

Check these common causes:

1. The skill was copied to .codex/skills/ instead of .agents/skills/.
2. The file is not named exactly SKILL.md.
3. The downloaded package has an extra nested directory.
4. The frontmatter is missing name or description.
5. Two installed skills use the same name.
6. Codex was started before the new folder was available and needs a restart.
7. The current working directory is outside the repository that contains the project skill.

If a skill is present but omitted from the initial list, the installation may be too large. Codex limits the metadata it places in the initial context when many skills are available. Remove unused skills or make their descriptions shorter and more specific.

Update, disable, or remove a skill

Replace the full skill directory when updating manually. To disable a skill without deleting it, Codex supports [[skills.config]] entries in ~/.codex/config.toml that point to the skill's SKILL.md and set enabled = false.

To remove a manually installed personal skill:

rm -rf ~/.agents/skills/seo-landing-page-audit

Restart Codex if the old entry remains visible.

Claude Code uses different folders for the same open skill format. See how to install Claude Code skills, or browse AI skills on Capabase when you want a packaged workflow.