Agent Skills Not Working: A Diagnostic Reference

Start here, because two questions separate almost every case:

1. Does the agent list the skill at all? If it doesn't, it's a discovery problem — wrong directory, wrong filename, broken frontmatter, or a path the runtime refuses to follow.
2. If it lists the skill, does invoking it explicitly work? Type /skill-name (or $skill-name in OpenClaw's composer). If explicit invocation works but the agent never reaches for it on its own, it's a triggering problem, and the description is almost always the cause.

Those are different failures with different fixes, and most guides run them together.

How claims on this page are labelled

Skills problems attract a lot of confident, wrong advice — including in Google's own AI summary of this topic, as documented below. So every cause here is marked:

• Documented — stated in the runtime's own documentation or the Agent Skills specification.
• Verified issue — a public bug report read through to its resolution, cited by number, with its state and version where the reporter gave one.
• Diagnosis — our inference from mechanics we hold. Labelled wherever it appears.

We have not run these agents or reproduced these failures. Nothing here is presented as our own testing.

---

Class 1: the skill is never discovered

Filename case

SKILL.md is case-sensitive. A file named skill.md is not found.

This is worth putting first because it is the resolution of one of the most-cited bug reports in this space. In anthropics/claude-code #17417 a user reported skills in .claude/skills/ never appearing, and posted a detailed root-cause analysis blaming /tmp/claude/ directory permissions. The issue was later closed with the reporter's own correction:

The problem was caused by incorrect case of files. skill.md instead of SKILL.md

Verified issue (#17417, closed January 2026).

The spec also requires that name in the frontmatter match the parent directory name. Both are silent failures.

A path the runtime won't follow

Symlinked skill directories break discovery in more than one runtime, independently:

If you keep a skills library in one place and link it into projects, this is the first thing to rule out. Diagnosis: replace the symlink with a real directory as a test; if the skill appears, you've found it.

Other discovery failures reported in Claude Code

All verified issues. Each is a single vendor and, in several cases, a single reporter — check whether your version and platform match before assuming it applies.

You're looking in a directory the runtime doesn't scan

The most common version of this is simply not knowing the full list. Every runtime scans more than one location, and two of them scan each other's:

Frontmatter that looks fine but isn't

YAML is unforgiving in ways that don't show up visually. In #9716 a reporter described frontmatter copied straight from the documentation being rejected; asking Claude to compare it against the spec produced a rewrite that was, in the reporter's words, "identical to my eyes" — after which the skill worked consistently. Verified issue (open since October 2025).

The two required fields are name and description. If in doubt, retype the frontmatter block by hand rather than copying it, and validate with skills-ref validate ./my-skill from the standard's reference library.

---

Class 2: the skill loads but never fires

If /skill-name works and automatic invocation doesn't, the problem is upstream of the runtime — the agent is deciding your skill isn't relevant.

The description is doing all the work

At startup an agent loads only each skill's name and description. Everything else stays on disk. The specification is explicit that this is the whole basis for the decision, and the standard's own guidance puts it plainly: the description "carries the entire burden of triggering."

Three things follow, all documented:

Write it as an instruction, not a summary. "Use this skill when…" rather than "This skill does…". The agent is deciding whether to act.

Describe the user's intent, not your implementation. The match is against what the user asked for, not against how the skill works internally.

Name the situations explicitly, including indirect ones. The standard suggests being deliberately pushy — listing contexts where the skill applies "even if they don't explicitly mention" the domain by name.

# Weak — describes the artifact
description: A skill for working with our deployment system.

# Better — describes the trigger
description: Deploy or roll back a service to staging or production. Use when
  asked to ship, deploy, release, revert, or roll back, even if the environment
  isn't named.

The task may be too small to warrant a skill

A subtlety worth knowing before you rewrite a description that isn't broken. Per the standard, agents typically consult skills only for tasks needing capability beyond what they can already do — so a simple, one-step request may not trigger a skill even when the description matches perfectly. Documented.

If your skill covers something the agent can handle unaided, low trigger rates may be correct behaviour rather than a bug.

Something else in context outranks it

The most under-reported cause we found. In #9716, a reporter found that an instruction in CLAUDE.md covering the same task was treated as "having higher salience than the skills trigger" — the always-on instruction won, and the skill never loaded. Verified issue.

This is the practical edge of a distinction the rest of this site covers at length: persistent instruction files and skills are different mechanisms, and when both describe the same job they compete. If you have a CLAUDE.md, AGENTS.md, or a Cursor rule covering the same ground as a skill, that overlap is a live suspect. See Codex skills vs AGENTS.md and Cursor skills vs rules.

Testing triggering instead of guessing

Model behaviour is non-deterministic, so a single test proves little. The standard documents a real method: build roughly 20 realistic prompts labelled for whether they should trigger the skill, run each several times, and compute a trigger rate.

The valuable half is the negatives. Weak negatives ("write a fibonacci function") test nothing. Strong ones are near-misses that share vocabulary but need something different — for a CSV-analysis skill, "update the formulas in my Excel budget" shares the spreadsheet concept but isn't the job.

Documented method, not our measurement. We have not run these evals, and we publish no trigger rates of our own.

Invocation is switched off

Check whether the skill has opted out of automatic selection. disable-model-invocation: true keeps a skill reachable by command while removing it from model-initiated selection — supported in Cursor, OpenClaw and Claude Code. In OpenClaw it also hides the skill from the $ picker. Codex has the equivalent in agents/openai.yaml as policy.allow_implicit_invocation: false.

Migration tools set this for you: Cursor's /migrate-to-skills converts slash commands into skills with disable-model-invocation: true, and OpenClaw's Claude import does the same for .claude/commands/ files. If a skill arrived via migration and never fires on its own, this is why. Documented.

---

Class 3: it worked, then stopped

The catalogue was dropped from context

If a skill worked earlier in a long session and then stopped, suspect compaction rather than configuration.

anthropics/claude-code #74990 reports that both /compact and auto-compaction remove the entire Available skills block from context — not some skills, the whole catalogue. Running /reload-skills afterwards prints 33 skills available (no changes), confirming the registry on disk is intact while the model still can't see it. Verified issue (open, July 2026).

Diagnosis: if a skill stops working mid-session and nothing on disk changed, start a new session before changing anything.

Too many skills for the budget

Skill descriptions share a fixed budget, and past it, skills are silently excluded.

#40774 is the practical illustration: a reporter with nine plugin skills saw about two reach chat, attributed it to a ~1% / ~8,000-character budget, and found the workaround was keeping descriptions under 200 characters with key terms front-loaded. The budget attribution there is the reporter's, not vendor documentation — but it points the same way as the two runtimes that publish figures.

So a long description costs twice: it consumes budget in every session, and past the ceiling it can be the thing that gets cut.

The runtime hasn't reloaded

Diagnosis: when a skill doesn't appear after an edit, a new session is the cheapest way to eliminate this whole class.

---

Class 4: the file is fine, but not here

Some skills are portable and some aren't, and the failure is silent either way.

paths breaks discovery in Claude Code

The sharpest example we found, and a genuine trap for anyone writing skills for more than one agent.

paths is a Cursor frontmatter field that scopes a skill to files matching glob patterns. Add it to a skill in Claude Code and, per #49835, the skill becomes entirely undiscoverable — absent from / autocomplete, unlisted as available, and returning Unknown skill on direct invocation. Removing the single line restores it. Verified issue (open, April 2026).

Nothing in either vendor's documentation tells you this, because it's only visible from both sides at once.

Runtime-only fields in general

These do not travel. A skill using them still works in its home runtime and may silently underperform or fail elsewhere:

The portable core is name, description, the markdown body, and the scripts/, references/, assets/ convention. Agent Skills compatibility covers what travels in detail.

You're on a different surface than you think

Within a single product family, skills don't always follow you. In the Claude Code family there are reports of skills enabled on claude.ai not loading in web sessions (#75261, open), the VS Code extension checking only filesystem paths and so missing organisation-level skills (#65021, closed), and Cowork resolving skills from a deployment mount rather than local ~/.claude/skills (#76724, open). Verified issues.

If a skill works in the CLI and not in the IDE or the web app, that's the class to look at.

---

A correction worth making

Search results for this problem currently propagate a wrong root cause.

Issue #17417's body contains a detailed analysis blaming /tmp/claude/ permissions — root-owned directory, EACCES on mkdir, "fails silently when it cannot create the necessary directories." That analysis is quoted in third-party troubleshooting articles and, at the time of writing, was reflected in Google's AI summary for this topic.

The issue's resolution, posted by the same reporter, was filename case: skill.md instead of SKILL.md.

Both facts are in the same issue. Only one of them is the answer. It's worth checking bug reports to the end before treating a preliminary hypothesis as a documented cause — including the ones on this page.

Caveats

• We have not run any of these agents, installed any skill, or reproduced any failure. Every cause is documented behaviour, a public issue read to resolution, or labelled diagnosis.
• GitHub issues carry state and version where the reporter supplied one. A closed issue may still describe behaviour you hit on an older version; an open one may be narrow. Several are single-reporter.
• Runtime behaviour here reflects documentation and issues as of 16 August 2026. These products ship weekly.

Sources

• Agent Skills — Specification and Optimizing skill descriptions
• anthropics/claude-code issues — #9716, #17078, #17417, #31649, #37553, #38051, #40774, #42573, #49835, #65021, #74990, #75261, #76724
• openai/codex issue #11314
• Runtime documentation for Claude Code, Codex, Cursor, OpenClaw, and Hermes Agent