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.
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.
| Rule | 2 points | 1 point | 0 points |
|---|---|---|---|
| Name | a name: field, or else the first H1, of 60 characters or fewer | a longer name | no name and no H1 |
| Description & trigger | a description: field and a trigger phrase | only one of the two | neither |
| Examples | two or more triple-backtick fences | one fence, or the word example | neither |
| Imperative steps | 3 or more list lines, at least half opening with a listed verb | any list line | no list lines |
| Scope & length | 50 to 800 words | 20 to 49, or 801 to 1,500 | under 20 or over 1,500 |
| Structure | 2 or more headings | exactly 1 | none |
Frontmatter counts only when the file opens with ---. The trigger is "when to use", "use when" (also with this, it or the skill), "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 yetA 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.
- Name, 2/2: the frontmatter name
commit-messageis 14 characters. - Description & trigger, 2/2: the description opens with "Use this when", which passes the trigger test by itself.
- Examples, 2/2: exactly two fences, opening and closing the sample commit.
- Imperative steps, 2/2: four list lines, all opening with a listed verb (Read, Pick, Write, Add), against a threshold of
⌈4 / 2⌉ = 2. - Scope & length, 2/2: 108 words.
- Structure, 2/2: four headings, the H1 and three H2s.
The total is 12, Well-formed skill. Small edits show how each rule bites:
| Edit | What changes | Total |
|---|---|---|
| Delete the frontmatter | Description & trigger 2 → 1; the name falls back to the H1 | 11 |
| Add a blank line above the frontmatter | the same, since frontmatter must open the file | 11 |
| Delete the Example section | Examples 2 → 0 | 10 |
| Start steps with Summarize, Decide, Keep | Imperative steps 2 → 1 | 11 |
| Rewrite the steps as a paragraph | Imperative steps 2 → 0 | 10 |
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
nameof at most 64 lowercase letters, numbers and hyphens and adescriptionof 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.
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.