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:
- Is the directory .agents/skills/<skill-name>/SKILL.md?
- Does the YAML in SKILL.md include name and description?
- Does the description state clearly when the Skill should be used?
- Does the request actually match the description?
- Do the relative paths you reference, such as references/... and scripts/..., exist?
- 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:
- Models and pricing: https://aicodewith.ai/zh/dashboard/pricing?ref=docs&src=codex-skills-tutorial
- Channel status: https://aicodewith.ai/zh/dashboard/channels?ref=docs&src=codex-skills-tutorial
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
- OpenAI: Build skills — https://developers.openai.com/codex/skills
- AI Code With: Codex configuration docs — https://aicodewith.ai/zh?s=k7m2q9



