what makes a skill worth paying for: the before-and-after test
The review rules behind every skillbay listing, and how to write a SKILL.md that passes them: one prompt, answered without and with the skill, has to come out clearly better.
Nick Khami · · 4 min read
Most skills people post are not bad. They are general. They tell the agent things it already knows, in a longer form, and the output does not change. This post is the test every skillbay listing has to pass, and what the ones that pass have in common.
TL;DR #
- The test is one prompt, answered twice: without the skill and with it. If you cannot show a difference a reader would notice, the skill is not ready.
- Skills that pass are narrow. They come from someone who has done the exact job many times and can say what a generalist gets wrong.
- Write the
descriptionas a trigger, not a summary: when should the agent load this, and when not.
The before-and-after test #
Every submission to skillbay has to include at least one worked example: a prompt, the agent's answer without the skill, and the agent's answer with it. This is the first thing a reviewer reads, before the description, before the seller's bio.
The reason is that it is the only thing that cannot be faked with good writing. A confident description is easy. A "with" answer that is clearly better than the "without" answer, on a prompt a real user would type, is hard, and it is the entire value of the skill.
What "clearly better" means in practice:
- A reader with the job's context would pick the "with" answer without hesitating.
- The difference is specific: a structure the agent did not use before, a check it did not run, a mistake it stopped making. "More detailed" is not a difference.
- The prompt is realistic. Not a prompt engineered to make the skill look good.
Narrow beats broad #
Skills that pass are almost always narrow. "Postgres query planner tuning" passes review. "Backend engineering" does not, because nobody is an expert in backend engineering; people are experts in ten specific things inside it.
skillbay asks every submitter three questions and rejects job titles as answers:
- What is your specialty? The narrow field, not the role. "Enterprise B2B sales decks" rather than "sales".
- How many times have you done exactly this? Dozens is a normal answer. Once is a red flag.
- What does a generalist get wrong? If you cannot name the failure mode, the skill probably does not fix one.
The third answer is usually the skill. A seller who says "agents write sales decks like college essays, one paragraph per slide, no numbers, no ask" has already written the most important paragraph of their SKILL.md.
How to write the SKILL.md #
The frontmatter has two fields that matter:
---
name: b2b-sales-deck
description: Build an enterprise B2B sales deck outline and slide copy. Use when the user asks for a pitch, sales, or customer deck. Not for internal status decks or investor decks.
---
The description is what the agent reads to decide whether to load the skill. Write it as a trigger: what the job is, when to use it, when not to. A description that only summarizes the content gets loaded at the wrong times or not at all.
Then the body. The pattern that works:
- The failure mode first. One paragraph on what goes wrong by default. The agent needs to know what it is being corrected away from.
- The procedure. Numbered steps in the order a practitioner does them. Include the decisions, not just the actions: "if the buyer is technical, lead with the architecture slide; otherwise lead with the cost slide."
- Concrete artifacts. A template, a checklist, an example of finished output. Agents copy shape well.
- Stop conditions. What "done" looks like, and what to ask the user when information is missing.
Keep the whole thing under a few thousand words. If it needs more, split it: two narrow skills are better than one broad one.
What gets rejected #
- Generic advice the base model already follows.
- Skills without a worked example, or with an example where the two answers are nearly the same.
- Specialties that are job titles.
- Packages that ship code the reviewer cannot read, or that phone home.
Frequently asked questions #
Can I list a free skill? Yes, with the same evidence rules. Free skills install straight from the listing and from the Agent Skills index.
How long does review take? Usually a day or two. The submitter gets an email either way.
Do I need an account to submit? No. Post a skill with the evidence, or the quick way with just the file and an email; the reviewer asks for the example by email if it looks promising.
