The Anatomy of a Great SKILL.md File

A skill is only as good as the moment it decides to fire. You can write a hundred lines of immaculate instructions, but if Claude never reaches for them, none of it runs. The whole game lives in one file: SKILL.md. Get it right and your skill shows up exactly when the user needs it. Get it wrong and it sits in the buyer's library, downloaded and forgotten.

Let's take the file apart and put it back together properly.

What's actually in a SKILL.md

The structure is deliberately boring. YAML frontmatter at the top with two fields — name and description — and then a Markdown body of instructions. That's it.

---
name: contract-reviewer
description: Use when the user wants to review, redline, or summarize a contract, NDA, lease, or other legal agreement. Flags risky clauses and suggests edits.
---

The Markdown body goes here: when to use the skill,
how to do the work, and what to do when things go sideways.

Two fields and some prose. The trick is that each part is doing a specific job, and most authors only get one of them right.

The description is doing two jobs

Here's the thing nobody tells you: the description is not marketing copy. It's a trigger. Before Claude ever reads your instructions, it reads the description to decide whether your skill is even relevant to what the user just asked. If the description doesn't match the situation, your skill never gets a turn.

So the description has to name the situations your skill applies to, in the words a real user would actually type.

Bad: "Helps with documents."

Good: "Use when the user wants to review, redline, or summarize a contract, NDA, lease, or other legal agreement. Flags risky clauses and suggests edits."

The bad one is a coin flip. "Documents" matches everything and therefore nothing — it fires on a grocery list and stays silent on an actual contract. The good one names concrete document types and concrete verbs, so it lights up on "can you check this NDA before I sign" and stays quiet on "help me write a poem."

One more pair, because this is the single most important habit to build:

Bad: "A powerful tool for data analysis."

Good: "Use when the user pastes CSV data or asks to find trends, outliers, or summary stats in a table or spreadsheet."

Notice the good version never says "powerful" or "tool." Adjectives don't trigger anything. Situations do. Write the description as a list of moments, not a list of features.

A useful exercise: open your draft, then imagine ten different ways a real user might ask for the thing your skill does. "Check this lease," "is this contract fair," "redline the NDA," "what am I agreeing to here." If your description wouldn't obviously match at least most of those phrasings, it's too narrow. If it would also match "summarize this article," it's too broad. You're aiming for the band in between, and you only find it by testing against the words people actually use.

Lead with WHEN, not WHAT

Open the body the same way you opened the description: by telling Claude when this applies and what a good outcome looks like — before any mechanics. A reader who understands the goal makes better decisions about the steps. A reader handed steps with no goal follows them off a cliff.

---
name: contract-reviewer
description: Use when the user wants to review or redline a contract, NDA, lease, or other legal agreement. Flags risky clauses and suggests edits.
---

## When to use this
The user has a legal agreement and wants risks surfaced before they
sign. Success means every concerning clause is flagged with a plain-
language explanation and a suggested edit.

## How to review
1. Identify the document type and which side the user is on.
2. Read clause by clause. Flag anything that shifts risk onto the user.
3. For each flag, give the clause, the risk, and a concrete rewrite.

The "When to use this" block costs you three lines and saves you from a skill that technically followed instructions while completely missing the point.

Be explicit about the failure cases

The skills that feel "smart" are usually just the ones that were told what to do when the input is bad. Everyone writes the happy path. Almost nobody writes the part where the file is empty, the document is the wrong type, or half the context is missing — which is exactly where skills embarrass themselves.

Name the failure modes out loud:

## When the input is off
- Empty or unreadable file: ask the user to re-upload before doing anything.
- Not a legal agreement (e.g. an invoice): say so and stop. Don't guess.
- Missing the user's role (buyer? landlord? employee?): ask, because
  the same clause is fine for one side and a trap for the other.

That's a few lines of "if you can't determine X, ask before proceeding." It prevents the majority of confidently-wrong outputs, and confidently-wrong is the fastest way to a one-star review.

Keep the instructions short and the judgment dense

Length is not quality. The best SKILL.md files are tight. Every sentence should either tell Claude when to do something or encode a judgment it wouldn't otherwise have. Everything else is filler, and filler dilutes the signal Claude is trying to follow.

There's a difference between short and thin. Thin instructions say "review the contract carefully." Dense instructions say "auto-renewal clauses and unilateral termination rights are the two most common traps — check for both by name." Same length. One of them actually carries judgment the model didn't already have.

A reviewer once gave me a test I still use: "If I delete this sentence, does the skill get worse?" If the answer is no, the sentence is decoration. Cut it.

Aim for instructions a sharp new hire could follow on their first day — specific enough to act on, short enough to hold in their head.

Show, don't just tell

Include one worked example: a representative input and the output you actually want back. Examples teach format and tone faster than any amount of description, because they remove ambiguity instead of describing it.

## Example
Input: "Here's my freelance contract. Anything I should worry about?"

Output:
- **Payment terms (Section 4):** Net-60 is long for freelance work.
  Risk: you float two months of costs. Suggest Net-30.
- **IP assignment (Section 7):** Assigns *all* your IP, not just work
  for this client. Suggest narrowing to deliverables under this contract.

One good example is worth three paragraphs of "be thorough and professional." It shows the structure, the voice, and the level of specificity all at once.

A checklist before you publish

Run every skill through this before it hits the marketplace:

• Does the description name real user phrasings, not features?
• Does the body lead with when and why before how?
• Are the failure cases handled explicitly, by name?
• Is there at least one concrete worked example?
• Could you delete 20% of the body without losing anything? Then do.

The logic is the easy part — it's the thing you were excited to build. The SKILL.md is the unglamorous file that decides whether anyone ever sees that logic run. It's where a skill stops being clever and starts being reliable. And on a marketplace where every purchase is one and done, reliability is the whole product. It's what turns a buyer into a five-star review, and a five-star review into your next sale.