How to Read a SKILL.md in 60 Seconds

You're not going to fully evaluate a skill before installing it. You're 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+) from the middle 214 (7.5–8.5), the ranking surprises people:

Structure has the widest spread. Workflow design contributes the most points. Security — the thing everyone talks about — accounts for about 4.6% of the difference.

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 check at the end, while structure and workflow are where the quality lives.

1. Open the file tree first — 15 seconds

Before reading a line, look at what ships next to 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 depth pushed into references/. That's progressive disclosure — the agent reads the summary and loads detail only when it needs it.

Red flag: a 900-line SKILL.md with no references/. Everything loads on every activation, and it means the author never had to decide what matters.

Highest signal, 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. Ask one question:

Does it say when this skill should not fire?

Most say what it does. Many say when to use it. Very few name the adjacent requests that should go elsewhere.

# 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 fires on everything adjacent. 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 "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 — and you'll 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
pandoc input.docx -o output.pdf --pdf-engine=xelatex

# vague
Run the conversion tool with the appropriate options.

Vague commands 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 under scripts/ and assets/.

Cheapest possible test of whether anyone ran the skill after packaging it.

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

Security is mostly a floor, not a differentiator — 92% of the directory scores 9+. Almost everything published is clean. But "clean" isn't your question. Scope is.

Scan for:

• What it reads — project files only? Env vars? A home directory?
• What it sends — to which hosts? Is that host in the 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 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's rare, which is exactly why the mismatch is the thing to look for.

The 60-second verdict

Check	Time	What it catches
File tree	15s	Bloated monoliths, no progressive disclosure
Description's negative space	10s	Skills that fire on everything
Workflow's final step	15s	Produces without verifying
Command concreteness	10s	Instructions the agent has to guess
One referenced path	5s	Unrunnable packages
Scope vs. stated purpose	5s	Capability mismatch

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

The rubric is public at https://skill123.me/methodology, and every skill page shows the same six scores with the written reasoning — so you can compare your read against ours and argue with a specific number.