Skip to content
Recaply.
Sign inSubmit a tool

LearnTutorials

CodexTutorialsOpen Codex

Install agent skills in OpenAI Codex

Add a skill to Codex in the CLI, the IDE extension or the ChatGPT desktop app, find it with /skills and call it with $skill-name. Repo and personal folders.

By Recaply EditorsBeginner5 min6 stepsUpdated

A hand sets a small book on top of a short stack of books

Codex reads skills from .agents/skills in your repo and from ~/.agents/skills in your home folder. Skills work in the Codex CLI, the IDE extension and the ChatGPT desktop app.

Short answer: run the skill's npx line with -a codex in your repo, type /skills to find it, then mention it with $skill-name or just ask for the job.

What you need

  1. Step 1: Choose a repo or personal skill

    1 min

    Codex looks in several places, from the folder you work in up to your home folder.

    1. Repo: .agents/skills/ in the folder you work in, or any folder above it up to the repo root. Commit it to share it with your team.
    2. Personal: ~/.agents/skills/. It applies to any repo you work in.
    3. Admins can also put skills in /etc/codex/skills, and Codex comes with built-in skills of its own.

    If two skills share a name, Codex doesn't merge them. Both can appear when you pick a skill, so give each a different name.

  2. Step 2: Install a free skill with one line

    1 min

    The skills CLI copies the skill from its maker's GitHub repo into .agents/skills/.

    1. Open a terminal in your project folder.
    2. Paste the line from the skill's Recaply page. It ends in -a codex.
    3. To install it for all your projects instead, add -g. It then goes to ~/.agents/skills/.
    The install line
    npx skills add <owner>/<repo> --skill <skill-name> -a codex

    You should see a new .agents/skills/<skill-name>/ folder with SKILL.md inside.

    The CLI asks which agents to install to?

    The line is missing its -a value. Pick your agent in the list, or run the line again with it. Add -y to skip the questions.

    Codex can also fetch skills itself: $skill-installer adds OpenAI's curated skills, such as $skill-installer linear, and can download skills from other repos.

  3. Step 3: Or install a premium skill from its ZIP

    2 min

    A premium skill comes as one ZIP that holds a single folder named after the skill.

    1. On the skill's Recaply page, sign in, buy it (or use the plan), then click Download ZIP.
    2. Move the ZIP into your project folder and open a terminal there.
    3. Run the line below. It unzips the folder, then installs it for your agent.
    4. When it's done, you can delete the ZIP and the unzipped folder: the CLI made its own copy.
    Your line
    unzip <slug>.zip && npx skills add ./<slug> -a codex

    You should see .agents/skills/<slug>/SKILL.md, with the skill's other files beside it.

    On Windows, there's no unzip?

    Right-click the ZIP, choose Extract All, and move the extracted folder into .agents/skills/ in your project.

    Unzipping straight into the folder works too: unzip <slug>.zip -d .agents/skills/.

  4. Step 4: Check that Codex sees it

    1 min

    Codex notices new and changed skills on its own.

    1. In the Codex CLI or the IDE extension, run /skills and look for the name.
    2. In the ChatGPT desktop app, open the Skills sidebar to see the skills across your projects.

    You should see the skill's name with its description.

    A new or changed skill doesn't show?

    Restart Codex. It usually picks up changes by itself, and a restart makes it look again.

  5. Step 5: Run the skill

    1 min

    Codex uses a skill when your task matches its description, or when you mention it.

    1. In the CLI or IDE extension, type $ and choose the skill, or write $skill-name in your prompt.
    2. In the ChatGPT desktop app, type @ and pick the skill.
    3. Or describe the job in words from the skill's description.
    Your prompt
    $<skill-name> <what you want it to do>

    You should see Codex follow the skill's steps for your task.

    Codex ignores the skill?

    Mention it with $skill-name. If it still doesn't load, check that SKILL.md starts with a name and a description between two --- lines.

  6. Step 6: Not working? Check these

    2 min

    Most problems come from the folder's place or a setting that turned the skill off.

    1. The skill sits in .agents/skills/<skill-name>/SKILL.md, the folder Codex's docs name for repos.
    2. Started Codex outside the repo? Repo skills load from your current folder up to the repo root, so start it inside the repo.
    3. Turned off? Look in ~/.codex/config.toml for a [[skills.config]] entry for that skill with enabled = false, remove it, and restart Codex.
    4. A symlinked folder is fine: Codex follows the link when it looks for skills.

You get

A skill in Codex that you can call with $skill-name

Try next

Install an agent skill in any AI coding agent6 steps · 5 minInstall agent skills in OpenCode6 steps · 5 minInstall agent skills in GitHub Copilot6 steps · 5 min

Did this guide work for you?

Sources

0 of 6Next: Choose a repo or personal skill