Why a Claude Code Skill Won't Trigger

Your team's code review Skill has been sitting in .claude/skills/review-changes/ for a week. When you say "review this branch for me," it doesn't show up. When you ask "what does this code do," it loads, and Claude starts assigning risk levels to an explanation request.

When a Skill skips the moments it should handle and turns up where it shouldn't, the problem usually isn't in its body. It's in the moment Claude decides whether to use it. A session doesn't see the full Skill; it sees only the name and description. Claude compares your request against that description and loads the body only on a match. Describe it too broadly and explanation requests match too. Describe it in words users don't actually say and real review requests miss.

The other half of the problem is how the Skill is invoked. You probably don't want Claude deciding on its own when to start a deploy or release. The fix has three parts:

• write the description as "what it does + when to use it," using words users really say;
• choose automatic, manual, or Claude-only invocation based on side effects;
• test with two kinds of real requests: one that should trigger it and one that shouldn't.

01 Claude Decides from the Name and Description

From the moment a Skill is visible to the moment it runs, roughly this happens:

The session normally sees only the Skill name and `description`
  → a task matches, or the user invokes it explicitly
Load `SKILL.md`
  → read references, examples, or scripts as needed
  → follow the Skill's method and verify the result

Before loading the body, Claude decides mainly from the name and description. The Claude Code skills documentation defines description as what the skill does and when to use it, and Claude uses it to decide when to apply the skill. The docs also say to put the key use case first, because the combined description and when_to_use text is truncated at 1,536 characters in the skill listing.

02 Describe the Task and the Trigger

A description should name the task and the intent that triggers it, for example:

Review a branch or uncommitted changes for correctness, security, and regression risk. Use when the user asks for a review, wants a diff checked, or asks to evaluate a commit.

"Handles code-related tasks" is too broad and can pull in the review method for an explanation request. The misfire in the opening most likely comes from a description like that.

Compare two versions:

The first item on the official "Skill not triggering" checklist is to check that the description includes keywords users would naturally say. Put words like "review," "check the diff," and "evaluate a commit" in it, and "review this branch for me" finally lines up.

03 Choose the Invocation Mode by Side Effects

By default, both you and Claude can invoke a Skill:

Deploys, releases, deletions, and external notifications change outside state, so you usually decide when they start. The docs explain that with disable-model-invocation, Claude can't invoke the skill on its own, which suits workflows with side effects or timing you want to control, like /commit and /deploy. It also keeps the skill from being preloaded into subagents.

user-invocable: false only changes your entry point; Claude can still use the Skill. To stop automatic invocation, use disable-model-invocation or a permission rule. Permission rules take the form Skill(name); with Skill(deploy *) in deny, Claude can't invoke that Skill.

The Claude Code best practices use a release as the example: for a workflow with side effects, like actually cutting a release, add disable-model-invocation: true. Claude then can't start the skill on its own, and it only runs when you type /release.

How a manual entry takes arguments and stops when they're missing is covered in writing custom slash commands for Claude Code.

04 Test Filtering with Two Kinds of Requests

Testing review requests and explanation requests separately is the only way to see whether the description actually filters:

1. Use words a user would really say to test cases that should trigger, such as "review this commit for me."
2. Use a similar request that shouldn't trigger, such as "explain this function."
3. If the Skill is set to manual invocation, also check that the user entry works.

If results are off, adjust in one of two directions:

• It doesn't trigger: check whether description covers this kind of request, then check invocation limits and frontmatter.
• It triggers too often: narrow the description, or switch to manual invocation.

The official checklist adds a few more checks:

• ask Claude "What skills are available?" to confirm it appears in the list;
• rephrase the request to match the description more closely;
• if the Skill sets paths, confirm the files Claude reads or writes are inside the current working directory;
• if the frontmatter YAML is malformed, the body still loads with empty metadata, so /skill-name works but Claude can't match against the description; start with --debug to see the parse error.

Once a Skill loads, its body stays in the conversation. The description decides when it comes in; how much it brings depends on how the body and supporting files are organized, covered in how to split a long SKILL.md file.

Back to the opening: change the description from "handles code-related tasks" to a version that names reviews, diffs, and commits, then try "review this branch for me" and "what does this code do" once each. When it shows up for the first and stays out of the second, decide whether to let Claude invoke it automatically.