Skills tab: add a per-skill 'health/linter' view (size band, preamble check, structure, openness-aware dev/publish warning)

Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity

Closed general

John Lauer · 14d ago ·closed by Colby Knox

Feature: a "skill health" / linter view on the page Skills tab, so an author (or their AI) can tell at a glance whether each skill is written well — without hand-counting lines.

Today the Skills tab lists each skill's name + description by tier (User / Dev / Publish). What it can't tell me: is a skill too long (the AI skims it), too short (underspecified), or missing a proper preamble? Right now I have to clone the repo and hand-count. The page already has every SKILL.md — it can lint them.

Per-skill health chips (cheap, high-signal):

Size — line + word count, with a band: e.g. green ~30–250 lines, yellow 250–450 (getting long), red >450 (the model likely skims it — split or move detail to referenced files). Flag <25 lines as "probably too thin." (For reference: the pup user skills are 69–119 lines = green; the two maintainer skills are ~260 = yellow.)
Preamble — ✅/❌ on: name present; description present AND contains trigger words (the discovery signal — a description with no triggers is nearly invisible); user-invocable set; and for a sub-skill, a Parent skill: first body line.
Structure — has ≥1 heading, has ≥1 example / code block, isn't a single wall of text. A skill with zero examples or zero headings is a smell.
Description length — flag a description that's empty/tiny (won't route) or absurdly long.

Tier-completeness warning — but ONLY when relevant (open vs closed source):

If the repo is open source and ships app/bridge code but has no dev or publish skill anywhere in the repo, show a gentle "no maintainer skills — this may be under-documented for contributors." (Per the Bridge SDK, dev/publish skills for an open-source project live source-only in the repo — dev-skills/ + publish-skills/ — so the page CAN see whether they exist.)
If the repo is closed source, DON'T warn — its dev/publish skills legitimately live in a private repo the wiki can't see, so their absence here is correct, not a defect.

Why it helps: it turns "did the AI write these skills well?" from a manual clone-and-count into a glance, and it nudges authors toward right-sized, properly-preambled, well-structured skills — which directly improves how well every consuming AI can actually use them. Happy to be a test case (the pup page has 5 user + 1 dev + 1 publish skill to lint).

1 Reply

Colby Knox · 13d ago

Shipped to prod. The Skills tab now lints every SKILL.md: a size chip banded by line count (green <=250, yellow 250-450, red >450 likely-skimmed, thin <25 underspecified) with word count; preamble checks (name, description, a WHEN-style trigger cue in the description, user-invocable, and the parent link for user sub-skills); structure signals (headings, an example/code block, wall-of-text). Plus the openness-aware nudge: an open-source app shipping no dev-skills/ or publish-skills/ gets a gentle 'no maintainer skills' banner, while closed-source apps are exempt since their maintainer skills legitimately live in a private repo. Amber marks are nudges with explanatory tooltips, never hard failures. Live example: adom/hook shows green size + flags its missing trigger cue and user-invocable. Logic lives in lib/skill-health.js as pure functions with a 32-assert unit test.