How to Publish Skills to GitHub and skills.sh — The Complete Guide

Built a skill worth sharing? Publishing it makes it available to thousands of developers — and builds your reputation in the fastest-growing standard in AI tooling. Here is the complete publishing workflow.

Some of the most useful skills you build will be specific to your work. Others will be broadly useful — and publishing them benefits the community while building your reputation. Publication is straightforward once you understand the conventions.

The Standard Repository Structure

Every published skill lives in a GitHub repository. The standard structure for a published skills repo:

my-skills-repo/
├── README.md          # repository overview
├── LICENSE            # Apache-2.0 or MIT recommended
├── skill-one/
│   └── SKILL.md
├── skill-two/
│   ├── SKILL.md
│   └── scripts/
└── skill-three/
    └── SKILL.md

Each skill is a top-level directory. The repository can contain a single skill or many — the Vercel skills CLI handles both patterns automatically. The README explains what skills the repo contains, what each does, and how to install them. The LICENSE specifies the terms (Apache 2.0 for skills with scripts is recommended for the patent grant; MIT is fine for markdown-only).

Before You Publish: Validate

The official anthropics/skills repository includes validate-anthropic-compliance.py — a script that checks every aspect of your SKILL.md against the specification. Run it before publishing anywhere:

python3 validate-anthropic-compliance.py path/to/skill

The validator catches the common problems: missing required fields, folder/name mismatches, descriptions that are too long, Markdown bodies that exceed the 5,000-token recommendation, YAML frontmatter that does not start at line 1. Fix any issues before publication — these get rejected at install time anyway.

Submitting to skills.sh

To get your skill listed on skills.sh, submit a pull request to the skills.sh registry. The submission requirements are minimal but important: your skill must be on public GitHub, must follow the SKILL.md specification, must include a README, and must have at least one successful test install.

Once accepted, your skill becomes discoverable through npx skills find immediately. The leaderboard begins tracking install counts from that point. Over weeks and months, well-built skills accumulate installs and trust signals that compound — a skill with thousands of installs is a meaningful asset both for the community and for your professional reputation.

Maintaining a Published Skill

Skills are software. They benefit from versioning, change logs and active maintenance. Use semantic versioning in the version field: 1.0.0 → 1.1.0 for new features, 1.0.0 → 2.0.0 for breaking changes that require users to adapt. Maintain a CHANGELOG.md describing what changed in each release.

Respond to issues and pull requests on your skill repository. Skills with active maintenance accumulate trust faster than abandoned ones. Skills with documented update history are easier for users to adopt confidently.