Skip to content

Publish a skill

Last reviewed October 24, 2026

A published skill is a repository other people can find, read in a minute, install in one line and trust enough to let run. Each section below is one of those, in the order people meet them.

One repository per skill, or per family

Keep one skill, or one tight family of skills, per repository, so versions and issues stay about one thing. Put the skill where installers look: a SKILL.md at the root, or one folder per skill under skills/. Add a license file that GitHub recognizes; a public repository without one is all rights reserved, which puts off anyone who checks.

A repository description and topics people search for

The repository description, GitHub's one-line About text, is what search results show: say what the skill does and for which agents. Then add topics, because topic searches only find repositories that carry the topic. Always add agent-skills, plus one per agent the skill is for, such as claude-code-skill, codex-skill or gemini-cli-skill:

shell
gh repo edit --add-topic agent-skills --add-topic claude-code-skill --add-topic codex-skill

git-release checks and sets these topics as part of a release.

A README people trust

Open the README.md with one paragraph on what the skill does and when it runs. Then the install line for each way people install it (below), a real example of asking for it, and everything it touches: files it writes, commands it runs, network calls, costs. End with how to remove it. Surprises in that list are what lose trust, not the list itself.

Say who made it, inside the skill

A skill gets copied out of its repository into someone's agent, often without the repository around it. Whoever finds the installed copy later should be able to tell where it came from from the files that traveled with it. Put a short block in the README.md that ships in the skill's folder, with who wrote it and a contact (an email or the issue tracker), the source repository URL written out in full, how to update it, and which version this is, in the same form as the metadata and the tag:

README.md
# writing-release-notes
Drafts release notes from the git history since the last tag.

Version 1.0.0 · MIT license
Source:  https://github.com/your-name/writing-release-notes
Author:  Your Name <you@example.com>
Update:  npx skills add your-name/writing-release-notes   (or: git -C <skill folder> pull)
Issues:  https://github.com/your-name/writing-release-notes/issues

Versions and a changelog

Use semantic versioning: a major version for changes to what the skill does or expects, minor for new abilities, patch for fixes. Put the version in the frontmatter's metadata (and in plugin.json if you ship a plugin), tag each release (git tag v1.0.0), and keep a CHANGELOG.md, which is where people look to find out what changed before they update. If the skill ships scripts, have each report the same number with --version (more on the safety step).

Optionally add a versions.json mapping each version to a one-line note. Tools can read it without parsing prose, and this site shows the history on your listing when it is there.

The ways people install a skill

With npx

Vercel's skills command installs from a GitHub repository into the agents the user picks, and finds skills at the root or under skills/ (vercel-labs/skills). Repositories people install this way appear on the skills.sh leaderboard by themselves; there is nothing to submit.

shell
npx skills add your-name/writing-release-notes            # asks which agents
npx skills add your-name/writing-release-notes -g -a codex  # for one agent, every project

As a Claude Code plugin

Wrap the skill in a plugin and list the plugin in a marketplace, which can be the same repository (plugin marketplaces):

layout
.claude-plugin/marketplace.json
release-notes/.claude-plugin/plugin.json
release-notes/skills/writing-release-notes/SKILL.md
release-notes/.claude-plugin/plugin.json
{
  "name": "release-notes",
  "description": "Drafts release notes from the git history since the last tag.",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}
.claude-plugin/marketplace.json
{
  "name": "your-tools",
  "description": "Release tooling for coding agents.",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "release-notes",
      "source": "./release-notes",
      "description": "Drafts release notes from the git history since the last tag."
    }
  ]
}

claude plugin validate . checks both files before you push. People then add the marketplace once and install from it:

Claude Code
/plugin marketplace add your-name/your-tools
/plugin install release-notes@your-tools

The plugin guide covers plugins for other agents.

With GitHub's CLI

gh skill install your-name/your-tools writing-release-notes installs a skill for Copilot; the command is in preview (gh skill).

By hand

Copying the folder into the agent's skills folder always works. Say which folder in the README.

Get it listed

Submit the repository here (submit a listing) so people find it by what it does, with a safety rating next to it. A pull request to a well-kept awesome list helps too; this site reads several of them.

Building something else? See the guides to a plugin or marketplace and an MCP server.