# Claude Code skills: how they load, what a big catalog costs, and which ones to keep

> Source: <https://dev.to/actuallyshipped/claude-code-skills-how-they-load-what-a-big-catalog-costs-and-which-ones-to-keep-jkl>
> Published: 2026-11-20 13:38:18+00:00

**Recommendation:** Keep a small catalog of short, self-written skills and audit third-party skills like code, since unused entries crowd the always-loaded list and get their descriptions dropped.
More in the playbook "Designing agent systems": <https://wpnews.pro/playbooks/agent-architecture>

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.

My rule: a skill is for a procedure you repeat. A fact belongs in the instruction file, so [CLAUDE.md and AGENTS.md](https://actuallyshipped.com/en/articles/claude-md-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](https://actuallyshipped.com/en/articles/claude-code-hooks/) 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`.

The format is the same in both because it is an open standard. Anthropic [handed it to the Agentic AI Foundation](https://actuallyshipped.com/en/news/agent-skills-moves-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.

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.

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](https://actuallyshipped.com/en/articles/agent-written-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.

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).

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).

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.

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.

`/skill-doctor` shows you which.`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.

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.

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.

*First published on [Actually Shipped](https://actuallyshipped.com/en/articles/claude-code-skills/).*
