Making it shareable

A skill that lives in your ~/.claude/skills/ can get away with a lot. It knows your username. It knows you've got brew installed. It knows your projects all live under ~/code/. Hardcoding any of that is fine — it's your machine.

A shared skill is a different animal. It has to work for someone you've never met, who has a different username, a different OS, a different toolchain, and zero context about how you set things up. The rule of thumb is simple: assume nothing about the other person's environment.

That doesn't mean a shared skill is harder to write — it just means a few habits have to change. Pull paths out into variables. Declare what you depend on. Add a README. The skill itself stays the same shape; the packaging around it grows up.

Six things, plain English:

• No user-specific paths. ~ or $HOME, never /Users/yourname/ or /home/yourname/.
• No machine-specific assumptions. Don't assume the user runs macOS. Don't assume brew is installed. Don't assume bash over zsh.
• Declared dependencies. If you need Node, say so. If you need ffmpeg, say so. List versions when they matter.
• Clear installation steps. A user should be able to follow them top to bottom without guessing.
• Documented expected behaviour. What does the skill do? What does it produce? What does it not do?
• A way to remove it. Uninstall is part of install. If your skill writes files outside its folder, document them.

The shape of a portable skill is: "this is what you need; this is what I do; this is what you get." If a user can answer those three questions from your README alone, you're done.

There isn't an official Claude skill registry yet — that's almost certainly coming, but it's not here today. So sharing is currently a question of where do I put this file so my person can grab it? Three pragmatic answers:

• GitHub repo — the default for anything non-trivial. Users clone or symlink it into ~/.claude/skills/. Versioned, discoverable, hooks into the rest of GitHub (issues, releases, stars).
• Gist — for tiny single-file skills, faster than a repo. A SKILL.md that's 30 lines and references nothing else is a fine candidate.
• Copy-paste — fine for your team's internal Slack or wiki. You just paste the SKILL.md content and tell people where to drop it.

And, looking ahead: expect a Claude skill registry. Not here yet, but when it lands, it'll probably look like npm-for-skills — searchable, installable, with metadata. Write your skills today as if that registry already exists, and you'll be ready.

Semver works the same here as everywhere else: major.minor.patch. Bump the major when you break something users depend on — workflow renamed, args parsed differently, expected output shape changed. Bump the minor when you add a capability without breaking the old behaviour. Bump the patch for fixes.

If your tooling reads metadata.version in the frontmatter, put it there. Otherwise tag git releases — v1.0.0, v1.1.0, and so on — and let users install a specific tag if they want stability.

Keep a CHANGELOG.md. Even a five-line one is better than nothing. Users who hit a regression will read it; users upgrading will scan it; future-you will be glad it exists.

Every shared skill needs two markdown files, and they do different jobs.

• SKILL.md — Claude reads this after install. It's the recipe.
• README.md — humans read this before install. It's the pitch + the manual.

The README answers a small, specific set of questions:

• What does this skill do?
• Who is it for?
• How do I install it?
• What does it depend on?
• How do I uninstall it?
• Where do I report issues?

That's it. A good README isn't long — it just answers those six questions clearly enough that someone can decide in under a minute whether to install your skill, and then actually install it without asking you.

The README's "depends on" section deserves real thought. Five things are worth declaring explicitly:

• Claude Code version — if your skill uses a feature that landed in 1.3, say "requires Claude Code >= 1.3". Don't make users diagnose it.
• OS support — macOS, Linux, Windows, WSL. If you tested on macOS only, say so. Honest scope beats false universality.
• External tools required — node, python, ffmpeg, anything the skill shells out to. Versions where they matter.
• Network requirements — does the skill call out to the internet? Hit a private API? Need to be online at all? Users in restricted environments need to know.
• Model assumptions — does it expect Opus-level reasoning? Or is it fine on Sonnet / Haiku? A skill that quietly fails on a smaller model is worse than one that says "requires Opus" up front.

Personal skills live as a single folder under ~/.claude/skills/. Shared skills live as a repository — same skill folder inside, but with packaging around it. Two tabs below: the repo layout, then a README template you can copy.

A few notes on the layout:

• The install.sh is optional but worth it once your skill has more than one file. It symlinks the folder into ~/.claude/skills/, so users can git pull to get updates.
• tests/prompts.md is your trigger-phrase test list — the same one ch.8 covers. Ship it: users can run it after install to verify the skill activates the way they expect.
• The LICENSE file matters more than people think. Without one, your skill is technically all-rights-reserved by default — a friction users may notice.