How SKILL.md files say when to use a skill: 73,322 counted

By markdownregistry. Published October 6, 2026. Updated October 6, 2026.

More than a third of SKILL.md descriptions never use the word "when" or a phrase such as "Use for". Of 72,066 SKILL.md files with a description in public GitHub repositories, 54.8% use the word "when" and another 7.5% a phrase such as "Use for"; 37.7% use neither. At startup an agent reads only each skill's name and description, so the description is what decides whether the rest of the file is ever read.

The description	Files	Share
Uses the word when or whenever	39,473	54.8%
Says when only with a phrase such as Use for or Use to	5,398	7.5%
Uses neither	27,195	37.7%
Shares its exact text with a skill in another repository	8,377	11.6%
Is shorter than 40 characters	1,065	1.5%
Is longer than 1,024 characters, the specification's limit	718	1.0%
Is written in the first or second person	280	0.4%

72,066 SKILL.md files with a description, inside skill directories in public GitHub repositories (73,322 files from 3,036 repositories in all), each read at its latest version in the registry on October 6, 2026. The first three rows add up to every description. How each was counted is under How we counted.

Counted from the registry's own crawl of public GitHub, read on October 6, 2026, against the Agent Skills specification, Anthropic's skill authoring guide and Claude Code's skills documentation as they read that day.

Why the description decides

The Agent Skills specification describes loading in stages: the name and description of every skill are loaded at startup, and the full SKILL.md only once the agent decides to activate the skill. It asks that the description say both what the skill does and when to use it, and include keywords that help an agent match a task, and it gives Helps with PDFs. as a poor example. Anthropic's authoring guide puts it more plainly: the description is how Claude chooses the right skill from potentially more than 100.

Most files say what the skill does. Fewer say when: 39,473 (54.8%) use the word "when" or "whenever", usually as the Use when ... sentence both sources show, and 5,398 (7.5%) use only a phrase such as "Use for" or "Use to". The other 27,195 (37.7%) use neither. Some of those still name a situation in other words, so read that share as an upper bound; a sample read by hand found most of them describe only what the skill does. The median description runs 242 characters, and 1,065 (1.5%) are shorter than 40; the specification's poor example, Helps with PDFs., is 16.

Trigger phrases kept outside the description

Some skills put their trigger wording in a field of its own. 1,627 files have a triggers field, which neither the specification nor Claude Code's documentation defines, and in 902 of them the description itself never uses the word "when". An agent that loads only the name and the description at startup does not see that field.

Claude Code has a field for this: when_to_use, which its documentation says is appended to the description in the skill listing, with the two together cut at 1,536 characters. 1,180 files with a description use it, and in 728 of them the description itself has no "when". The field is Claude Code's, not the specification's, so another agent that follows the specification reads the description alone. In 34 of the files that use it, the description and when_to_use together run past Claude Code's 1,536-character cut.

Fields beyond the specification

The specification defines six fields: name, description, license, compatibility, metadata and allowed-tools, and says properties it does not define go in metadata, which 17,397 files use. 12,154 of the 72,388 files whose frontmatter could be read (16.8%) use a field Claude Code adds, such as argument-hint, user-invocable or disable-model-invocation. And 19,792 (27.3%) carry a top-level field defined in neither source. The commonest is version, at the top level in 7,645 files, where the specification's own example puts it under metadata; then category, author, tags and triggers.

Two smaller things the sources rule on. 280 descriptions (0.4%) are written in the first or second person, which Anthropic's guide says to avoid because the description is injected into the system prompt. And 253 names (0.4%) contain "claude" or "anthropic", which Anthropic's guide says a name cannot contain; that rule is Anthropic's, not the specification's.

Copies and length

8,377 files (11.6%) have a description, character for character, that a skill in another repository also has, across 2,840 distinct texts: skills copied from one collection into another, or built from the same template. The 73,322 files hold 66,644 distinct contents in all.

Both sources ask that SKILL.md stay under 500 lines, with longer material moved to files the skill points to. The median body, after the frontmatter, is 114 lines; nine in ten are 366 lines or shorter, and 3,192 (4.4%) run past 500.

Check your own skill

The specification points to its reference library, skills-ref, for validation; it says the validate command checks that the frontmatter is valid and follows the naming conventions, which does not include whether the description says when to use the skill. The library's to-prompt command, which its help describes as generating the available-skills XML for agent prompts, prints the name and description the way that block presents them. This is the output on a scratch skill whose description is written in the first person:

$ skills-ref validate pdf-tools
Valid skill: pdf-tools
$ skills-ref to-prompt pdf-tools
<available_skills>
<skill>
<name>
pdf-tools
</name>
<description>
I can help you with PDFs.
</description>
<location>
/private/tmp/skdemo/pdf-tools/SKILL.md
</location>
</skill>
</available_skills>

The skill passes validation, and the agent is left with "I can help you with PDFs." to decide when to load it. Read the description in that block on its own and ask whether it names the requests that should bring the skill in. Real SKILL.md files from other projects are on the SKILL.md page, most starred first, and the required fields are in the SKILL.md frontmatter guide. To see how the registry's audit grades a skill on GitHub, paste its link into the checker. To start a new one from a file that passes every check the registry runs, use the SKILL.md starter on mdpantry, which says what to change in it.

How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content. We took every SKILL.md it holds inside a skill directory, the path ending in /SKILL.md, and read the frontmatter of each one's latest stored version as the registry parsed it; 934 files with no frontmatter, or frontmatter that could not be read as YAML, count as having no description. A description counts when it is non-empty text. It uses "when" when the word "when" or "whenever" appears in it; failing that, it uses a phrase when it contains "use for", "use to" or "use if" (also as "use it", "use this" or "use this skill" before the last word), "if the user" or "if a user", or "trigger", "triggers" or "triggered" followed by "on" or "by". Every match ignores case except the first-person one. The person counts look for "I", "I'm", "I'll" or "I've" opening a sentence, or "I can", "I will", "I help", "I am" or "I have" anywhere, and for a description that opens with "You" or contains "you can use", "you can ask", "you can call", "you can invoke" or "your assistant". Copies are exact matches of the trimmed text in two or more repositories. A body's length is its lines after the closing frontmatter fence, read from the file's bytes, which were checked against its hash. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.

Sources

Last checked October 6, 2026.