skillhawk

Why isn't my Claude skill triggering?

Most of the time the skill's description does not tell Claude when to use it, the skill never loaded, or another skill's description competes with it. The agent decides whether to open a skill from its name and description alone, so a vague description fails silently: nothing errors, the skill is simply never used.

What to check, in order

A worked example

A real example from the Skillhawk good-versus-bad gallery. The skill notes-v2 has the description "Internal notes." and Skillhawk grades it C. After rewriting the description (the rewrite below is ours, for illustration), the same skill grades A.

$ skillhawk review examples/bad/notes-v2

C  notes-v2  ~ 811 tok  1 finding: description-no-when
     high   SKILL.md:3 [description-no-when] description does not say when to use the skill; agents decide to load a skill from its description alone
            fix: Rewrite as "<what it does>. Use when <the situations and phrases a user would say>."

# SKILL.md frontmatter, before
description: Internal notes.

# after
description: Formats meeting notes into the team template with decisions and owners. Use when the user pastes meeting notes, asks for a recap, or says "write up the notes".

$ skillhawk review notes-v2   # after the rewrite above

A  notes-v2  ~ 847 tok  no findings

The Skillhawk command that helps

Skillhawk cannot see inside a live Claude session, so it cannot tell you why one particular request did not fire. It does check the things above before you ship:

npx skillhawk validate .claude/skills
npx skillhawk review .claude/skills      # description-no-when, trigger-hijack, overlapping triggers between skills
npx skillhawk test .claude/skills/notes-v2 --static   # your trigger cases scored against sibling skills

A "why didn't it fire" replay of a real session is on our list of ideas; it is not built.

Questions

Why does Claude ignore my skill even when the description looks fine?

Check that the skill loaded at all, that no other skill has an overlapping description, and that you are not testing in headless mode, where users report skills not triggering. Then make the description name the exact situations and phrases that should trigger it.

Does Skillhawk tell me why a skill did not fire?

Not for a live session. skillhawk review flags descriptions that do not say when to use the skill, claim every task, or overlap another skill, which are the common causes you can fix before shipping.

Sources

Skillhawk is a tool in this space, so weigh our framing accordingly. Last updated 2026-11-17.

Related

Try skillhawk review