Why Claude Code Skills Do Not Activate
A skill that the model never invokes is the same shape of failure as a CLAUDE.md it never follows.
Activation is delivery plus authority, not just presence on disk.
What this covers
- Claude Code skills are loaded at session start. Adding a SKILL.md without restarting the session usually leaves it inactive.
- Activation depends on the description matching the user request. Vague descriptions activate inconsistently.
- YAML frontmatter errors cause silent failures. The session does not warn that the skill is broken.
- Pathrule treats skills as named team procedures attached to a path and delivered through the same hook flow that carries memories and rules.
Common reasons a SKILL.md does not activate
- The session was not restarted after the skill was added.
- The file is not named SKILL.md with an uppercase basename.
- The folder is double-nested after an archive extract, so the discovery path is wrong.
- The YAML frontmatter has a syntax error and the loader skips the file silently.
- The description is too vague to match real user requests.
- A Prettier or formatter pass broke the frontmatter into multi-line values the loader does not handle.
- The skill directory is not readable, or a temporary cache directory could not be created.
Skills are loaded once, at session start
A skill in Claude Code is a SKILL.md file under a discovery directory the tool scans on startup. The scan picks up the frontmatter, registers the description, and makes the skill available for the rest of the session.
There is no live reload. If a skill is added after the session is already running, the running assistant does not know about it. The most common first failure mode is exactly this: the team installs a skill, sees nothing happen, and concludes the skill is broken when the actual fix is to restart the session.
Practitioners writing about this in the last year keep coming back to the same first step. If a skill is not activating, close the session and start a new one before debugging anything else.
Activation depends on the description, not just presence
A loaded skill is not an executing skill. The model decides whether the user request matches the skill description, and that decision is sensitive to how the description is written.
A vague description loses the comparison. The model has many things it could plausibly do for any given request. If the description does not commit to a specific class of task in a specific kind of phrasing, the model defaults to doing the task directly without invoking the skill.
Public discussion of skill activation rates is converging on a clear pattern: descriptions that are directive and specific activate close to all the time. Descriptions that are generic activate maybe a third of the time. The same SKILL.md body produces different results because of one paragraph in the frontmatter.
Silent frontmatter failures
The other quiet failure is YAML. The loader expects a specific shape: opening fence, name, description, optional fields, closing fence. Any structural problem inside that block can cause the loader to skip the file with no surface warning.
Common breaks include single-line descriptions that an autoformatter rewrote across multiple lines, special characters that were not quoted, a missing closing fence after a hand edit, or leading spaces before the fence introduced by an editor template.
On case-sensitive filesystems the basename matters too. SKILL.md is the expected name. Skill.md, skill.md, and SKILL.MD will not be discovered. macOS may forgive this depending on the volume. Linux will not.
Environment and permission issues
A few non-content failures look like skill problems but are really filesystem problems. A skill bundled as a zip is sometimes extracted into a doubly nested folder, so the SKILL.md lives one level deeper than the loader expects.
Some installations also need write access to a temporary directory to process and cache skills. Without that, the cache step fails quietly and the skill never reaches the active set. These cases are rare but worth checking when a skill that worked elsewhere is not loading on a specific machine.
The shape of the failure is the same across all of these. A file exists. The user assumes it is active. The assistant does not invoke it. The team has no obvious place to see why.
What activation looks like when delivery is reliable
A skill that activates reliably has three things going for it. The file is in the right place with the right name. The frontmatter is valid and the description is specific enough that the model can match it to a real user request. The discovery path the tool scans was actually scanned for this session.
Pathrule treats skills as one of three primitives, alongside memories and rules. The skill body and frontmatter live in the workspace tree. The delivery is the same hook flow that injects memories and rules: at session start, before the first tool call, scoped to the path of the work.
A skill that lives at a path only matters when the assistant is working near that path. It never has to compete with every other skill in the repo for the same generic match. That is a different shape of activation problem to debug because the scope is part of the design.
Debugging skills without guessing
A useful first move when a skill is not activating is to confirm the loader sees it. Restart the session in the directory where the skill is supposed to be active. Ask the assistant whether the skill is available. If not, the answer is usually one of the silent failures above and the next step is to inspect the file directly.
If the skill is loaded but never invoked, the description is the next thing to rewrite. Make it directive and specific. Reference the kind of phrasing real teammates use when they ask for this task. Try the exact request again in a fresh session.
If your team is hitting the same activation cliff repeatedly, we want to hear about it. Every signup gets three months of Pathrule PRO on the house. [email protected] is open if you want to design a more reliable skill delivery flow on a real repo.