Guide

How to write a good SKILL.md: the checks behind an A grade

A good SKILL.md has a third-person description that says when to use the skill, in 30 to 1,024 characters; a body of real instructions under markdown headings with no placeholders; under 500 lines, with the bulk moved into a references/ folder; a lowercase-hyphenated name; a licence, a version and evals; and none of the patterns a security scan flags, such as piping a remote script into a shell or reading credentials.

Published 6 November 2026. The checks are the ones behind every grade in the 24 September 2026 snapshot.

How a skill's grade is made

The engine scores architecture (55% of the intrinsic score) and maturity (45%), and a security finding can cap the result. A is 90 and up, B 80 to 89, C 70 to 79, D 55 to 69 and F under 55. In the 396 public marketplace skills we benchmarked, 43% declare a licence, 15% a version and 7% ship evals, which is why most skills lose their grade on maturity rather than on their writing.

Write the description so the skill fires at the right moment

The description is what the agent reads to decide whether to load the skill. Write it in the third person, name the trigger ("Use when…") rather than summarising the workflow, and keep it between 30 and 1,024 characters.

The five architecture checks

01. Triggerability (25% of architecture)

Whether the description will make the model reach for this skill at the right moment.

  • No description at all: score 0
  • Description under 30 characters: −40
  • Description over 1024 characters: −20
  • No use when style trigger cue: −25
  • Description written as an order rather than a third-person cue: −10
  • Description summarises the workflow instead of naming the trigger: −20

02. Instruction quality (25% of architecture)

Whether the body is worth loading once the skill fires.

  • Body under 200 characters: −45
  • No markdown headings anywhere in the body: −15
  • Placeholders left in: TODO, FIXME, TBD, lorem ipsum: −30

03. Modularity (20% of architecture)

Whether one skill is trying to be six.

  • SKILL.md over 500 lines: −30
  • SKILL.md over 800 lines: a further −20
  • More than 14 top-level sections: −15

04. Progressive disclosure (15% of architecture)

Whether the bulk sits in files that load on demand instead of in the context window on every session.

  • Over 500 lines: −1 per 10 lines over 500, max −50
  • Over 250 lines with no references/ to offload into: −25
  • References nested deeper than one level: −15

05. Structure and frontmatter (15% of architecture)

Whether the file is well formed enough for a harness to load it without guessing.

  • Missing frontmatter name: −45
  • name not lowercase-and-hyphens, or over 64 characters: −20
  • Missing description: −20
  • Broken relative links in the body: −10 each, max −40

The seven maturity signals

  • Complete frontmatter. A name and a description, both present.
  • Non-trivial body. More than 200 characters of instruction after the frontmatter.
  • References. A references/ directory, or links into one from the body.
  • Scripts. At least one executable file that is not SKILL.md.
  • Licence. A license field in the frontmatter, or a LICENSE file.
  • Version. A version field in the frontmatter.
  • Evals. An evals/ or tests/ directory, or a file with eval in its name.

They set the maturity level:

  • L0 Experimental. The body is thin or the frontmatter is incomplete. Nothing else is considered.
  • L1 Basic. Frontmatter and body are there. Nothing else is.
  • L2 Structured. There are references or scripts.
  • L3 Maintained. There is a licence, plus a version or references.
  • L4 Certified. There are evals, a licence, and a version.

Stay clear of the security rules

A match caps the score whatever else the skill does well. If your skill genuinely needs a shell command or an environment variable, say why in the body so a reader can judge it.

  • critical (score capped at 15, verdict unsafe): destructive rm -rf on home/root; fork bomb; pipe remote script to shell; reverse shell
  • high (score capped at 45, verdict risky): prompt-injection: ignore-previous; exfiltration language; instructs to hide actions from user; references sensitive credential env; accesses sensitive system files; executes shell/subprocess; dynamic code execution (eval/exec); base64 decode (possible obfuscation)
  • medium (score capped at 72, verdict review): reads environment variables; suspicious outbound endpoint; hidden/zero-width/bidi unicode chars
  • low (4 points off, verdict stays ok): over-broad allowed-tools ('*'); mentions secrets in text

Check your own skill

Every public skill on Skillspace already has a grade and a report; find yours under the categories, or read the full methodology. If we got a rating wrong, the methodology page says how to dispute it.