Yes, GitHub is the standard distribution channel for Claude Code skills. Create a public repository, place your skill folder at the root or in a clearly named subdirectory, add a README, and tag the repository with claude-code-skills. Anyone can then install your skill by cloning the repo and copying the skill folder into their .claude/skills/ directory. AEM publishes its production Claude Code skills on GitHub using this exact structure.

TL;DR: Publishing on GitHub is 5 steps: create a repo, add the skill folder, write a README, add the claude-code-skills topic tag, and optionally submit to the awesome-claude-skills curated list. The README is the highest-leverage element. A skill with a clear 3-step install section gets installed. A skill with "see the SKILL.md for details" gets skipped.

How Do I Set Up a GitHub Repository for a Claude Code Skill?

Create a new public GitHub repository, using the claude-skill-{skill-name} naming convention or just the skill name itself, e.g., reviewing-typescript-prs. Both work. GitHub hosts public repositories free on any personal plan. The naming convention is not enforced, but matching it makes your repo easier to surface when developers search the claude-code-skills topic across GitHub's 180 million active developers (GitHub Octoverse, 2025).

The file structure has two valid configurations:

Single-skill repository (most common):

your-repo/
├── README.md
├── LICENSE
└── reviewing-typescript-prs/
    ├── SKILL.md
    └── references/
        └── style-guide.md

Multi-skill repository (skill library):

your-repo/
├── README.md
├── LICENSE
└── skills/
    ├── reviewing-typescript-prs/
    │   └── SKILL.md
    └── drafting-release-notes/
        └── SKILL.md

The skill folder name becomes the skill's identifier when installed. Keep it lowercase, hyphenated, and specific. typescript-pr-review is better than code-tools.

What Files Should the Repository Include?

A minimum viable skill repository contains 3 files beyond the skill folder itself: a README at the root that drives install decisions, a LICENSE so developers can legally use the code, and a CHANGELOG kept outside the skill folder so Claude never loads version history into context when running the skill. Research across 5,000 GitHub repositories found that README structure and update frequency are statistically significantly different between popular and unpopular projects (Wang et al., Journal of Systems and Software, 2023).

  • README.md: The file GitHub shows first. It determines whether someone installs your skill or moves on. Cover what the skill does, when to use it, and exactly how to install it: three numbered commands, no ambiguity.
  • LICENSE: The MIT license is standard for community skills, and accounts for about one-third of all licensed repositories on GitHub (GitHub Innovation Graph, 2025). The Open Source Initiative's MIT license page drew 1.7 million unique visitors in 2024, four times the traffic of the next most-viewed OSI-approved license (Open Source Initiative, 2024). Without a license file, copyright law defaults to "all rights reserved," meaning legally no one can use your skill, even though you published it publicly. Notably, 46% of the top 1 million public GitHub repositories carry no license at all (OpenWeaver, 2023).
  • CHANGELOG.md: Place this at the repository root, not inside the skill folder. The CHANGELOG records what changed between versions. Keeping it outside the skill folder means Claude never loads version history into context when running the skill. It's for humans, not for the model.

Your skill folder should contain only what Claude needs to execute the skill: the SKILL.md, any reference files, and if applicable, an evals.json and assets folder.

"The failure mode isn't that the model is bad at the task. It's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)

This applies directly to your README. Ambiguous installation instructions produce support questions. Specific ones produce silent successful installs.

How Do I Make My Skill Discoverable on GitHub?

Two actions drive the majority of skill discovery on GitHub: adding the claude-code-skills topic tag so your repo appears in topic search, and submitting to the awesome-claude-skills curated list. Developers treat curated list inclusion as a quality signal, so it drives more installs than topic tags alone.

  • Add the claude-code-skills topic tag. On your repository page, click the gear icon next to "About" and add claude-code-skills as a topic. GitHub's topic search indexes these immediately. Developers looking for skills search by topic first.
  • Submit to the awesome-claude-skills list. This is a community-curated GitHub repository listing high-quality Claude Code skills. Submitting a pull request adds your skill to the list. The review checklist includes: working description field, output contract, and at minimum 1 test case in evals.json.

Beyond those two: when developers search GitHub for claude-code-skills, use the skill's actual function in the repo description, not a tagline. "TypeScript PR review skill with severity rating output" surfaces in search. "My awesome skill" doesn't. GitHub saw nearly 137,000 new public generative AI projects in 2024 alone, a 98% increase in new AI project creation year-over-year (GitHub Octoverse, 2024). Developers searching for tools in that environment scan descriptions fast. A specific description is not optional.

What Should I Put in the README?

Four sections cover everything a developer needs to evaluate and install your skill: what it produces, when to trigger it, how to install it with exact numbered commands, and what to configure before the first run. A developer scanning your README decides to install or skip in under 30 seconds. Each of the four sections removes one reason to skip. Repositories with well-organized README lists are statistically associated with higher popularity across 1,950 GitHub projects studied (Venigalla and Chimalakonda, 2022).

  1. What this skill does: State the output in 2-3 sentences. "This skill produces a structured code review in 3 sections: critical issues, warnings, and style feedback. It runs on TypeScript files passed as context." Not "This skill helps you review code better."
  2. When to use it: State the trigger in 1-2 sentences. "Invoke when you want a structured review of a TypeScript file before submitting a pull request."
  3. Installation: Show exact commands. Do not summarize. Show the path. Three numbered commands minimum.
  4. Configuration: List any reference files the user needs to customize. If the skill works out of the box, say so explicitly: "No configuration needed. Install and run."

We've shipped public skills on GitHub and the metric that predicts install count is README clarity, not skill quality. A skill with a clear installation section gets installed. A skill with a vague "see the SKILL.md" note gets skipped before the reader reaches the quality of the skill itself.

For more on what makes a skill ready for public distribution, see How do I package a skill for distribution to others?.

How Do I Handle Updates After Publishing?

Use semantic versioning in your CHANGELOG and README, tagging each GitHub release with v1.0.0, v1.1.0, and so on. Developers who installed via git submodule pin to a specific tag for stability. Developers tracking main get the latest automatically. Semantic versioning is the standard across the open source ecosystem and gives both groups a clear upgrade signal when behavior changes.

When you update SKILL.md in a way that changes behavior, treat it as a breaking change and increment the major version. A description field change that alters what auto-triggers the skill is a breaking change. A reference file update that adds new examples is not.

GitHub does not notify developers who installed via direct copy when you release a new version. That is a hard limit of the platform: there is no subscriber list, no push notification, and no dependency graph entry for direct-copy installs. Only submodule users receive automatic references to your updates. Add a "Last updated: YYYY-MM-DD" line in the README as the only mitigation available to direct-copy installers.

For a broader view of where developers find and install skills, see Where can I find community-built Claude Code skills to install?.

FAQ

Do I need a paid GitHub account to publish a skill?

No. Public repositories are free on GitHub's personal plan. A free account hosts any number of public skill repositories with no restrictions on downloads or clones.

Can I publish a skill under a license that lets companies use it commercially?

Yes. The MIT license allows commercial use without restriction. If you want to restrict commercial use, Creative Commons NC (Non-Commercial) is an option, though it's less standard for code. For most community skills, MIT is the right choice.

Should I put the skill folder at the root of the repository or in a subdirectory?

At the root for single-skill repos. Inside a skills/ subdirectory for multi-skill repos. Both patterns work for installation. The root pattern is simpler for single-skill projects.

How do I contribute a skill to the awesome-claude-skills repository?

Fork the awesome-claude-skills repository, add a link to your skill in the relevant category section, and submit a pull request. The checklist requires: a working SKILL.md with a single-line description field, an output contract, and at minimum one test case in evals.json.

Can I take my skill down after publishing it?

Yes. Delete or archive the repository. Anyone who already installed the skill keeps their copy. Anyone who installed via git submodule loses the remote reference. Taking down a widely-used skill without a deprecation notice is considered poor community practice.

What if someone forks my skill and makes changes?

That's the expected behavior under MIT license. The fork is a separate repository. Your original stays unchanged. If they improve the skill, they can submit a pull request. You decide whether to merge it.

Last updated: 2026-04-25