How to Build an Internal Skills Marketplace for Claude Code with GitHub

The problem: great skills trapped on one laptop

Claude Code gets dramatically more useful when you teach it your team's way of working. You capture a workflow once as a skill, a production code review, a release checklist, a way to respond to pull request feedback, and Claude runs it on demand. The trouble is that most teams keep these skills as local files. The engineer who wrote the skill benefits. Nobody else does. And when the skill improves, the improvement never reaches the rest of the team.

We hit exactly this at BetterFutureLabs. We had built a library of proprietary skills for our own development, and individual engineers had their own skills on top of the standard ones. All of that value was stranded on individual machines.

The fix is to treat your skills like any other internal package: version them, review changes to them, and distribute them from one source of truth. Claude Code supports this directly through plugins and plugin marketplaces, and a marketplace is just a GitHub repository. Here is how to build one.

What a skill actually is

Think of a skill as a short, self-contained playbook that teaches an AI assistant how to do one specific task the way you want it done. It is an open format that Anthropic introduced and made free for anyone to use, and it is deliberately simple: a skill is just a labeled document, written in plain language, plus any reference material the task needs. The assistant keeps a one-line summary of every skill on hand and opens the full playbook only when the moment actually calls for it, so a team can build up hundreds of them without ever overwhelming the assistant. And because each skill is just a simple file, it travels easily: you write it once, and anyone on your team, along with the AI they work with, can use it.

What you are building

A plugin marketplace is a GitHub repo with a specific shape, and it is how you take those skills and share them. It bundles your skills into one installable plugin, so once it exists, every teammate runs two commands and gets all of your skills inside Claude Code. When you merge an improvement and bump the version, their next session picks it up automatically. The version bump is the signal that pushes the update.

Step 1: Shape the repository as a marketplace

Create a repo and give it this structure. Only one kind of file belongs inside a .claude-plugin directory: a manifest. Everything else lives beside it.

• A top-level .claude-plugin/marketplace.json that declares the marketplace and lists your plugins.
• A plugins folder, with one folder per plugin inside it, for example plugins/your-skills.
• Inside each plugin, its own .claude-plugin/plugin.json manifest and a skills folder.
• Each skill lives at plugins/your-skills/skills/skill-name/SKILL.md.

The one structural rule to remember: never put your skills, commands, or hooks inside a .claude-plugin directory. Only the manifest goes there.

Step 2: Write the two manifests

The marketplace manifest names the marketplace and points at your plugin. The plugin manifest names the plugin and carries its version. Keep the version in both files in sync, because that number is what tells installed clients to update.

Your marketplace.json declares a name, an owner, a description, and a plugins array. Each entry in that array has a name, a source path to the plugin folder, a description, and a version.

Your plugin.json declares the plugin name, description, version, and author.

The single rule that matters most here: both manifests must stay valid JSON. A broken manifest breaks installation for the whole team, so re-read them after every edit and confirm they parse.

Step 3: Write your first skill

A skill is a SKILL.md file with a short frontmatter block followed by a body of instructions. The frontmatter needs two things: a name and a description.

The description is the most important thing you will write in the entire repo. Claude decides whether to auto-invoke a skill almost entirely from its description, so write it for a reader who has never seen the skill. Name the situations that should trigger it and the phrasings a user might actually type, then state what it does and what it returns. A vague description like "reviews code" will never fire reliably. A specific one that names the triggers, the user phrasings, and the output will.

The body is plain instructions: numbered steps, the exact output format you expect, and pointers to any helper scripts you ship alongside the skill.

Step 4: Install it locally and test

Never ship a skill you have not run. From a Claude Code session you can install your working copy as a local marketplace and exercise it before anything is public:

1. Add your local checkout as a marketplace with /plugin marketplace add /path/to/your-repo.
2. Install the plugin at user scope with /plugin install your-skills@your-marketplace --scope user.
3. After each edit, reload without restarting using /reload-plugins.
4. Invoke the skill on a real example and confirm it does what its description claims.

Step 5: Distribute to the team

Push the repo to GitHub. Now any teammate installs everything with two commands:

1. /plugin marketplace add your-org/your-repo
2. /plugin install your-skills@your-marketplace --scope user

To turn the skills on automatically for everyone working in a particular project, commit a .claude/settings.json to that project that registers the marketplace and enables the plugin. New contributors then get the skills the moment they open the project.

Step 6: Treat skills like production code

The marketplace only compounds if you hold the bar. The workflow we follow:

• One skill per pull request, so changes stay small and reviewable.
• Bump the version in both manifests on every change that should reach users. No bump means no update.
• Test before you open the PR, and review the change like any other production code.
• Branch and open a pull request rather than pushing straight to the main branch.

Because a version bump is the update signal, the moment a PR merges, every installed teammate is one session away from the new version.

Step 7: Or let Claude Code stand it up for you

If you would rather not assemble the pieces by hand, you do not have to. Open Claude Code in an empty folder and paste the prompt below. It scaffolds the whole marketplace for you: the repository structure, both manifests, and a first working skill, ready to push to GitHub. It is the same process described above, handed to Claude Code to run from start to finish.

Set up a new Claude Code skills marketplace in this folder, ready to push to GitHub. Work through every step below and do not stop until they are all done.

1. Ask me for two things, and only if you cannot infer them: my GitHub org or username, and a short name for the plugin. Default the plugin name to team-skills if I have no preference.

2. Create this structure. Only a manifest may live inside a .claude-plugin folder, nothing else.
   - .claude-plugin/marketplace.json at the repository root
   - plugins/PLUGIN-NAME/.claude-plugin/plugin.json
   - plugins/PLUGIN-NAME/skills/

3. Write marketplace.json as valid JSON with a marketplace name, an owner holding my name and email, a description, and a plugins array with one entry that has the plugin name, a source of ./plugins/PLUGIN-NAME, a description, and version 0.1.0.

4. Write plugin.json as valid JSON with the plugin name, a description, version 0.1.0, and an author. Keep this version identical to the one in marketplace.json.

5. Scaffold one starter skill at plugins/PLUGIN-NAME/skills/review-staged-diff/SKILL.md. Give it YAML frontmatter with a name and a description. Write the description for a reader who has never seen the skill: name the situations and the phrasings that should trigger it, then say what it does and what it returns. Give the body numbered steps and an exact output format. Make it genuinely useful: have it review the staged git diff for bugs, missing tests, and risky changes, then return a short findings list with a clear pass or fail.

6. Add a README.md that says what the repo is and lists the two commands a teammate runs to install it: first /plugin marketplace add MY-ORG/REPO, then /plugin install PLUGIN-NAME@MARKETPLACE-NAME --scope user.

7. Initialize a git repository and make one commit. Then print the exact commands I need to create the GitHub repo and push it, plus the two install commands my teammates will run.

8. Before you finish, confirm that both manifests are valid JSON and that the two versions match. Do not use any em dashes anywhere in the files you create.

Answer the one or two questions it asks, and you have a working marketplace your team can install in minutes.

Why this compounds: skills that learn

The real payoff shows up over time. Here is a pattern we use.

One of our most-used skills is a production code review. We also run an external review tool on every pull request, after our own skill has already looked at it. Whenever the external tool catches a class of issue our skill missed, we treat that as a gap in the skill, not a one-off fix. We harvest those misses, find the recurring patterns, and teach the skill to catch them itself. Then we bump the version and merge.

Because the skill lives in the marketplace, that lesson does not stay with one engineer. The entire team gets the smarter reviewer on their next session. The skill stops being a static script and becomes shared infrastructure that gets a little better every week.

The payoff

A skills marketplace turns Claude Code from a personal productivity tool into team infrastructure. Your best workflows become installable, versioned, and shared. Improvements propagate to everyone automatically. And the knowledge your team encodes into skills compounds instead of scattering across laptops.

If you build one, start small: one plugin, one strong skill with a sharp description, and the discipline to version every change. The rest grows from there.