Codex · Skills guide

How to add, use, and fix Codex Skills

Start with one small skill. Add it to your project, try it with sample notes, and check the result.

Compare all three

1. Add Codex Skills

This example uses a local project. You need Codex installed and a folder you can edit.

Open your project in Codex. Create a meeting-recap folder inside .agents/skills.
Save the example below as SKILL.md in that folder. Include both name and description in the YAML header.
Use the personal path for a skill you want in multiple projects. Codex detects skill changes automatically.

For this project: .agents/skills/meeting-recap/SKILL.md
For your projects on this computer: ~/.agents/skills/meeting-recap/SKILL.md

The project path starts in your project folder. ~ means your home folder. Choose one location.

Practice example: your SKILL.md file

---
name: meeting-recap
description: Turn meeting notes into decisions and actions. Use when the user asks for a meeting recap.
---

Read the notes supplied by the user.
1. List the decisions.
2. Make an action list with an owner and due date.
3. Write "Not provided" for missing details. Do not invent them.
4. Return a draft for review. Do not send messages or change files.

Using a downloaded skill? Read its instructions and supporting files before adding it.

2. Use Codex Skills

Mention $meeting-recap in your Codex request and add the sample notes below.
Codex can also select a skill when the request matches its description.

$meeting-recap

Sample meeting notes:
Maya will draft the proposal by Friday.
The team agreed to offer a two-week trial.
Someone needs to check the budget; no owner was chosen.

Check the draft: Maya owns the proposal, Friday is its deadline, and the budget task has no named owner. If the answer adds facts, ask for a correction before using it.

3. Fix Codex Skills

The skill is missing

Check the .agents/skills path and SKILL.md filename. Make sure Codex is working in the right project. Restart Codex if the change has not appeared.

The skill is disabled

Check for an entry with enabled = false under [[skills.config]] in ~/.codex/config.toml. Restart Codex after changing this setting.

The wrong skill runs

Check for duplicate skill names. Give your skill a distinct name and a description that explains when it should be used.

If a downloaded skill fails after starting, read the first error. Check its required tools, files, and access. A skill folder does not install those for you.

Skills to try in Codex

Browse the Skills library