Publishing a skill to the registry

Writing a good SKILL.md is the hard part. Getting it onto the registry is the part people ask about most, mainly because the steps aren’t obvious until you’ve done them once. This post walks through the whole path: authenticating, checking your skill before anyone else sees it, publishing, and updating it later.

Install the CLI and log in

If you haven’t already, install the CLI:

npm i -g skillmds

Publishing requires a token. If you already have one, pass it directly:

skillmd login --token <token>

If you don’t have a token handy, run skillmd login with no arguments and follow the interactive prompt instead. Either way, the CLI stores the result in ~/.skillmd/config.json, so you only need to log in once per machine. Every later skillmd publish reads the token from that file automatically.

skillmd login

If you switch accounts or move to a new machine, just run login again. It overwrites the stored token.

Dry-run before you publish anything

Once you’re authenticated, don’t jump straight to publishing. Run a dry-run first:

skillmd publish --dry-run

This lints your skill and reports what it finds, but it does not submit anything. Use it while you’re still editing the SKILL.md file, especially if you’re not sure whether your frontmatter or structure will pass. It’s the same check that runs when you publish for real, just without the network call at the end.

Publish

When the dry-run is clean, publish from the same directory:

skillmd publish

By default this targets the current directory (.), so run it from wherever your SKILL.md lives. You can also point it at a different path as the target argument:

skillmd publish ./skills/pdf-extraction

If the linter finds errors, skillmd publish refuses to submit. This isn’t a suggestion you can override: a skill with lint errors does not reach the registry, full stop. Fix what the linter flagged and run it again.

Warnings are treated differently. If the only issues are warnings, not errors, you can push past them with --force:

skillmd publish --force

--force will never publish over an error. It only lets you proceed when what’s left is a warning you’ve decided to accept. If you’re publishing a multi-skill pack rather than a single skill, tell the CLI so it validates the right shape:

skillmd publish --type pack

The default is --type single, which is what most publishers use. Use --type pack when you’re shipping a directory of related skills together as one listing.

What happens after you submit

Publishing doesn’t make your skill visible immediately. Every submission goes through review before it appears in search results or on skillmd add. This is true whether it’s your first skill or your fiftieth.

Two things happen once you submit:

1. Your skill is queued for review before it’s listed publicly.
2. A safety review runs on every skill, and the resulting verdict shows on the skill’s page once it’s live.

You don’t need to trigger the safety review yourself or configure anything for it. It runs automatically as part of submission, and the verdict is the thing visitors see when they land on your skill’s page, not the process behind it.

The verified badge

Some publishers carry a verified badge next to their skills. That badge is tied to the publisher, not to any individual skill, and it signals that the account behind the listing is a trusted publisher. Publishing a single well-reviewed skill doesn’t grant it on its own. Treat it as a separate track from the standard review every skill goes through.

Updating a published skill

There’s no separate “update” command. If you need to change something after a skill is live, edit the SKILL.md and publish again from the same directory:

skillmd publish

The CLI matches it to the existing listing by name and owner, so a second skillmd publish updates the listing in place instead of creating a duplicate. The updated version goes through the same lint check and safety review as any other submission. There’s no fast path that skips review just because the skill was already live.

Use --dry-run before republishing changes too, especially if you touched the frontmatter or restructured sections. It’s the fastest way to catch a broken update before it goes out.

Keep the description and body honest

The fastest way to slow down your own review is a description or body that doesn’t match what the skill actually does. Reviewers, human or automated, are checking the listing against the behavior, and a mismatch is the kind of thing that gets flagged.

A few habits that keep skills passing review cleanly:

• Write the description in plain terms that match the skill’s actual trigger conditions, not aspirational ones.
• If the skill calls out to an external API or writes files, say so in the body. Don’t leave reviewers to discover it.
• Update the description when you update the behavior. A skill that grew new capabilities but kept an old, narrower description reads as inaccurate even if nothing in it is technically false.
• Keep examples in the body runnable. An example that doesn’t match the current command syntax is one of the more common reasons a review takes longer than expected.

None of this is about gaming a check. It’s the same bar you’d want from any skill you installed from someone else: what it says it does is what it does.

Recap

Log in once with skillmd login, dry-run early and often with skillmd publish --dry-run, and publish with skillmd publish when the lint is clean. Errors always block a submission; --force only overrides warnings. After that, review and the safety check happen on their own, and republishing is just running skillmd publish again from an updated directory.