Codex: Agent Skills

What is a skill?

A skill in Codex is essentially a playbook for doing a specific task. At its most basic, a skill is a directory with a SKILL.md file that looks something like this:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

Suppose you have a project that’s a Symfony & API Platform REST API. You could write a skill that looks something like this:

skills/
    api-platform-endpoint/
        SKILL.md
        templates/
        examples/
        assets/

And then the SKILL.md file might look like this:

When creating a new endpoint:

1. Create a DTO.

2. Create a Processor.

3. Add validation.

4. Add an integration test.

5. Run:

composer phpstan

composer test

Now, when you give Codex a prompt like:

Build a POST /comments endpoint that lets authenticated users create a Comment record. It should meet the following requirements:
- Can only be used by authenticated users
- The created Comment is associated with the authenticated user via the Comment::user relation

Codex will notice that you have defined a skill that’s relevant to this task. It does this by looking at the description field of all your SKILL.md files to determine which skill is relevant.

So in this example, it’ll identify the api-platform-endpoint skill as relevant so it’ll follow the instructions in the api/platform-endpoint/SKILL.md file as much as possible for this particular task.

What are the benefits of creating and using skills?

You can create playbooks so that Codex can do specific things in a very particular way that is suitable for your project.

How do I invoke a skill?

You have a few options:

• Run /skills to list all the available skills and choose one (explicit)
• Type $ and then the name of the skill (explicit)
• Give Codex a prompt where the prompt description contains relevant words or phrases so that Codex can use the relevant skills (implicit)

How can I create a skill?

• Via the built-in creator by running $skill-creator
• Manually by creating a folder with a SKILL.md file
• Via Record & Replay

Where shall I save the skills?

• For project-specific skills, use $REPO_ROOT/.agent/skills
• For user-specific skills, use $HOME/.agents/skills. You’ll probably want to create a skills Git repo and clone it in $HOME/.agent/skills

Examples use cases for a skill

Whenever you find yourself doing something repeatedly, consider creating a skill for it. Examples might include:

• Creating a new page in your React SPA
• Creating a new REST API endpoint
• Adding tests for a REST API endpoint
• Adding a new form
• Asking Codex to review all the changes in your current branch and suggest refactorings

Relevant skills

• Agent Skills Overview – agentskills.io