How to Use Codex Skills: From SKILL.md to Trigger Verification, Explained in One Pass

Learn how to build a minimal working Skill from SKILL.md, verify that it triggers correctly with positive and negative tests, and troubleshoot common problems like a Skill not loading, not triggering, or bloating the context.

5 min read
How to Use Codex Skills: From SKILL.md to Trigger Verification, Explained in One Pass

When people build their first Skill, they often get stuck at an awkward spot: the file is written, the directory is created, and Codex still acts like it can't see anything.

Before you start making SKILL.md longer and longer, slow down. Whether the Skill can be found, and when it should trigger, matter more than how polished the body is. Those are the first two gates.

What a Skill Actually Is

A Skill is not just a Prompt saved to a file. It's closer to a small reusable workflow: when to use it, which materials to read, which steps to run, and when to stop can all go inside.

A Skill needs at least a SKILL.md. Add scripts, reference materials, and resource files when you need them:

my-review-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Don't fill in all four directories the first time. Start with just a SKILL.md, prove that it can be found and triggers as expected, then add things gradually.

Put It in the Right Directory First

Codex loads local Skills from several scopes. For most personal projects, the most common ones are:

current-project-directory/.agents/skills/
project-root/.agents/skills/
$HOME/.agents/skills/

If you only want one project to use a Skill, put it in that project's .agents/skills. If you want it available across projects, consider the user-level directory.

For example:

demo-project/
└── .agents/
└── skills/
└── check-release-notes/
└── SKILL.md

Codex can detect Skill changes automatically. If a newly added Skill doesn't show up, check the directory and file name first, then restart Codex. Don't jump straight to reinstalling.

A SKILL.md That Does the Job

Start with the minimal version:

---
name: check-release-notes
description: Check whether release notes are missing compatibility, migration steps, and rollback instructions. Use only when reviewing release notes.
---

# Release notes check

1. Read the release notes the user specifies.
2. Check whether they include changes, compatibility, migration steps, and rollback instructions.
3. Report only what's missing. Don't edit the original file.
4. If the information is insufficient, mark it clearly as "to be confirmed" and don't fill it in on your own.

The part most worth your time here is description.

A description like "help me handle documents" is almost the same as writing nothing. "Check whether release notes are missing migration and rollback information" is much clearer. When Codex decides whether to invoke a Skill implicitly, it looks at the name and description first, so the description should read like clear usage instructions, not marketing copy.

Don't Test Just Once

I'd recommend two rounds.

Round one: invoke it explicitly. In the CLI or IDE, you can run /skills, or type $ and pick the Skill from the list. If you already know the name, you can also write $skill-name directly. First confirm that the Skill itself works.

For example:

$check-release-notes
Please check docs/release-note.md. Only report what's missing, and don't modify the file.

Round two: don't name the Skill, and send a request that closely matches its description:

Please check whether this release note is missing migration steps and rollback instructions.

If Codex picks it on its own this time, implicit triggering is basically working too.

Finally, run a negative test, such as:

Summarize today's meeting notes for me.

This should not trigger the release notes check. A Skill that triggers when it should and stays quiet when it shouldn't is worth more than one that works "once in a while."

If a Skill Doesn't Trigger, Check in This Order

Don't change ten settings at once. Start with the basics:

  1. Is the directory .agents/skills/<skill-name>/SKILL.md?
  2. Does the YAML in SKILL.md include name and description?
  3. Does the description state clearly when the Skill should be used?
  4. Does the request actually match the description?
  5. Do the relative paths you reference, such as references/... and scripts/..., exist?
  6. If you just edited the Skill, start a new task and test again.

If a script is part of the flow, get the script running on its own in the terminal first. If the script itself errors out, don't blame the Skill trigger.

When to Add scripts and references

Some rules are just written guidance and belong in references/. Other work has to run reliably, such as format validation, file conversion, or running a fixed set of tests, and that's when scripts/ makes sense.

There's another benefit: you don't have to cram a pile of material into SKILL.md every time. Codex uses progressive loading. After a Skill is selected, it reads the full instructions and any needed resources. The clearer the structure, the easier it is to maintain later.

If Your Skill Involves Model Selection, Don't Hardcode Prices

If you already call models through AI Code With, the live pages there make a good external source of truth.

Say you're building a Skill that picks a model based on task complexity. You can define the flow like this: read the current model and channel information first, then decide which model to use. Don't permanently hardcode things like "model X costs this much" or "channel Y is always this much off" in SKILL.md.

The AI Code With model and channel pages are themselves a dynamic source of information:

The upside is that the Skill only stores how to decide, while information that changes, like prices and channels, stays on the live pages. If an ordinary document-organizing Skill doesn't involve models at all, you don't need this extra layer.

Final Thoughts

Skills are easiest to turn into something big and all-inclusive, and that's also the easiest way to lose control of them.

Start with a small Skill you can validate in ten minutes: it can be discovered, invoked explicitly, triggered implicitly, and doesn't trigger by mistake. Once that runs smoothly, add scripts, reference materials, and more complex automation.

References

Related articles

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

The UI SDK is Vercel's behavior library for agents, released on 12 November 2026 as 0.1.0-beta.1. Behaviors live in the framework-free @ui-sdk/core package and are rendered by adapters for React, Vue, Svelte, Solid, and Web Components. This guide follows the official docs on what it is, how to install it, and how to add the skill for Claude Code, Codex, and Cursor, and it records the commands, timings, and output from our test machine.

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of its service APIs, generally available since November 11, 2026 (US time). It has no additional service fee, its source is open, it needs no AWS account, and it covers more than 200 services. We tested version 1.0.322 on Debian 13. This guide covers the install commands, pointing the AWS CLI at the local endpoint to create an S3 bucket and a DynamoDB table, the errors we hit, and how to let Claude Code, Codex and Cursor write and test code against the emulator.

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

T3 Code is pingdotgg's open-source control surface for coding agents. It ships no model of its own; it drives the Claude Code, Codex, Cursor and other CLIs already on your machine. We tested T3 Code 0.1.9 on Linux. This guide covers the install commands, how to point Claude Code and Codex at an AICodeWith API Key so T3 Code can drive them, a full run of both agents with the t3 thread command, and the errors we hit along the way with their fixes.