Anthropic's docs are clear: a SKILL.md should be under 500 lines. Their own docx skill is 590. I read all 17 of Anthropic's official skills, frontmatter by frontmatter, while building my own marketplace alongside. Every time, the same gap: the docs say one thing, the corpus does another. And the corpus is the one that's right.
Here's what actually comes out when you read the code instead of the docs.
The description is 90% of the skill
A skill is useless if it doesn't trigger at the right moment. And what decides triggering isn't the body of the SKILL.md, it's its description in the frontmatter. Claude reads the list of available skills (just name + description) and picks. So all of the "when to use it" must live in the description, not the body.
The counter-intuitive part, which Anthropic repeats in its own skill-creator: Claude under-triggers skills far more than it over-triggers them. It only consults a skill for a task it can't handle trivially. "Read this PDF" will never fire the PDF skill, even with a perfect description. Hence an explicit instruction: write descriptions that are a little pushy.
