A skill is a folder with a SKILL.md file that Claude Code or Codex loads when your task matches its description. Write one when you catch yourself pasting the same procedure into the chat a third time, and keep it short. The cost sits in the catalog, not in the single skill: every installed skill takes a place in the list on every turn, many never run, and once the list outgrows its budget the least-used ones lose their descriptions. Keep a few short skills of your own, and read anyone else's like code before it goes on your machine.
Who ran the tests. An agent procedure ran everything measured below, not me. On 2026-11-02 a Claude Code session (Claude Opus 5.5) drove the shell on my Mac, with my own skill catalog installed, using Claude Code 2.1.312 and Codex CLI 0.160.1 (model gpt-6.1-sol, reasoning effort medium). Each prompt ran once per condition in a fresh headless session through my subscriptions, so the counts show what happened, not a rate. Documented behavior is marked as documented. Claude Code's docs and changelog were rechecked on 2026-11-18 against release 2.1.327, the latest at the time of writing; the tests were not rerun. The prompts, scripts and results are in our evidence archive.
When is a skill better than a CLAUDE.md section, a hook or a subagent?
My rule: a skill is for a procedure you repeat. A fact belongs in the instruction file, so CLAUDE.md and AGENTS.md is the place for what the project is. Once a section there has grown into numbered steps that only matter on some tasks, it is a skill, because a skill's body is read only when it is used.
| You want | Use | Why |
|---|---|---|
| A procedure Claude should follow when the task matches | Skill | Only its name and description are always loaded; the body loads on use |
| A fact about the project, true on every task | CLAUDE.md or AGENTS.md | Read at the start of every session |
| A rule that must hold every time | Hook | Runs on the event whether or not Claude remembers (documented) |
| Work in a separate context, with a report back | Subagent | Keeps the noise out of your main conversation |
The hook row matters more than it looks. The docs say it directly: if Claude skips a rule that must hold every time, move the rule into a hook, which a skill can define in its own frontmatter. Our hook recipes show what a hook does and does not block.
Custom slash commands no longer compete with skills. Per the docs they are merged: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you /deploy.
Where do Claude Code and Codex look for skills?
The format is the same in both because it is an open standard. Anthropic handed it to the Agentic AI Foundation on 2026-10-22, so one SKILL.md can serve both tools. The portable core, a name, a description and a body, works in both; the folders, the way you call a skill and some fields differ.
| Claude Code | Codex | |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | $HOME/.agents/skills |
| Project | .claude/skills/<name>/SKILL.md | .agents/skills, from the working directory up to the repository root |
| Other | enterprise, plugins, --add-dir, skills synced from claude.ai | /etc/codex/skills, bundled system skills |
| Required fields | none; description recommended | name and description |
| Call it yourself | /name | /skills or $name |
All of this is documented behavior except one surprise from the test. Codex 0.160.1 also loads skills from ~/.codex/skills, a folder its current docs no longer mention. In an empty folder, Codex listed skills that exist only there. If you wonder why Codex sees a skill you never put in .agents/skills, look there. I would not rely on it.
Claude Code also reads fields the spec does not define, such as disable-model-invocation and hooks. What Codex does with them was not tested.
What does the smallest working skill look like?
Here is a shortened version of the skill the tests used; the test version also told Claude to print a canary line, so a run could be scored. Put it at .claude/skills/license-headers/SKILL.md for Claude Code and .agents/skills/license-headers/SKILL.md for Codex:
--- name: license-headers description: Adds, checks or updates license and copyright headers at the top of source files. Use when the user asks about license headers, copyright notices or SPDX identifiers in code files. --- 1. List the source files (`git ls-files`). 2. Report which files lack an SPDX header such as `# SPDX-License-Identifier: MIT`. 3. Do not edit files in this run; describe the change you would make. Write the description first, and put the words a person would say at the front. The spec requires name (64 characters, lowercase letters, digits and hyphens) and a description of up to 1,024. Claude Code cuts the description plus when_to_use at 1,536 characters in its list, so a long first sentence of background is wasted. The spec suggests keeping the file under 500 lines.
What does a big catalog cost?
My own catalog is the example: about 80 skills of my own, plus a plugin, skills synced from claude.ai and the built-in ones. An agent asked Claude Code what that does, with /context and /skill-doctor in an empty repository. The listing took 10k tokens, 1% of the context window, which is exactly the documented budget.
That is not the expensive part. The budget is fixed, so when the catalog outgrows it, Claude Code drops descriptions, starting with the skills you invoke least. Of the 131 skills in my list, 78 were there by name only: the least-invoked ones, by Claude Code's own count, had lost the text that helps Claude pick them. Raising the budget to 3% through a settings override brought every description back and grew the listing to 18.7k tokens. That is the trade: findability against context.
/skill-doctor counted 96 skills on the machine that had never been invoked. It prints what each one costs in the system prompt on every turn, and tells you to disable or remove what is not used.
So prune the catalog, and when you start a new project, do not copy the old project's skills over. Pick them again for the new work. A skill that fit the last project is a description that now competes for the budget with everything else. Agent setups pile up other things the same way when nobody prices them; I wrote about what happened with checks.
Codex has the same mechanism with different numbers. Per its docs, the first list takes at most 2% of the context window, shortens descriptions first and may leave skills out with a warning; skills.max_context_tokens raises it up to 10,000 tokens.
Will it actually trigger?
Claude Code's skill-creator plugin tunes a description the same way: it generates should-trigger and should-not-trigger prompts and measures the hit rate (documented). The agent ran ten prompts that should trigger the license-headers skill and ten that should not ("Put an SPDX identifier at the top of every Python file" against "Write a unit test for the add function"). For Claude Code, a run counted when the transcript showed a Skill tool call and the answer carried the canary line the skill asks for. Codex has no Skill tool call to look for, so there the canary line in the answer was the test. All runs had my full catalog installed.
| Condition | Should trigger | Should not trigger |
|---|---|---|
| Claude Code, default listing | 10 of 10 | 0 of 10 |
| Claude Code, description removed (name only) | 10 of 10 | 0 of 10 |
Claude Code, opaque name hdrkit, name only | 9 of 10 | 0 of 10 |
| Codex | 10 of 10 | 0 of 10 |
The opaque row needs a second look. Claude called the skill in all ten runs, and one answer left out the canary line. But it never called the skill as its first step. In every run it first read a skill file or explored the repository, where .claude/skills/hdrkit/SKILL.md is a visible file, and only then called it. The tested recovery went through files in the repository; a personal skill in ~/.claude/skills was not tested.
With a clear name, the description changed little in this run: Claude called the skill as its first step in 6 of 10 runs without it and 5 of 10 with it. One run per prompt cannot tell those apart. When the budget cuts descriptions, the name is what remains, so give it the words of the task.
If you want to check your own skill, ten prompts that should trigger it and ten that should not make a quick first test. If the frontmatter does not parse, the skill still loads, but with empty metadata, so Claude cannot match it by description. Run claude plugin validate ~/.claude/skills to find those (v2.1.233 or later).
Which skills should never run on their own?
A skill with side effects, like a deploy or a message to a customer, should be invoked by you. Set disable-model-invocation: true and Claude will not call it. Per the docs this also keeps its description out of the context, so it stops using budget. user-invocable: false is the opposite and hides it from the / menu, but the description stays in context.
None of my 80 skills used disable-model-invocation, and 47 of them pre-approve tools with allowed-tools. Scheduled tasks and /loop now ask before running a skill that declares allowed-tools or hooks (Claude Code 2.1.325, 2026-11-13).
Why does Claude stop following a skill halfway?
Claude Code puts the skill's text into the conversation once and does not re-read the file. After a compaction it re-attaches the most recent call of each skill, but only the first 5,000 tokens of each and 25,000 for all of them together (documented). Two consequences. Put the instruction that matters most at the top of the file. And if a long session starts to drift, call the skill again.
If a rule must hold every time, do not make the skill stronger. Move that rule into a hook.
Is it safe to install someone else's skill?
Read it like code, because it is code with instructions on top. Look at allowed-tools, at every script in the folder, and at the commands in the body. The docs state something worth knowing here: Claude Code applies a project skill's allowed-tools even in a -p run in a folder you have never trusted. A repository you only cloned can ship a skill that grants itself tools.
What I conclude
- The catalog is the cost, not the skill. One skill is cheap. Eighty share one fixed budget, and the least-used lose their descriptions first.
- Name a skill for the task. With a descriptive name, Claude reached for the skill first about half the time even without a description. With an opaque name it never did, and had to dig the skill out of the repository.
- Write a skill for a procedure you repeat, keep it short, and turn off what never runs.
/skill-doctorshows you which. - Rules that must hold go into a hook, side effects get
disable-model-invocation, and someone else's skill gets a read first.
A small catalog whose descriptions fit the budget needs none of this cleaning; /context shows whether yours fits. The numbers here are from one machine and one run per prompt, and the next release can change them.
Two more questions
Can Codex use a skill written for Claude Code?
Yes, if it sticks to name, description and a body. Put the same folder in .agents/skills. Fields that only Claude Code defines may be ignored; that was not tested.
Are skills and slash commands the same thing now?
For Claude Code, yes: a file in .claude/commands/ and a skill folder both create the command, and the skill adds supporting files and automatic loading.
Sources
- Extend Claude with skills (Claude Code docs)
- Agent Skills specification
- Build skills (Codex docs, reached from developers.openai.com/codex/skills)
- Claude Code changelog
- Anthropic, Donating Agent Skills to the Agentic AI Foundation
First published on Actually Shipped.

