Skip to content

Publishing

How to release this plugin so people can install it, on Claude Code and Cursor. Maintainer-facing.


0. The one thing to understand first

A marketplace is just a Git repository with a marketplace.json in it. There is no upload, no review queue, and no registry account for the basic path. When someone runs /plugin marketplace add parvez3019/ai-coding-microservices-skills, their client clones this repository and reads .claude-plugin/marketplace.json.

That means pushing to main publishes. Everything below is about making that safe and discoverable.


1. Pre-flight

Run these before every release:

make check             # syntax, rebuild, drift, validation, manifests, install smoke test
make plugin-validate   # the real Claude Code loader's opinion on your manifests

make plugin-validate is the important one. It parses the manifests the way the client will, and it catches schema mistakes that a JSON linter will not.

Then a real install test, from a different directory so you are not testing the working tree:

cd /tmp && mkdir plugin-test && cd plugin-test
claude plugin marketplace add ~/repos/ai-coding-microservices-skills
claude plugin install microservices-skills@ai-coding-microservices-skills --yes

Open a session there and check: the skills appear in / autocomplete under /microservices-skills:…, /stack-profile runs, and a principle fires on relevant work without being invoked.


2. Claude Code

2.1 What is already in place

File Purpose
.claude-plugin/marketplace.json The marketplace registry — name, owner, and the plugin list
.claude-plugin/plugin.json The plugin manifest — name, version, description, keywords
skills/ Auto-discovered; no need to list skills in the manifest
agents/ Auto-discovered

source: "./" in the marketplace entry means "the plugin is this repository's root". That is why one repository serves as both marketplace and plugin.

2.2 Release

# 1. Bump the version across all seven manifests at once. The validator fails if they
#    disagree, and doing it by hand is the most common release mistake here.
make version V=0.2.0

# 2. Update CHANGELOG.md

make check && make plugin-validate

git commit -am "release: v0.2.0"
git tag -a v0.2.0 -m "v0.2.0"
git push origin main --tags
# The tag push triggers .github/workflows/release.yml, which re-runs `make check`, verifies the
# tag matches the manifests, and publishes the GitHub release from the CHANGELOG section.

Existing installs pick the new version up on /plugin marketplace update — or automatically, depending on the user's settings. Users are not pinned to a tag by default; they track the default branch. So main must always be releasable.

2.3 Getting listed publicly

Repository-based install works immediately with no listing. To be discoverable:

  • anthropics/claude-plugins-official — Anthropic's curated directory. Open a PR adding an entry. It is curated, so expect a quality bar and a wait. Highest-value listing by far.
  • Community aggregators — sites like claudemarketplaces.com index public marketplace repositories. Some crawl GitHub automatically; others take a submission.
  • GitHub discoverability — add the topics claude-code, claude-plugin, agent-skills, microservices, ai-agents to the repository. This is how most people actually find these.

2.4 Things that will bite you

  • Renaming the plugin breaks every existing install. If you must, add a renames map to marketplace.json so clients auto-migrate on their next sync.
  • main is production. There is no staging. Work on branches; merge only what is releasable.
  • Version drift across the five manifests is the most common release mistake here — which is exactly why validate-skills.sh checks it.
  • A skill with malformed frontmatter silently never loads. No error, it just is not there. Run the validator.

3. Cursor

Cursor supports the vendor-neutral Agent Plugins specification, so there are three routes, in increasing order of effort:

Route 1 — nothing to do. Cursor reads Claude Code skills from .claude/skills/. A user who runs ./tools/install.sh /path/to/project/.cursor/skills (or .claude/skills) has them.

Route 2 — the root plugin.json. Already committed, with the https://agent-plugins.org/schemas/1.0.0/plugin.schema.json schema. A conformant client auto-discovers the skills from a repository link with no extra steps. This is the route to point Cursor users at.

Route 3 — the Cursor marketplace. Submit to cursor/plugins — Cursor's plugin specification and official plugin directory. Check that repository's CONTRIBUTING for the current submission process; it has changed more than once. Listing gets you into Cursor's in-app Customize page.

.cursor-plugin/ mirrors the Claude manifests for hosts that look there. It points at the same skills/ folder — no content is duplicated.

Verify in Cursor: install into a test project's .cursor/skills/, open the project, and check the skills appear in the agent's skill list. Cursor does not support subagents, so agents/microservice-reviewer.md is ignored there — /review-service degrades to a single-pass review, which is why that workflow describes the independent pass as an addition rather than a requirement.


4. Versioning policy

Semantic versioning, interpreted for a skill library:

Change Bump
Fixing a typo, sharpening a check, adding an anti-pattern Patch
Adding a skill; adding a section to a reference Minor
Renaming or removing a skill; changing a config.yaml key; changing the .msskills/ layout Major

The major cases all break someone's existing config.yaml or their muscle memory for a slash command. Treat a skill name as a published contract — which is, pleasingly, exactly what api-contracts says about everything else.


5. Release checklist

[ ] source/ edited (never skills/ directly)
[ ] make version V=x.y.z — all seven manifests bumped together
[ ] make check — 0 errors, 0 warnings
[ ] make plugin-validate — passes
[ ] CHANGELOG.md updated
[ ] README catalogue matches the actual skill list
[ ] fresh install tested from a clean directory
[ ] at least one skill exercised end to end in that install
[ ] tag pushed, GitHub release created