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

说明与用途

研究表明，Claude Code 仅在技能的单行描述（或第一条非空 Markdown 行）包含与用户请求匹配的关键词时才会自动调用技能。when_to_use 字段并未增加额外匹配能力，技能名称仅贡献其字面词。

问题

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

结果

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.

工作流

• 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.

证据

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."

来源

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

来源

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

来源