Vibe Engines
YouTube

Vibe Engines is free, interactive AI engineering & system design — runs in your browser. Pick a learning path

Skill Linter

A client-side linter for agent skill files (SKILL.md). Paste your skill and it scores the structure a good skill needs — a clear name and description, an explicit “when to use” trigger, concrete examples, imperative step-by-step instructions, and a scoped length — against a 12-point rubric, with per-criterion feedback on what is missing. Everything runs in your browser; nothing is uploaded. Built to catch the quality gaps that separate a curated skill from the average public one.

12/ 12
Well-formed skillpublic skills average ≈ 6.2 / 12
Name2/2
Clear name: “commit-message”.
Description & trigger2/2
Has a description and a when-to-use trigger.
Examples2/2
Includes a fenced code example.
Imperative steps2/2
4 step-style lines, mostly imperative.
Scope & length2/2
108 words — a healthy, scoped length.
Structure2/2
4 headings organize the skill.
Paste your SKILL.md

A structural lint, not a correctness check — a skill can score 12 and still teach the wrong thing. Everything runs in your browser; nothing is uploaded.

A skill is a document an agent loads to learn a procedure, and before anyone checks whether its advice is right, it has to be findable, followable and short enough to keep in context. This linter checks that structure. It runs six deterministic rules over a pasted SKILL.md, in the browser, and scores each one 0, 1 or 2.

What it computes

Each rule is named as it appears in the results panel.

Rule2 points1 point0 points
Namea name: field, or else the first H1, of 60 characters or fewera longer nameno name and no H1
Description & triggera description: field and a trigger phraseonly one of the twoneither
Examplestwo or more triple-backtick fencesone fence, or the word exampleneither
Imperative steps3 or more list lines, at least half opening with a listed verbany list lineno list lines
Scope & length50 to 800 words20 to 49, or 801 to 1,500under 20 or over 1,500
Structure2 or more headingsexactly 1none

Frontmatter counts only when the file opens with ---. The trigger is "when to use", "use when" (also "use this when", "use it when", "use the skill when" and "use this skill when"), "use this whenever" or the word "trigger", anywhere in the text. A list line starts with 1., - or *, and the verb list holds 34 verbs, from read, write and check to escalate, choose and confirm. Words are counted across the whole file, frontmatter and code included.

total = sum of the six rules, 0 to 12
10 to 12   Well-formed skill
 7 to 9    Solid, a few gaps
 4 to 6    Needs work
 0 to 3    Barely a skill yet

A worked example

The default input is a sample commit-message skill with frontmatter, an H1, When to use, Steps and Example sections, four numbered steps and one fenced commit message.

  1. Name, 2/2: the frontmatter name commit-message is 14 characters.
  2. Description & trigger, 2/2: the description opens with "Use this when", which passes the trigger test by itself.
  3. Examples, 2/2: exactly two fences, opening and closing the sample commit.
  4. Imperative steps, 2/2: four list lines, all opening with a listed verb (Read, Pick, Write, Add), against a threshold of ⌈4 / 2⌉ = 2.
  5. Scope & length, 2/2: 108 words.
  6. Structure, 2/2: four headings, the H1 and three H2s.

The total is 12, Well-formed skill. Small edits show how each rule bites:

EditWhat changesTotal
Delete the frontmatterDescription & trigger 2 → 1; the name falls back to the H111
Add a blank line above the frontmatterthe same, since frontmatter must open the file11
Delete the Example sectionExamples 2 → 010
Start steps with Summarize, Decide, KeepImperative steps 2 → 111
Rewrite the steps as a paragraphImperative steps 2 → 010

Deleting the example still earns Well-formed, because the top band starts at 10. Read the per-rule notes, not just the verdict.

Assumptions and limits

  • Structure, not truth. A skill can score 12 and still teach the wrong procedure.
  • Pattern matching. Headings and list lines are counted inside code blocks too, so a Python comment counts as a heading, and the verb list misses valid imperatives such as Summarize.
  • Platform rules are not checked. Claude requires a name of at most 64 lowercase letters, numbers and hyphens and a description of at most 1,024 characters. The linter accepts an H1 in place of a name, so a file with no frontmatter can score 11 and still fail to load.
  • The trigger can be anywhere. A When to use heading in the body passes, but an agent chooses a skill from its name and description before the body is read.

How to use the result

  • Fix zeros first. Every rule is worth the same two points, and a zero is usually a missing section that takes a minute to add.
  • Put the trigger in the description. Say what the skill does and when to use it in that one field; it is the sentence the agent matches against.
  • Write steps as commands, one action per line, so an agent can follow and check them in order.
  • Treat 800 words as a split signal. Move reference material into separate files the skill points to and keep the main file to the procedure.
  • Then test behavior. A clean lint earns a trial on real tasks, not a place in production.

When to use it, and when not

Use it as the first pass on a new or inherited skill, in review before a skill is shared with a team, or to compare two drafts. It takes seconds and catches the missing piece, usually the trigger or the example, before anyone spends time testing.

Do not use it to rank skills against each other or to approve one. It cannot see the files a skill points to, cannot tell whether two skills compete for the same requests, and has no idea whether the procedure works. Those need a run on real tasks.

Trade-offs and limits

Every rule is a cheap proxy for a property that matters, and each proxy can be satisfied without the property:

RuleRewardsMisses
Description & triggerA trigger phrase anywhereWhether the description alone tells an agent when to load the skill. A When to use heading deep in the body passes, and "Use the tool when" or "Call this for" does not match at all
ExamplesTwo backtick fencesWhether the example shows the hard case
Imperative steps34 listed verbsBuild, Push, Tag, Group and Summarize are all imperative and all score as not
Scope & lengthWords in the pasted fileFiles the skill links to
StructureLines starting with #Comments inside a shell or Python block count too

The length rule matters more than it looks. Claude keeps only each skill's name and description in context up front, loads the SKILL.md body when the skill is triggered, and reads bundled files only when the body points to them. A short body with linked references costs little until it is needed; a long body costs its full length every time it fires.

Common mistakes

  • A description that names the skill, not the situation. "Release notes helper" matches few requests. "Use when the user asks what changed since the last release, or wants a changelog" matches the ways people actually ask.
  • Steps the agent cannot check. "Write good notes" passes the verb test. "Write one line per change, linking the pull request" can be followed and verified.
  • Pasting reference material into SKILL.md. API tables and style guides push the body past 800 words and load on every trigger. Move them to a separate file and point to it.
  • Two skills with overlapping descriptions. Each lints clean on its own, but an agent matching a request against both may load the wrong one. Make each description say when not to use it.
  • Editing for the linter. Rewriting "Build the image" as "Run the build" earns a point and changes nothing for the agent. Fix what a rule points at, not the rule's pattern.

Check yourself

A skill scores 2 on every rule except the trigger: its description reads "Drafts release notes from merged pull requests." and no trigger phrase appears anywhere. What is the total?

11. The description field is present but carries no trigger phrase, so Description & trigger scores 1. Rewriting it as "Use this skill when the user asks for release notes" matches the pattern and makes it 12, and it puts the trigger where an agent actually reads it.

A skill has five numbered steps, and two start with verbs on the list. How many points for Imperative steps?

1. Full marks need at least ⌈5 / 2⌉ = 3 listed verbs. Changing one more step to a listed verb gives 2, as would cutting the list to four steps with the same two verbs, since ⌈4 / 2⌉ = 2.

No frontmatter; an H1 # Deploy; a 20-word paragraph; five steps starting Run, Build, Push, Tag, Check; and one bash block whose first line is # build the image. 57 words in all. Score?

Name 2 (the H1). Description & trigger 0: no field, no phrase. Examples 2: two fences. Imperative steps 1: only Run and Check are listed, under the threshold of 3. Length 2. Structure 2, because the bash comment counts as a second heading; without it the file would get 1. Total 9, Solid, a few gaps.

Namefield or H1 Descriptionplus trigger Examples2 fences Stepshalf: listed verb Length50-800 words Structure2+ headings each rule: 0, 1 or 2 sum0 to 12 10-12 well-formed 7-9 solid 4-6 needs work 0-3 barely
Six equal-weight checks, summed. Because every rule is worth the same two points, a missing example costs exactly as much as a missing trigger, though the trigger matters more to whether the skill is ever loaded.

How it works

  • Scores a pasted SKILL.md against a 12-point structural rubric.
  • Checks name, description and trigger, examples, steps, length and structure.
  • Per-criterion feedback on exactly what is missing.
  • Pure in-browser: nothing is uploaded or stored.

Frequently asked questions

What makes a skill good?

The same things that make any instruction good for an agent: it is discoverable and unambiguous. Discoverable means a crisp name and a description that says exactly when to reach for it, because the description is what the agent matches a request against. Unambiguous means imperative, step-by-step instructions and at least one concrete example, scoped tightly enough to sit comfortably in context next to the task. Vague, sprawling, example-free skills get ignored or misapplied, and the rubric here scores each of those properties.

How is the skill linter score computed?

Six deterministic checks each award 0, 1 or 2 points: Name, Description and trigger, Examples, Imperative steps, Scope and length, and Structure. For example, Examples needs two triple-backtick fences for full marks, Imperative steps needs at least three list lines with half or more starting with a verb from a fixed list, and Scope and length wants 50 to 800 words. The total out of 12 reads Well-formed skill from 10, Solid, a few gaps from 7, Needs work from 4, and Barely a skill yet below 4.

What are the SKILL.md frontmatter requirements for Claude?

A Claude skill needs YAML frontmatter at the top of SKILL.md with two required fields. The name can be at most 64 characters, using only lowercase letters, numbers and hyphens, with no XML tags and without the reserved words anthropic or claude. The description must be non-empty, at most 1,024 characters and free of XML tags, and it should say both what the skill does and when to use it. This linter checks that the fields exist, not these exact limits.

Why does my skill score low on Imperative steps?

The rule counts list lines, meaning lines that begin with a number and a period, a dash or an asterisk. Full marks need at least three of them, with at least half starting with a verb from the linter's fixed list, such as read, write, check, run, add, pick or verify. A paragraph of prose scores 0, and steps that start with words outside the list, such as Summarize or Decide, score only 1. Rewriting each step as a short command that begins with a common verb usually fixes it.

Is my skill uploaded anywhere?

No. The linter is client-side JavaScript: the text you paste never leaves your browser, no network request is made, and nothing is stored. Once the page has loaded you can disconnect from the network and it still works. That is deliberate, because skill files often describe internal processes, systems and conventions that you would not want to send to a server just to check their structure.

Does a perfect score mean the skill works?

No. The checks are structural, so a skill can score 12 out of 12 and still describe the wrong procedure, name the wrong tool or fire on the wrong tasks. Even the structural checks are heuristics: headings and list lines are counted inside code blocks, and the trigger phrase can sit anywhere in the file, while an agent decides whether to load a skill from its name and description alone. Treat a clean score as permission to test the skill on real tasks.