skillhawk

How to write a SKILL.md description that triggers

Write the description as what the skill does, then when to use it, in the words a person would actually type: "<what it does>. Use when <the situations and phrases>." Keep it under 1024 characters, scope it to one job, and put detail in the body, because the agent decides whether to open the skill from the description alone.

Rules that hold up

A worked example

The same skill before and after (the rewrite is ours; the review lines are real Skillhawk output on the notes-v2 example):

# before
description: Internal notes.
C  notes-v2  ~ 811 tok  1 finding: description-no-when

# 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".
A  notes-v2  ~ 847 tok  no findings

The Skillhawk command that helps

These check the description before you ship:

npx skillhawk review <skill-dir>          # description-no-when, description-length, trigger-hijack
npx skillhawk test <skill-dir> --static   # trigger cases (tests/cases.yaml) scored against sibling skills

Passing a static check does not guarantee the model will pick the skill in a real session; it removes the common mistakes.

Questions

How long can a SKILL.md description be?

The Agent Skills format limits it to 1024 characters, and Skillhawk flags longer ones. Shorter and specific usually works better than long.

What should a skill description contain?

What the skill does and when to use it, using the words a person would type, scoped to one job.

Sources

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

Related

Try skillhawk review