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.

2. Body instructions

• Written in imperative form ("Extract the API's response schema," not "The API's response schema should be extracted").
• Explains the why behind non-obvious steps, not just a checklist of MUSTs. Heavy use of all-caps ALWAYS/NEVER without reasoning is a yellow flag — note it and suggest reframing with the underlying reason instead.
• Stays general enough to handle the range of requests the description promises, rather than being hard-coded to one example scenario.
• Under roughly 500 lines. If it's approaching that, check whether it should push detail into references/ instead of bloating the main body.

3. Privacy and scope

• No personal file paths, usernames, machine-specific config, or private URLs. This is a hard fail — flag immediately and specifically, since it's the one category that shouldn't ship regardless of everything else being good.
• No third-party credits, attributions, or "built by X" content baked into the instructions.
• Nothing that resembles malicious intent (exfiltration, unauthorized access, credential harvesting) — a hard fail, no exceptions.

4. Folder structure

• SKILL.md present at the skill's root, and name matching the folder name.
• references/ only if there is genuine lookup content to split out. Do not ask for placeholder files — an empty references/ or assets/ folder is worse than none.
• Every file in references/ must be linked from the body. Agents load reference files only when SKILL.md points at them, so an unlinked reference can never be read.
• The *.skill bundle, if present, must be named for the skill. Bundles are generated by scripts/bundle.py; a mismatched name means a rename left an artifact behind.

5. Run the validator

The mechanical checks above are enforced by scripts/validate.py in the hub repo. Run it rather than eyeballing them:

python scripts/validate.py --repo <category>

Review the things a script cannot judge: whether the description's triggers match how someone would actually phrase the request, whether the instructions are specific enough to act on, and whether the skill overlaps an existing one without saying so.

Output format

Give a short pass/flag list, grouped by the four checks above. For each flag, name the specific line or section and explain the fix in one or two sentences — don't just say "description is weak," say what's missing and give an example rewrite.

## Skill review: <skill-id>

**Frontmatter** — [pass / flagged: reason + suggested fix]
**Body instructions** — [pass / flagged: reason + suggested fix]
**Privacy & scope** — [pass / flagged: reason — hard fail if triggered]
**Folder structure** — [pass / flagged: reason + suggested fix]

**Overall:** [ready to commit / needs revision before commit]

If everything passes, say so briefly — don't manufacture nitpicks to seem thorough. A clean skill should get a clean pass.

Verification & Quality Checklist

• Trigger clause names phrases a user would actually type, not the skill's own name.
• Every file the body tells the model to read exists in the skill folder.
• Instructions were run once end-to-end against a real request before shipping.
• Description states what the skill is NOT for, naming the sibling that is.

Anti-Patterns & Constraints

• NEVER ship a skill whose referenced files do not exist.
• NEVER write a description whose trigger only fires on the skill's own name.
• NEVER pad a skill body to look substantial; a thin skill should be deleted, not inflated.

References

Load these only when the task needs them:

• references/house-conventions.md