Claude skill not triggering: causes and fixes for Claude Code and the Claude app

A Claude skill usually fails to trigger because its description does not match the words in your request, so Claude has no reason to load it. The other common causes are that the skill never loaded (wrong folder, broken frontmatter, a refused name, or switched off) or that a setting such as disable-model-invocation: true stops Claude from invoking it on its own.

This page walks through each cause in the order you should check it, for both Claude Code and the Claude app, using Anthropic's official docs as read on 28 October 2026. For the basics of how skills work, start with Claude skills or Claude Code skills.

Why isn't Claude using my skill?

Work down this table. Each row is a cause the official docs describe.

The Claude Code troubleshooting section suggests the same first steps: check the description includes keywords users would naturally say, verify the skill appears when you ask "What skills are available?", rephrase your request to match the description, and invoke it directly with /skill-name to confirm the instructions work.

Is the skill in the right folder?

A skill is a folder with a SKILL.md file inside it. In Claude Code, the main locations are ~/.claude/skills/<skill-name>/SKILL.md for personal skills and .claude/skills/<skill-name>/SKILL.md for project skills, according to the skills docs. The debugging guide lists a loose .claude/skills/name.md file as the reason a skill doesn't appear in /skills.

Location rules that catch people out:

• Nested folders load late. Skills in a .claude/skills/ below where you started Claude Code "don't load at startup." They load the first time Claude reads or edits a file in that subdirectory. Run /add-dir with the path to load them sooner.
• Personal skills don't reach Cowork or cloud sessions. Those sessions don't read ~/.claude/skills/ on your machine. Enable the skill for your claude.ai account instead, or commit it to the repository for cloud sessions other than project threads.
• New top-level folders aren't watched. Claude Code picks up edits to existing skill directories without a restart, but if you create a skills directory that didn't exist when the session started, run /reload-skills.
• Reserved names don't load. Don't name a folder synced, and outside a plugin a skill named anthropic-skills or starting with anthropic-skills: doesn't load.
• Same name, different place. Enterprise beats personal, and personal beats project, so a personal deploy skill hides a project deploy skill when you type /deploy.

In the Claude app, the help article says skills "require the code execution environment to function." Turn on code execution in Settings, Capabilities (Free, Pro, Max) or ask an owner to enable it in Organization settings (Team, Enterprise). Then check the skill is switched on in Customize, Skills. If skills appear greyed out, code execution may be disabled.

Is the frontmatter valid?

Claude Code reads frontmatter "only when the opening --- is the file's first line." A blank line or a comment above it turns the whole header into body text. And if the YAML between the markers doesn't parse, the skill "still loads with no fields set." That is why a skill can run fine from /skill-name while Claude never chooses it: there is no description to match.

To find the problem:

• Start Claude Code with claude --debug and read the parse error.
• Run claude plugin validate .claude/skills (or ~/.claude/skills) to find SKILL.md files whose frontmatter doesn't parse. This needs Claude Code v2.1.233 or later.
• Check field spelling. Claude Code "ignores a field it doesn't recognize without reporting an error," so disable_model_invocation with underscores does nothing.

Name rules. The Agent Skills specification says name must be 1 to 64 characters of lowercase letters, numbers and hyphens, must not start or end with a hyphen or contain --, and must match the parent directory name. Anthropic's authoring best practices add that it cannot contain XML tags or the reserved words anthropic or claude, and that description must be non-empty and at most 1,024 characters.

Refused names. Claude Code refuses names with hidden characters such as a zero-width space, direction-changing characters, odd blanks like a no-break space or double spaces, or < and >. A startup notice tells you a name was refused; search the debug log for [names] to see which one.

Why does the description decide whether a skill fires?

Because it is the only part Claude sees before deciding. Claude Code loads skill names and descriptions into context and loads the full skill only when it is invoked. Anthropic's best practices say Claude uses the description "to choose the right Skill from potentially 100+ available Skills."

What the docs recommend:

• Say what it does and when to use it. Include the file types, tools and phrases people actually type.
• Write in third person. "Processes Excel files and generates reports," not "I can help you."
• Put the key use case first. In Claude Code, the combined description and when_to_use text is cut at 1,536 characters in the skill listing.

A before and after:

# Too vague to match
description: Helps with releases

# Matches how people ask
description: Writes release notes and changelog entries from merged pull requests. Use when the user asks for release notes, a changelog, or a summary of what shipped.

If a skill fires too often, the docs give the reverse fix: make the description more specific, or add disable-model-invocation: true so it only runs when you call it.

Did a setting stop Claude from invoking it?

Several settings block automatic use on purpose:

• disable-model-invocation: true means Claude can't invoke the skill on its own, and its description isn't in context at all. You can still run it with /name.
• skillOverrides in settings can set a skill to "on", "name-only", "user-invocable-only" (shown as user-only in the /skills menu) or "off". Highlight a skill in /skills and press Space to cycle states.
• Permission rules such as a deny on Skill(deploy *) block that skill, and denying Skill blocks all skills.
• paths limits a skill to matching files inside Claude's current working directory. Files in a sibling worktree don't match.

In Codex, the equivalent switch is allow_implicit_invocation: false in a skill's agents/openai.yaml, per the Codex skills docs.

Can too many skills stop a skill from triggering?

Yes. Every skill in the listing costs context on every turn, so Claude Code caps the listing. The docs say the budget "scales at 1% of the model's context window," and when it overflows, Claude Code "drops descriptions starting with the skills you invoke least." The skill name stays, but the keywords Claude needs to match your request are gone.

How to check and fix it:

1. Run /doctor for an estimate of the listing's context cost and its biggest contributors, or look at the Skills row in /context.
2. Run /skill-doctor (v2.1.252 or later) to see what each skill costs and how often it gets used. It flags skills that have never been invoked.
3. Set low-priority skills to "name-only" in skillOverrides so they list without a description, or turn them off.
4. Raise the budget with the skillListingBudgetFraction setting (for example 0.02 for 2%) or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

Codex has a similar limit. Per the Codex skills docs, its skills list uses at most 2% of the model's context window by default, or 8,000 characters when the window is unknown. With many skills it shortens descriptions first and may omit some skills with a warning; skills.max_context_tokens sets a different budget, up to 10,000 tokens.

The cleanest fix is installing fewer skills per project. Keep your full library somewhere else and install only what a repository needs.

Why does a skill stop working partway through a session?

When a skill is invoked, its content "enters the conversation as a single message and stays there across later turns," and Claude Code does not re-read the file. Two things follow from the skill content lifecycle:

• Compaction trims skills. After auto-compaction, Claude Code re-attaches the most recent invocation of each skill but keeps only the first 5,000 tokens of each, within a combined 25,000-token budget. Older skills can drop out entirely. Invoke the skill again, and keep the critical instructions near the top of SKILL.md.
• One-time steps fade. Write guidance as standing rules ("Run the tests after every edit") rather than single steps. For a rule that must hold every time, the docs recommend a hook instead of an instruction.

Why won't my skill upload to the Claude app?

The Claude help article lists these common reasons for upload failures:

• ZIP file exceeds size limits
• Skill folder name doesn't match the skill name
• Missing required skill.md file
• Invalid characters in skill name or description

Uploads also enforce the Agent Skills field list. Claude Code's docs show the hard error you get for a Claude Code-only field: Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name. Strip fields like argument-hint, disable-model-invocation and context before uploading.

On Team and Enterprise plans, a missing upload option can also mean an owner has turned off user-created skills.

How do you confirm the fix worked?

Ask for the task in the words you expect to use and watch whether Claude loads the skill. Anthropic's help article recommends testing "with a few different prompts" after uploading, and being explicit if needed, for example "Use my brand guidelines skill to create a presentation." For skills shipped in a plugin, Claude Code can measure trigger rates across many prompts with claude plugin eval and a tool_used: Skill grader.

Small, specific skills with sharp descriptions trigger more reliably than one large skill. Kipt keeps your skills as SKILL.md folders in a private GitHub repo you own, and the free SKILL.md generator checks the 64-character name and 1,024-character description limits before you save. For the full authoring checklist, see how to write a SKILL.md. If you are deciding what should be a skill at all, AGENTS.md vs skills covers when always-on context works better.