The three-phase pipeline
Every agent that supports Agent Skills runs the same three-phase pipeline, whether it's Claude Code reading from ~/.claude/skills/ or Codex CLI reading from ~/.codex/skills/: discovery, activation, execution. Understanding these three phases, and specifically what's cheap versus what's expensive, explains almost every "why didn't my skill fire" question, and it's the single most useful piece of a skill author's mental model.
Phase 1: discovery
At session start, the agent scans its skill directories and reads only the frontmatter name and description of each installed skill. Not the body. Not any bundled scripts/, references/, or assets/. Just two short fields per skill.
This is deliberate, and it's the whole reason the system scales. Reading a one-line description costs a handful of tokens. Reading a full SKILL.md body, plus everything it might bundle, could cost thousands. Multiply that by a hundred installed skills and the difference between "read everything" and "read names and descriptions" is the difference between an unusable context window and a negligible one. This mechanic, load the cheap summary always, load the expensive detail only when needed, is called progressive disclosure, and it governs all three phases, not just this first one.
Phase 2: activation
When you make a request, the agent matches your intent against the descriptions it collected during discovery. If a description matches what you're asking for, the agent loads that skill's full SKILL.md body into its context. If nothing matches, nothing loads, the descriptions sat there for free and nothing else happens.
This is the phase where most "skill isn't working" problems actually originate, and it's worth being precise about why. Activation isn't a keyword search and it isn't a guarantee. It's the agent judging, from your request and the description text, whether this skill is relevant. A description has to state the situations that should trigger it clearly enough for that judgment to land correctly, every time, not just when you phrase the request exactly the way the author was imagining.
Phase 3: execution
Once a skill's body has loaded, the agent follows its instructions. This is where the rest of the skill's bundle comes in, and it follows the same progressive-disclosure logic as everything before it: a references/ file loads only if the instructions direct the agent to consult it, and a bundled script only runs if the instructions call for it. A skill can bundle ten reference documents and never load nine of them in a given session, because the task at hand only needed the tenth.
Execution is also where a skill's allowed-tools frontmatter matters, if it's set. It constrains which tools the agent can reach for while following that skill's instructions. And execution depends on the agent actually having tool execution available for skills that shell out to bundled scripts; a skill that expects to run a script needs an agent that can run it.
The three phases at a glance
| Phase | Trigger | What loads | Typical cost |
|---|---|---|---|
| Discovery | Session start | name + description for every installed skill | Small, fixed, paid once per session |
| Activation | Every user request | Full SKILL.md body, if a description matches | Zero if nothing matches; one skill's body if something does |
| Execution | After activation | Bundled references/, scripts/, assets/ — only what the instructions call for | Varies; only what's actually needed for the task |
Worked example: tracing one request through all three phases
Say a repository has this skill installed:
.claude/skills/
└── changelog-writer/
├── SKILL.md
└── references/
└── style-examples.md
---
name: changelog-writer
description: Use when the user asks to write or update a changelog entry for a release, or to summarize recent commits into release notes.
---
# Changelog Writer
Write one bullet per change, past tense, grouped under Added / Changed / Fixed / Removed.
For edge cases in tone or formatting, see references/style-examples.md.
Discovery, at session start: the agent reads name: changelog-writer and the description above. Nothing else. This happens whether or not the session ever mentions a changelog.
Activation, when the user types "write the changelog entry for this release": the agent compares that request against the collected descriptions. "Write... a changelog entry for a release" is close enough to "Use when the user asks to write or update a changelog entry for a release" that the description matches, and the full SKILL.md body loads.
Execution: the agent follows the instructions, group by Added/Changed/Fixed/Removed, past tense. If the changes at hand include something ambiguous in tone, the instructions direct it to check references/style-examples.md, and only then does that file load. If nothing ambiguous comes up, that reference file never loads at all in this session.
Now compare a second request in the same session: "explain what this function does." Nothing about that matches the changelog-writer description, so the skill never activates, its name and description sat in context from discovery, contributing nothing beyond that small fixed cost.
The description field is the entire discovery surface
Because discovery only reads name and description, and activation is purely a match against that text, the description is the entire interface between a request and a skill firing. A brilliant, thorough SKILL.md body is worthless if the description never gets matched.
Weak description: "Helps with changelogs." Vague. It doesn't say what kind of request should trigger it, so the agent has to guess whether "helps with changelogs" covers "summarize these commits" or "explain what a changelog is."
Strong description: "Use when the user asks to write or update a changelog entry for a release, or to summarize recent commits into release notes." It names the concrete triggering situations directly (writing an entry, updating one, summarizing commits into notes) so the match is obvious rather than inferred.
The pattern generalizes: name the situations, not the abstract category. "A skill for code review" is weak. "Use when the user asks to review a pull request for missing tests, exposed secrets, or unsafe migrations" is strong, because it states exactly what should cause activation.
A second worked example: when activation should fail
It's just as useful to trace a case where a skill correctly does not activate, because that's the behaviour most authors underestimate. Take the same changelog-writer skill from the example above, with its description: "Use when the user asks to write or update a changelog entry for a release, or to summarize recent commits into release notes."
A user asks: "what changed in the last release?" On the surface this looks related. It's about a release, and changelogs are about releases. But the description names writing, updating, and summarizing into release notes; it doesn't name answering a question about what already changed. A careful match should treat this as a request for information, not a request to produce a changelog entry, and leave the skill inactive. If the skill does activate here, it's a sign the description is worded broadly enough to catch adjacent-but-different requests. The fix is narrowing the description to the actual triggering action, not the general topic.
This is the same principle as the weak-versus-strong description comparison below, applied to a near-miss instead of a clean hit: a description that names a specific action ("write or update... summarize... into release notes") discriminates between "make this" and "tell me about this" in a way a topic-only description ("helps with changelogs") cannot.
Why the cost curve matters at scale
The reason all of this is worth understanding in detail, rather than just trusting it to work, is what happens as a skills library grows. A single installed skill costs almost nothing at discovery regardless of how it's written, because reading one name and one description is trivial. The design only gets tested once you're running dozens or hundreds of skills across a team or an organisation, which is exactly the situation the skills directory is built to support, spanning categories from development to writing to data analysis.
At that scale, two things have to both hold true for the system to stay usable: discovery has to stay cheap no matter how many skills are installed, and activation has to stay accurate no matter how many descriptions are competing for a match. Progressive disclosure handles the first one structurally. Cost scales with the number of installed skills only at the cheap discovery phase, and with the number of activated skills (usually zero or one) at every other phase. It cannot handle the second one for you. Accurate activation across a large library depends entirely on every skill author writing a description specific enough not to collide with the others, which is why the discipline of naming concrete triggering situations matters more, not less, as a library grows.
How this plays out across agents
The three-phase pipeline is the same standard everywhere skills are supported, but the details of when discovery happens can differ by agent. Codex CLI, for instance, runs discovery at session start and doesn't pick up newly added skills until a new session starts. See Claude Code vs Codex CLI for skills for that comparison. Codex also layers an explicit $skill-name invocation on top of description-based activation, letting you skip straight to activation without relying on the match. Across all supported agents, Claude Code, Codex CLI, Cursor, Antigravity, Windsurf, GitHub Copilot, OpenCode, Cline and more, the underlying discovery-then-activation-then-execution shape holds, because it's what the open standard defines, not something each agent reinvented separately.
Troubleshooting: why a skill isn't activating
The skill never fires, no matter how you phrase the request. Almost always the description. Rewrite it to name concrete triggering situations instead of describing the skill abstractly.
The skill fires on requests it shouldn't. The description is matching too broadly. Narrow it, describe the specific situations, not a general topic area.
The skill fires, but a reference file it needs never loads. Check that the SKILL.md body actually instructs the agent to consult that reference under the relevant condition. Execution only loads what the instructions call for. It isn't automatic just because the file is bundled.
A newly added skill doesn't seem to exist yet. Some agents only run discovery at session start. Start a new session and check again before assuming the skill itself is broken.
A bundled script never runs. Confirm the agent has tool execution available, and that the instructions in the body actually direct the agent to run it, bundling a script doesn't make execution automatic any more than bundling a reference file does.
What this means if you're writing a skill
Everything above points to the same practical conclusion: spend your effort on the description first, the body second. A skill with a mediocre body but a description that names exactly when it should fire will at least get used. A skill with a superb body and a vague description never gets read at all, because activation never happens. If you're about to write one, the guide to writing your own agent skill walks through this in more depth, and the SKILL.md format explainer covers the rest of the frontmatter this pipeline depends on.
