How to package a Claude Code skill as a plugin (and get it in the Discover tab)

If you've written a Claude Code skill and want other people to actually use it, a loose SKILL.md in a gist isn't enough. Claude Code has a proper plugin format now — with a marketplace and a Discover tab — and packaging your skill as a plugin is what makes it installable in one line and, eventually, discoverable to everyone.

I went through this whole process last week turning a set of freelance-admin skills into an installable plugin, so here's the concrete, no-fluff version of how it works.

The mental model

Two ideas, don't mix them up:

• A plugin is your thing: a folder with a manifest plus your skills/agents/hooks.
• A marketplace is a catalog that lists one or more plugins. A GitHub repo becomes an addable marketplace by including a marketplace.json.

The neat part: a single repo can be both — the plugin and a one-plugin marketplace that points at itself. That's the simplest setup and the one I'll show.

1. The plugin manifest

At the repo root, create .claude-plugin/plugin.json:

{
  "name": "freelancekit",
  "version": "1.0.0",
  "description": "Free /invoice skill for freelancers — describe the work in plain English, get a clean, client-ready invoice back, right inside Claude Code.",
  "author": { "name": "Your Name" },
  "homepage": "https://freelancekit.tools",
  "license": "MIT",
  "keywords": ["freelance", "invoice", "skills"]
}

Two gotchas that cost me time:

• Only plugin.json goes inside .claude-plugin/. Your skills/, agents/, hooks/ directories live at the repo root, not inside .claude-plugin/. Put them in the wrong place and Claude Code silently won't find them.
• If you set version, users only get updates when you bump it. Omit it and every commit counts as a new version (the commit SHA is used). Set it deliberately.

2. The skill itself

Skills live in skills/<name>/SKILL.md. The name in plugin.json becomes the namespace, so a skills/invoice/SKILL.md in a plugin named freelancekit is invoked as /freelancekit:invoice.

---
name: invoice
description: "Generate a clean, client-ready invoice from a plain-English description of the work. Use when the user says \"make an invoice\", \"bill this client\", or describes hours, rate, or expenses."
---

When the user describes freelance work to bill, produce a polished invoice...

The description is doing the most important job here: it's how the model decides when to fire the skill. Front-load the trigger phrases ("make an invoice", "bill this client"), not just what it does. Vague descriptions never trigger.

3. Make the repo a marketplace

Also at the root, add .claude-plugin/marketplace.json so people can add your repo directly:

{
  "name": "freelancekit",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "freelancekit", "source": "./", "version": "1.0.0" }
  ]
}

"source": "./" means "the plugin is this same repo." That's the self-pointing trick.

4. Test it locally before you ship

You don't have to publish to test. Point Claude Code straight at the folder:

claude --plugin-dir ./freelancekit

Then /reload-plugins and try your skill. claude plugin validate catches manifest mistakes before anyone else sees them — run it.

5. Let people install it

Once it's pushed to GitHub, anyone adds your marketplace and installs in two lines:

/plugin marketplace add your-username/your-repo
/plugin install freelancekit@freelancekit

6. Get into the official Discover tab

Anthropic runs a community marketplace that shows up in Claude Code's Discover tab. You submit through the in-app form (there's a claude.ai one for orgs and a Console one for individuals), it goes through automated review, and approved plugins get pinned into the anthropics/claude-plugins-community catalog, which syncs nightly. Run claude plugin validate first — the same check runs on submission.

The example is real and free

Everything above is the actual setup of a plugin I ship, so if you want to poke at a working example, the free /invoice skill installs in one line:

/plugin marketplace add ricardo-agent/freelancer-skills

or via skills.sh: npx skills add ricardo-agent/freelancer-skills. Describe some freelance work and it writes the invoice. It's the free piece of a larger freelance-admin pack, but the point here is it's a real, minimal, MIT-licensed plugin you can read to see the format end to end.

Takeaway

The barrier to sharing a Claude Code skill is now basically zero: one manifest, one marketplace file, one validate command. If you've built something that saves you time from a one-line prompt, packaging it as a plugin is a 20-minute job — and it's how it stops being your private hack and becomes something other people run.

What have you turned into a Claude Code skill? Curious what workflows other people have encoded.