Publishing and Sharing Claude Skills

By Yanni Papoutsis | 6 min read | 2026-07-14

Once a skill is written and tested, you share it one of three ways: zip the folder as a .skill file for a direct, one-off install, bundle it inside a plugin and distribute the plugin through a marketplace repository for anyone to add, or hand the raw folder to someone who copies it into their own skills directory. Which one fits depends on whether you are sharing with one person, your own future sessions, or the public.

This is the final post in the skills-authoring series. It assumes the skill has already been built (see writing a skill from scratch) and passed its own eval set (see testing and eval). Publishing is the last step, not a substitute for the first six.

TL;DR: A single skill is shared by zipping its folder with a .skill extension; presenting that file in a Cowork session surfaces a direct install action, which is the fastest path for sharing one skill with one person. For a set of skills meant to travel together, package them inside a plugin with a plugin.json manifest and distribute through a marketplace, a Git repository containing a marketplace.json that lists one or more plugins, so anyone can add the marketplace once and install or update from it going forward. Version every release: bump the number in the manifest, keep the previous version available for rollback, and never silently overwrite something people already installed. Before publishing anything, do a final pass for real credentials, since a shared skill folder is plain text anyone who installs it can read in full, and confirm the install on a separate, clean account before calling it done. Below is the full workflow for both paths plus a versioning checklist and a short list of common publishing mistakes to avoid.

Choosing a sharing path

Situation Best path
One skill, sharing with one person or your future self Zip as .skill, share the file directly
Several skills meant to be installed together Bundle into a plugin with plugin.json
Public distribution to strangers Plugin plus a marketplace repository
Personal backup across your own sessions .skill file kept in your own files, reinstalled as needed

How do you publish a single skill?

Step 1: Do a final credential and secrets pass

Before zipping anything, re-read every file in the skill folder specifically looking for real API keys, tokens, passwords, or account-specific URLs. Replace anything real with a placeholder:

API_KEY=YOUR_API_KEY_HERE
GITHUB_TOKEN=sk-xxx
DATABASE_URL=postgres://user:YOUR_PASSWORD_HERE@host:5432/db

A .skill file is a zip archive. Anyone who installs it can open it and read every line.

Step 2: Zip the folder with a .skill extension

zip -r changelog-writer.skill changelog-writer -x "*.DS_Store"

Step 3: Share the file

In Cowork, presenting a file that ends in .skill surfaces a direct install action for the recipient, since a .skill file is recognised as a zip archive containing a SKILL.md. Outside of Cowork, send the file through whatever channel you would use for any other document, and tell the recipient to unzip it into their skills directory if their environment expects a raw folder rather than an archive.

Step 4: Confirm the install on the receiving end

Ask the recipient (or do it yourself in a separate account) to install the skill and run the same cold-session trigger test from the testing and eval guide. A skill that worked perfectly in your own session can behave differently once it is the only copy installed, especially if it silently depended on a companion skill you also have installed but forgot to include.

How do you publish a set of skills as a plugin?

Step 1: Bundle the skills under one manifest

session-tools/
  .claude-plugin/
    plugin.json
  skills/
    changelog-writer/
      SKILL.md
    schema-change-helper/
      SKILL.md
  commands/
    audit.md

{
  "name": "session-tools",
  "version": "1.0.0",
  "description": "Changelog writing and safe schema-change helpers for Claude.",
  "author": {
    "name": "Yanni Papoutsis",
    "url": "https://yanni.uk"
  },
  "keywords": ["changelog", "database", "productivity"]
}

The full manifest structure and folder layout are covered step by step in the plugin from scratch guide; this post focuses on the distribution step that comes after the plugin is built, using the same pattern as the site's own 21-agent product pipeline, which ships as one plugin rather than 21 separate installs.

Step 2: Create a marketplace repository

A marketplace is a Git repository with a .claude-plugin/marketplace.json file listing one or more plugins:

{
  "name": "yanni-uk",
  "owner": { "name": "Yanni Papoutsis" },
  "plugins": [
    {
      "name": "session-tools",
      "source": "./session-tools",
      "description": "Changelog writing and safe schema-change helpers."
    }
  ]
}

Step 3: Publish and let others add it

/plugin marketplace add yanni-uk/claude-plugins
/plugin install session-tools@yanni-uk

Once someone adds your marketplace, they can install or update any plugin listed in it without you sending files individually again.

Versioning: treat releases like software releases

Bump the version field in plugin.json on every meaningful change, and keep old versions retrievable rather than force-overwriting a tag someone has already installed. A practical minimum discipline:

1.0.0 -> first public release
1.1.0 -> added a new companion skill, no breaking changes
1.1.1 -> fixed a description that was failing to trigger
2.0.0 -> renamed a skill or changed its expected inputs (breaking)

Note what changed somewhere the next installer will actually see, a CHANGELOG file in the repository root works well and gives you practice writing the exact kind of changelog a changelog-writer skill would produce.

Common publishing mistakes

Mistake Consequence Fix
Real credential left in an example Leaked on install, since skill files are plain text Final pass for secrets before every zip or push
No version bump on update Installers cannot tell if they have your fix Bump version on every release, however small
Skill depends on a companion not included in the bundle Works for the author, breaks for everyone else Test the install on a separate, clean account
Marketplace repository made private Frictionless install breaks for new users Keep distribution repositories public unless access must be restricted
Force-pushing over a released version Breaks rollback for anyone who needs the prior version Tag releases, never overwrite a published version in place

Frequently asked questions

Do I need a Git repository to share a single skill?

No. A single skill can be shared as a .skill file directly, no repository required. A marketplace only becomes useful once you are distributing more than a handful of plugins to people who were not sent the file personally.

Can the same plugin be listed in more than one marketplace?

Yes, a plugin's source can be referenced from multiple marketplace.json files. Keep the plugin name unique to avoid an ambiguous /plugin install when someone has more than one marketplace added.

What happens to people who installed an old version when I publish an update?

Marketplace installs can typically pull the new version when the installer checks for updates; a .skill file sent directly does not update itself; you need to share the new file again. This is one more reason to prefer a marketplace once a skill has more than a couple of users.

About the author

Yanni Papoutsis builds AI products, automation pipelines, and technical documentation with Claude, and publishes free tooling and guides at yanni.uk.

Next step: Start from the beginning with how to write a Claude skill from scratch, or explore 1,000+ AI tools at yanni.uk/ai-tools.

Sources