How to Read a SKILL.md in 60 Seconds

You are not going to evaluate the skill. You are going to rule out the four or five expensive mistakes — in the order that actually correlates with quality.

We score 628 agent skills on six dimensions. If you look at what separates the top 18 (9.5 and above) from the middle 214 (7.5 to 8.5), the ranking is not what the discourse would predict:

Structure has the widest spread, workflow design contributes the most points, and security — the thing everyone talks about — accounts for about 4.6% of the difference. (The full analysis is here.)

That ordering is also the order to read in. Not because security doesn't matter, but because the security you can see in 60 seconds is mostly a binary you can check at the end, while structure and workflow are where the quality actually lives.

1. Open the file tree first — 15 seconds

Before reading a single line, look at what ships alongside the SKILL.md.

skill-name/
├── SKILL.md          ← should be lean
├── references/       ← detail, loaded on demand
├── scripts/          ← runnable code
└── assets/           ← templates, fonts, icons

Green flag: a SKILL.md under a few hundred lines with the depth pushed into references/. This is what progressive disclosure looks like — the agent reads the summary, and only loads the detail when it needs it.

Red flag: a 900-line SKILL.md with no references/ directory. Everything is loaded on every activation. It also means the author never had to decide what matters.

This is the single highest-signal check in the whole routine, and it takes the least time. Structure is where the widest gap between good and average skills is.

2. Find the negative space in the description — 10 seconds

The description field is the router. Read it and ask one question:

> **Does it say when this skill should not fire?**

Most descriptions say what the skill does. Many say when to use it (Use when the user asks to…). Very few name the adjacent requests that should go somewhere else.

# weak
description: Reviews contracts and identifies legal risks.

# strong
description: Reviews a contract against a risk taxonomy and returns findings
  with severity and suggested redlines. Use when the user asks to "review this
  contract", "check this NDA", or "flag risky clauses". Not for drafting new
  agreements (use an NDA generator), not for jurisdiction-specific compliance
  questions (use a compliance skill).

A skill with no negative space will fire on everything adjacent to it. Install three of those and your agent starts loading the wrong instructions for ordinary requests — worse than not installing them.

3. Scroll to the end of the workflow — 15 seconds

Workflow design is the heaviest dimension in the rubric, and most of it is decided by one thing:

> Is there a step that verifies the result before claiming done?

Look for a final step like "check the output renders", "diff against the source", "run the tests", "confirm the file opens". A skill that produces and stops is a generator, not a workflow. You will be the one who discovers the failure.

Red flag: the last numbered step is "return the result" or "summarize". Nothing checks.

4. Look at the commands — 10 seconds

Concrete or vague?

# concrete
pandoc input.docx -o output.pdf --pdf-engine=xelatex

# vague
Run the conversion tool with the appropriate options.

Vague commands look harmless and fail in the field, because the agent has to guess the arguments — and it will guess differently than you would.

5. Spot-check one path — 5 seconds

Pick any file the skill references and confirm it exists in the package. Skills regularly reference files the author forgot to ship, especially in the scripts/ and assets/ directories.

This is the cheapest possible test of whether anyone ran the skill after packaging it.

6. Then, and only then, check what it touches — 5 seconds

Security in the rubric is mostly a floor, not a differentiator: 92% of the directory scores 9 or above. Almost everything published is clean. But "clean" is not the question you have — the question is scope.

Scan the scripts and the instructions for:

• What it reads — your project files only? Environment variables? A home directory?
• What it sends — to which hosts? Is that host in the skill's stated purpose?
• What it persists — config files, shell profiles, browser profiles?
• What it asks the agent to execute — does it hand the agent a shell command built from untrusted input?

The clearest signal is the gap between what the description promises and what the capability manifest actually contains. A skill that formats Excel files has no business reading your keychain. Confirmed credential access, exfiltration, or injection caps a skill at 39/100 in our scoring — and it is rare, which is exactly why the mismatch is the thing to look for.

The 60-second verdict

If all six pass, you have a skill worth installing. If one fails, you have a decision to make rather than a surprise to discover in production.

The rubric behind this is public at methodology, and every skill page shows the same six scores with the written reasoning for each — so you can compare your read against ours, and disagree with a specific number instead of the whole system.