A skill's description routes activation. The agent reads that field to decide whether to load
the skill. A narrow description misses relevant prompts. A broad description intercepts unrelated
work. Both failures produce no error.
I pulled 200 public SKILL.md files from GitHub and ran them through
tripwire's lint engine. The results:
| share | |
|---|---|
| at least one lint error | 96% |
| no lint errors | 4% |
| missing the "Use when…" activation line (of valid skills) | 95% |
Among 171 valid skills, 163 omit when the agent should load them. They describe what the skill is ("a helper for writing tests") and omit the activation cases ("use when the user adds tests, is looking at a failing test, or mentions coverage"). Authors ship a label and leave the routing signal weak.
The scan found other failures:
- 6 skills contain invalid YAML frontmatter: unquoted colons and stray quotes cause the loader to reject the file. My scanner crashed on the first one, so I changed it to count parse failures.
- 20 stuff code fences into the
descriptionfield. 13 leaveTODO/placeholder text in. - 11 use non-kebab-case names.
what the scan can prove
Tripwire classifies a missing "Use when…" line as a convention failure. Anthropic recommends the pattern because it sharpens activation. A static scan measures the text and cannot prove that a specific skill misfires in a live session. That proof requires a prompt matrix and real agent runs. Tripwire supports those runs; this post covers the free lint check.
The defensible claim is: 95% of published skills leave their activation signal weaker than the recommended convention.
why the miss repeats
The Agent Skills specification opened in December 2025. Within about 90 days, 30+ agent tools supported it, including Codex CLI, Gemini CLI, VS Code, Cursor, and Goose. skills.sh lists about 90,000 skills. The routing field remains a freeform string with no compiler, test, or editor warning. Authors get no feedback when it drifts.
Tripwire adds the missing checks: lint for the file and agent runs that can gate a PR on activation behavior.
Try it on your own skill: paste a SKILL.md into
tripwire.bharath.sh and inspect the result. Or run:
npx tripwire-skills lint ./skills/yours/SKILL.md