Will Claude Code call your skill on its own? 38 runs, one skill, seven ways to describe it

Description and use

It was found that Claude Code auto‑invokes a skill only when the one‑line description (or first non‑empty markdown line) contains words matching the user’s request. The when_to_use field does not add extra matching power, and the skill name contributes only its literal words.

Problem

Determining how Claude Code decides to auto‑invoke a skill based on its description, name, and frontmatter.

Outcome

A skill is auto‑invoked only when the one‑line description (or first markdown line) contains words that match the user’s request. The when_to_use field does not add extra matching power beyond the description. The skill name contributes only its literal words. A vague description can be rescued by a matching heading or by user words in the request.

Workflow

• 1. Create a temporary directory with a single skill SKILL.md and a project settings file disabling bundled skills.
• 2. Run Claude Code CLI with --setting-sources project and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 to isolate the skill.
• 3. Vary the skill’s frontmatter: description, when_to_use, no frontmatter, different headings, or rename the directory.
• 4. Issue three types of requests: direct, indirect, and negative, each three times.
• 5. Count invocations by detecting a Skill tool_use block or the marker "Refs: none" in the transcript.
• 6. Record results for each variant.
• 7. Analyze which variants triggered the skill and why.

Evidence

The specific description was: "Writes git commit messages in this repository's house format (type(scope): summary line, a short why, a Refs line). Use when the user asks for a commit message or wants a diff summarized for the git log."

Source

With the vague description, Claude answered all six direct and indirect requests itself, in one turn, without looking at the skill.

Source

The skill fired 6 times out of 6, as reliably as the carefully written description.

Source