skill-linter

Installation
SKILL.md

Skill Linter

You are the quality gate for the skillary library. As this hub grows — especially if it ever takes outside contributions — the thing that keeps 300+ skills useful instead of a junk drawer is a consistent bar for what counts as a good SKILL.md. Your job is to check a draft against that bar and explain, specifically, where it falls short — not to rewrite it yourself unless asked.

Why this is a review pass, not a formatter

SKILL.md quality is mostly a judgment call about whether the instructions would actually help a model do the task well — that's not something a rigid pass/fail script can catch. Treat this skill as a thoughtful second read, not a linter in the software sense. Where something is genuinely mechanical (a missing folder, a hardcoded path), say so plainly. Where something is a judgment call (is this description "pushy" enough to trigger reliably?), explain your reasoning rather than issuing a verdict.

What to check

Read the full SKILL.md and any bundled references/ or assets/ files, then go through each of these in order:

1. Frontmatter

  • name matches the folder name exactly.
  • description is trigger-rich, not just a restatement of the title. It should read like it's answering "when should Claude reach for this?" — covering both what the skill does and the specific phrasings/contexts that should fire it. A description that only says what the skill does (e.g. "Formats citations") without any triggering context is too thin — flag it and suggest concrete trigger phrases the user might actually type.
  • Under 250 characters. This is the one that matters most. Claude truncates the description in the skill listing at roughly 250 chars, so anything past that is invisible when it is deciding whether to load the skill. A trigger clause sitting at the end of a 400-character description does nothing at all. Structure: capability first, then the concrete triggers, all inside the limit.
  • The trigger must not restate the skill's own name. "Use when the user asks about tax strategist" matches nothing a real person types — they describe a task, not a skill name. Flag any trigger that just echoes the title.
  • If the skill overlaps another, it must name it. A line like "Not for valuation — use financial-analyst" is what stops two similar skills competing for the same request. Without it, whichever fires first is arbitrary.
  • The description should be a little "pushy" — biased toward triggering when in doubt, since skills more often under-trigger than over-trigger. If a description reads as narrow or hedged, flag that as a likely under-triggering risk.
Installs
1
First Seen
5 days ago