From SKILL.md to a live listing: the publishing checklist

Publishing is deliberately boring, and that is the feature. If you already have a working SKILL.md, the distance between that file on your disk and a live listing on the shelf is one short checklist — a handful of fields, all of them checked while you type. There is no submission queue, no reviewer's inbox, no wait to hear back. You paste, we lint, you publish. The whole ceremony fits inside the time it takes to make a coffee, and most of that time is you re-reading your own description, which is time well spent.

We keep it this short on purpose. The gates that matter are few and fixed, and the same gate runs whether you are publishing for the first time or editing a listing that has been live for a month — so nothing can slip in through a side door on the second pass. Here is the whole thing, in the order you meet it.

What the counter actually checks

Most of this list you clear without thinking. It is written down so you know exactly where the walls are before you walk into one.

• A file named SKILL.md, sitting at the root of the skill. That is the file an agent reads first, so it is the one thing we insist on. Everything else is optional.
• Extra files, if you want them — templates, a reference doc, a script or two. They ride along as long as the whole skill stays at twenty files or fewer, and each file stays under 64KB. Skills are meant to be lean; if you are brushing that ceiling, the skill is probably two skills.
• A title between 3 and 80 characters. It heads the card and it seeds the URL slug, so a verb and a noun beat a clever pun. The slug is the listing's identity — installs, inbound links, and the manifest URL all key off it — so it never changes once you publish, even if you later rename the title.
• A one-liner between 10 and 200 characters. This is the description that sits under the title on every card. It is the field most people underspend, so it gets its own section below.
• A shelf. Every skill lands in exactly one category. Pick the one a stranger would look under, not the one that flatters the skill.
• At least one proof link, and every link carries a title. You can attach up to three. This is the receipt, and it also gets its own section, because it is the part people are tempted to skip.

Two things are optional but worth the extra minute. You can attach up to six proof images, a megabyte each — a screenshot of the diff, the passing run, the before-and-after. And you can write a longer guide, up to ten thousand characters, for the reader who wants the why before the install. Skip both and the skill still ships. The gate only holds you on the essentials.

Write the one-liner like it costs a dollar a word

Two hundred characters sounds generous until you are standing inside it. The one-liner is the only sentence most people read before they decide to install or scroll on. It is doing the work a whole README used to do, in the space of a subtitle.

So spend it on what the skill does and when it fires, not on adjectives. "Flattens divs, dedupes utilities, extracts variants" tells a reader exactly what lands in their repository. "A powerful CSS tool" tells them nothing and costs the same. The minimum is ten characters, which is enough to be lazy; the ceiling is two hundred, which is not enough to hide. Aim for the sentence a colleague would forward without editing.

The proof link is the receipt, not decoration

An anonymous skill is a claim with nothing behind it. The proof link is where you put the something. It is the reason the gate requires at least one, and the reason we would quietly like you to add the second and third.

A good receipt is a link a skeptic can click and come away convinced: the pull request the skill opened, the thread where it settled an argument, the run that went green, the audit it produced. Every link ships with a title, so "PR #4012: migration cleanup" reads as evidence rather than a naked URL. The gate is one link. The honest bar is one link that survives someone actually following it.

The proof is the listing. Everything else is decoration.

This is the whole reason the directory means anything. Installs are counted, retention is counted, and the file is readable in full before it ever touches someone's setup. A listing with real receipts compounds; a listing without them is just a file you uploaded.

Point at a repository instead of pasting

If the skill already lives in a repository, you can skip the paste entirely. The publish wizard has a panel that reads, plainly, "Point at a repository." Paste a github.com/you/repo/tree/… URL, or browse the repositories you have granted the app and drill down folder by folder until you reach the one holding the SKILL.md. Private repositories are included; the app reads only what you grant it.

When you import, the files come in and Haiku drafts the listing for you — a proposed title, a one-liner, a shelf — read off what is actually in the folder. It saves you the blank-page tax on the fields above.

Hold on to one thing here: the draft is a draft. Haiku is a fast first pass, not a signature. Read every field before you publish, because the moment you hit publish the listing carries your name, not the model's.

The importer drafts the listing. You are the one who signs it.

There is a nicety for the well-organized. If you point at a folder that turns out to hold several skill folders rather than one — a whole shelf's worth in a single directory — the importer notices and offers to draft all of them at once. You still review each before it goes live, but you do it from a running start instead of from nothing.

Box the shelf into a kit

Once two or more of your skills are live, there is one more move worth knowing. You can box them into a kit — a labeled crate of related skills that a reader installs as a set. A landing-page skill, a dashboard skill, and a backend skill are stronger sold as one box than scattered as three loose files.

A kit lives on the same /@you/slug shelf as your skills and shares their namespace, so it behaves like any other listing: named, counted, readable. It is not a separate publishing ritual to learn — it is what you reach for after the checklist, once you have enough on the shelf to arrange.

That is the whole ceremony. A SKILL.md at the root, a title, a one-liner you would forward, a shelf, and a receipt that holds up. Point at the repository if you have one; box the skills into a kit once you have a few. Then publish, and the install curve starts at zero — which is exactly where every good curve starts.