Chapter 12 of 14 · Create · 4 min read
Sharing and publishing your skills
A skill that helps you will probably help someone else: a teammate, another team, or strangers who do the same kind of work. Because skills are plain folders, sharing them is easy. Sharing them well takes a little more: a predictable repository layout, a licence that says what people may do, a README that helps them decide whether to trust and install it, and, if you like, packaging for plugin marketplaces. This chapter covers each.
Choose how widely to share
| Audience | Simplest approach | Notes |
|---|---|---|
| Your team, one project | Commit to .claude/skills/ in the repository | Everyone who clones gets it; changes go through code review |
| Your organisation | A shared internal skills repository, or a private plugin marketplace | Lets several projects use one maintained copy |
| Everyone | A public GitHub repository with a licence and README | Others can read, install, fork and improve it |
A repository layout people understand
There is no single required layout, but a common pattern has emerged: one folder per skill, each with its own SKILL.md, under a top-level skills/ directory. It’s easy to browse, easy for installers to find and easy to copy a single skill from.
A public skills repository
my-skills/
├── README.md # what's here, how to install, how to contribute
├── LICENSE # e.g. MIT or Apache-2.0
├── CHANGELOG.md # optional: notable changes
└── skills/
├── pr-description/
│ ├── SKILL.md
│ └── tests/cases.md
└── weekly-metrics/
├── SKILL.md
├── template.md
├── reference/
└── scripts/- Keep folder names identical to each skill’s
name. - Make every skill self-contained. Avoid references to files outside its own folder, because people often install skills one at a time.
- Include test cases if you have them. They show users what the skill is meant to do and help contributors avoid regressions.
- Don’t commit secrets, personal data, internal URLs or customer examples. Check the history as well as the current files.
Before publishing a skill you wrote for work, check it for internal details: hostnames, project names, credentials, customer data and anything your employer would consider confidential. Scrub examples and check your Git history, not only the latest version.
Pick a licence
Without a licence, others have no clear permission to use, change or share your work, and many organisations won’t touch it. A permissive licence such as MIT or Apache-2.0 is a common choice for skills: short, widely understood and friendly to commercial use. Add a LICENSE file at the root of the repository. If you’ve adapted someone else’s skill, keep their licence and credit them as it requires. Our MIT licence explainer covers what that licence does and doesn’t require.
Write a README that earns trust
Most people decide whether to install a skill from the README. Answer their questions up front.
README.md outline
# my-skills
One sentence on who these skills are for.
## Skills
| Skill | What it does |
|---|---|
| pr-description | Writes clear pull-request descriptions from a branch |
| weekly-metrics | Turns an analytics CSV into a one-page weekly summary |
## Install
- Claude Code: copy a folder from skills/ into ~/.claude/skills/
(personal) or .claude/skills/ (project).
- Claude apps: zip a skill folder and upload it under Settings.
- Plugin: (if you publish one) how to add the marketplace and install.
## What the skills access
- pr-description: runs read-only git commands. No network.
- weekly-metrics: runs a local Python script on the CSV you provide.
No network. Needs Python 3.
## Contributing
How to propose changes and run the test cases.
## Licence
MIT. See LICENSE.A short “What the skills access” section, listing commands, network use and required credentials for each skill, does more for trust than anything else in the README. It saves every careful user from working it out themselves.
Plugins and marketplaces
For larger collections, or when you want one-step installation, package your skills as a plugin. In Claude Code, a plugin is a folder with a small manifest that can bundle skills alongside commands, subagents, hooks and MCP server configuration. A marketplace is a catalogue of plugins, often itself a Git repository, that users add once and then install plugins from. Other agents have their own packaging and registries, and community installers can place a skill in the right folder for several agents at once.
- Follow the current documentation for the manifest format; it’s small but specific.
- Keep each skill usable on its own too, so people who don’t use plugins can copy the folder.
- Version the plugin and note changes, because users may update automatically.
- List the plugin’s components and what they access in its description.
Maintaining a published skill
- Respond to issues, especially reports that a skill triggers wrongly or misbehaves.
- Rerun your test cases before each release.
- Avoid surprise changes in behaviour or access. If a new version needs network access or credentials, say so prominently.
- If you stop maintaining it, say so in the README so people can fork with confidence.
SuperpowersOpen sourceA well-organised public skills collection, also packaged as a plugin.★ 311k · MIT
Agent SkillsOpen sourceA clear example of a multi-skill repository layout.★ 113k · MIT
skillsOpen sourceA CLI that installs skills from repositories into many agents.★ 37.7k · MITKey takeaways
- Share in the narrowest place that works: project folder, internal repository or public GitHub.
- Use one self-contained folder per skill under
skills/, named after the skill. - Add a licence and a README that says exactly what each skill accesses.
- Plugins and marketplaces make installation one step; keep skills usable on their own too.
Put it into practice
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Written by the AI Tool Garage editors. Tool details link to their catalogue pages, which are refreshed weekly; spotted something out of date? Tell us.