Why Your AI Agent Ignores Your Skill (and How to Fix It)
A skill can be installed and still never fire. Work through path, filename, description, invocation flags, scoping and context budget until the agent picks it up, or you know why it won't.
You installed a skill. The folder is on disk. You ask for the thing it was written for, and the agent just… improvises. No skill, no / call, nothing. That usually isn’t a broken model. It’s almost always one of a short list of loading and discovery problems.
This post is a troubleshooting checklist for Claude Code, Cursor and Codex. It assumes the skill already follows the Agent Skills shape (name, description, a SKILL.md body). If you’re still writing the file, start with How to Write Your First SKILL.md. If you’re unsure where the folder goes, use the install guide.
First: is the skill even loaded?
Don’t debug the description until you know the tool can see the skill.
| Tool | How to check |
|---|---|
| Claude Code | Ask “What skills are available?”, open /skills, or type / and look for the name. You can also run /skill-name directly. |
| Cursor | Open Customize → Skills. In Agent chat, type / and search for the skill. |
| Codex | Run /skills, or type $ and mention the skill by name. |
If it isn’t listed, the problem is path, filename or frontmatter. If it is listed but never fires on its own, skip ahead to the description and invocation sections.
1. Wrong path or wrong filename
Every tool looks in specific folders. One level off and there is no error, just silence.
| Claude Code | Cursor | Codex | |
|---|---|---|---|
| Project | .claude/skills/<name>/SKILL.md |
.cursor/skills/ or .agents/skills/ |
.agents/skills/ |
| Personal | ~/.claude/skills/<name>/SKILL.md |
~/.cursor/skills/ or ~/.agents/skills/ |
~/.agents/skills/ |
Common misses:
SKILL.mdmust be named exactly that. Notskill.md, notSkill.md, notskills.md. Claude Code’s troubleshooting notes call this out, and the open standard expects the same file.- The file sits inside a named folder.
.claude/skills/my-skill/SKILL.mdis right. A bare.claude/skills/SKILL.mdis not. - Codex does not read
.claude/skills/. Put the real copy in.agents/skills/, or symlink as the install guide describes. - Claude Code does not read
.agents/skills/. Same idea in reverse. - Cursor will read Claude and Codex folders for compatibility, but personal skills in
~/.cursor/skills/stay local unless you turn on Sync Skills for Cloud Agents. Cloud Agents, remote SSH sessions and automations won’t see unsynced personal skills.
Claude Code also won’t load a nested .claude/skills/ below your start directory until it reads or edits a file in that subdirectory. If you started at the repo root and the skill lives under apps/web/.claude/skills/, it stays invisible until Claude touches that tree, or you /add-dir / /cd into it.
2. Broken or missing frontmatter
The opening --- has to be the first line of SKILL.md. A blank line or a title above it means Claude Code treats the whole file as body text with no metadata. Cursor’s Cloud Agents warn when frontmatter won’t parse or description is missing; without a description the agent is unlikely to pick the skill on its own.
In Claude Code, malformed YAML still loads the body, but with empty fields. /skill-name may work while automatic matching never does. Run claude --debug and look for the parse error, or validate with claude plugin validate on the skills directory.
Two YAML traps:
- A colon-plus-space inside an unquoted
descriptionbreaks the map. Quote the string. namemust match the parent folder. The Agent Skills specification requires it; Cursor enforces it. Lowercase letters, numbers and hyphens only.
3. The description doesn’t match how people ask
This is the most common “it’s installed, it just never fires” cause.
At startup, tools load only each skill’s name and description (roughly a hundred tokens under the progressive-disclosure model in the specification). The full body loads only when the agent decides the task matches. So the description has to say what the skill does and when to use it, in words a person would actually type.
Vague:
description: Helps with releases.
Specific enough to match:
description: Writes release notes from merged pull requests since the last tag. Use when the user asks for release notes, a changelog entry, or a ship summary.
Claude Code’s docs say to put the main use case first: the combined description and when_to_use text is truncated at 1,536 characters in the skill listing. Codex is stricter on budget. Its docs say the initial skills list uses at most 2% of the model’s context window, or 8,000 characters when the window size is unknown. With many skills installed, Codex shortens descriptions first and may omit some skills from the list entirely, with a warning. Front-load the trigger phrases so a shortened description still matches.
If /skill-name works but free-form requests never pull the skill in, rewrite the description. Add the phrases your team uses (“PR”, “pull request”, “ship notes”) and test in a fresh session.
4. You told the agent not to invoke it
Both Claude Code and Cursor support disable-model-invocation: true. That flag hides the skill from automatic matching on purpose. You can still run it with /skill-name, but the agent will not load it because a prompt “looks relevant.”
Check the frontmatter. Also check Claude Code’s skillOverrides in settings: a value of "user-invocable-only" or "off" has the same effect from outside the file. Cursor’s Customize → Skills view is the place to confirm the skill isn’t stuck as slash-only.
5. Path scoping left it out of this task
Claude Code and Cursor both support a paths field (glob patterns). When it’s set, the skill is only surfaced while the agent is working on matching files. A skill scoped to **/*.tsx will sit quiet during a Python refactor, even if you ask for it by topic.
Nested project skills in Cursor are scoped to their directory automatically. A skill under apps/web/.cursor/skills/ only surfaces for work under apps/web/. If you’re editing a sibling package, that skill won’t appear unless you invoke it by name.
Claude Code’s docs add one more footgun: paths patterns are relative to the current working directory. Files outside it, including a sibling git worktree, don’t match even if you /add-dir the tree for file access.
6. Context is already full of other guidance
A skill can be discoverable and still lose the fight for attention.
- Too many skills. Every listed description costs tokens every turn. Claude Code’s
/skill-doctor(v2.1.252+) reports unused skills and their context cost so you can turn the noisy ones off. Codex’s 2% / 8,000-character list budget is the hard version of the same problem. - A long always-on instructions file.
CLAUDE.md, Cursor always-on rules andAGENTS.mdload every session. If those files already contain a blurry version of the same procedure, the agent may follow the always-on text instead of loading the skill. Move procedures into skills and keep instructions for facts and standing rules — the split we cover in Skills vs MCP vs Custom Instructions. - Mid-session drift. Claude Code keeps an invoked skill’s content in the conversation. After auto-compaction it re-attaches recent skills within a token budget (first 5,000 tokens of each, 25,000 combined). If Claude stops following a skill later in a long chat, the docs point you at hooks for rules that must hold every time, and at re-invoking the skill when the rendered content needs to come back in full.
7. You’re in a session that can’t see that skill
Location matters more than people expect.
- Claude Code Cowork and cloud sessions don’t read
~/.claude/skills/on your machine. They use skills enabled for your claude.ai account (and, outside project cloud threads, skills committed to the repo). A personal skill that works in the terminal can report “not found” in a scheduled cloud task. - Cursor Cloud Agents see personal skills from
~/.cursor/skills/only after Sync Skills for Cloud Agents is on. Project skills in the repo are the reliable path for shared or automated runs. - A brand-new top-level skills folder in Claude Code isn’t watched until you run
/reload-skillsonce. Edits inside a folder that already existed when the session started are picked up live.
A short fix order
Work top to bottom. Stop when the agent starts using the skill on a fresh request.
- Confirm the skill appears in
/skills, Customize → Skills, or$//. - Fix path and
SKILL.mdnaming if it doesn’t. - Fix frontmatter: first-line
---, valid YAML,namematches folder, non-emptydescription. - Invoke it by hand (
/skill-nameor$skill-name). If that works, the file is fine — improve the description and dropdisable-model-invocationif you set it by mistake. - Check
paths, nested-directory scoping and which machine / cloud session you’re in. - Trim unused skills and move overlapping procedures out of always-on instructions.
When “ignored” is actually correct
Sometimes the agent is doing the right thing. A skill about database migrations shouldn’t fire on a CSS tweak. A deploy skill with disable-model-invocation: true should wait for you. If the description says “Use when merging to main” and you asked about a draft branch, a miss is a win.
Write the description for the requests you want, test those requests in a clean session, and keep a slash command as the escape hatch when automatic matching isn’t reliable enough. When you want a known-good starting point instead of debugging a homemade one, browse the Skillaisle library.
Sources
- Claude Code docs: Extend Claude with skills
- Agent Skills: Specification
- Cursor docs: Agent Skills
- OpenAI docs: Build skills
Products change quickly. If something here no longer matches what you see, the official page above is the reference.
Related on Skillaisle
Want the setup steps? Browse the Learn guides or walk the skills aisle.