Create and share a Claude Code skill

Package a thing you keep explaining to your agent — a checklist, a house style, a multi-step routine — as a skill anyone can drop into their own Claude Code and use. A skill is just a folder with one file (SKILL.md) telling the agent what it does and when to use it; your agent can scaffold the whole thing for you.

Time: ~5 min to build with your agent, ~2 min to share. The un-delegable bits are tiny: type one / command to test it, and (if you share by repo) accept a GitHub invite on the recipient's side. [estimate] Last verified: 2026-06-07 · file layout, frontmatter fields, and install commands checked against Anthropic's own skills and plugins docs. [confirmed]

New to all this? Do Set up Claude Code first — the agent builds and installs skills for you. Unsure how to phrase the ask? How to ask your agent is one screen.

Before you begin

Claude Code running — ~10 min once. It scaffolds the folder, writes the SKILL.md, and tests that the skill loads.
The thing you want to package. Not code — instructions: the steps you keep typing ("turn my meeting notes into our summary format"), a style guide, a checklist, a routine. If a chunk of your CLAUDE.md has turned into a procedure rather than a fact, that's a skill. [confirmed]
To share by repo: a GitHub account (~10 min once) and the GitHub CLI connected (~3 min once). To share as a one-command install (a plugin marketplace), the same — a marketplace is just a repo with one extra index file.

New to letting an agent run setup for you? Read How to ask your agent — one screen, then come back.

The one thing to say

With Claude Code running, describe the routine and ask for a skill:

Make a Claude Code skill that <does X>. Scaffold the folder under
~/.claude/skills/, write the SKILL.md with a clear description of when to
use it, and put the step-by-step instructions in the body. Then tell me
the exact /command to test it.

Your agent creates ~/.claude/skills/<name>/SKILL.md, fills in the two parts that matter — a description (so the agent knows when to reach for it) and the instructions (what to do when it runs) — and hands you back the slash command to try. [confirmed]

What your agent actually builds

A skill is a folder. The only required file is SKILL.md; everything else is optional helpers. [confirmed]

my-skill/
├── SKILL.md          ← required: the description + instructions
├── reference.md      ← optional: long docs, loaded only when needed
└── scripts/
    └── helper.py     ← optional: a script the agent can run

SKILL.md itself is short — a few lines of frontmatter between --- markers, then the instructions: [confirmed]

---
description: Turn raw meeting notes into our standard summary format. Use when
  the user pastes notes or asks for a meeting summary.
---

Rewrite the notes into these sections: Decisions, Action items (with owners),
Open questions. Keep it under 200 words. Flag anything that sounds like a
commitment without a named owner.

Two things carry the whole skill:

The folder name is the command. A folder named meeting-summary gives you /meeting-summary. [confirmed]
The description is the trigger. It's the only part the agent reads up front to decide whether to use the skill on its own. Vague description → it never fires. Name the concrete situation and the words a user would actually say. [confirmed]

The instructions stay loaded for the rest of the session once the skill fires, so keep the body tight — state what to do, skip the why. Move long reference material into a separate file the agent loads only when it needs it. [confirmed]

Steps

Build it. Say the sentence above. The agent scaffolds ~/.claude/skills/<name>/SKILL.md and writes both parts. [confirmed]
Test that it loads. New skills under ~/.claude/skills/ are picked up within the same session — no restart. [confirmed] Type the command directly:
```
/your-skill-name
```
Or check the whole set is registered by asking your agent: "What skills are available?" [confirmed]
Test that it triggers on its own. Say something that matches the description in plain language ("summarise these notes") and confirm the agent reaches for the skill without being told the command. If it doesn't, the description is too vague — see If it doesn't work. [confirmed]
Tighten, then share. Once it behaves, pick how the recipient gets it — by repo (they point their agent at a folder) or as a one-command install (a plugin marketplace).

By repo — simplest. Your skill folder goes into a GitHub repo; the recipient's agent copies the folder into their own ~/.claude/skills/. Tell your agent:

Put this skill folder in a GitHub repo and give me the link to share.

The recipient then tells their agent: "Install the skill in this repo into my Claude Code" with the link — the agent copies the folder into ~/.claude/skills/<name>/ and it's live. (Or they drop the folder there by hand.) [confirmed] This is the right call for one skill shared with a few people.

As a one-command install — a plugin marketplace. Wrap the skill as a plugin and list it in a marketplace (one repo with an index file). The recipient adds the marketplace and installs in two lines — no copying folders, and they get updates when you push changes. [confirmed] Worth it when you're sharing several skills, or with a wider group who should get a clean install + updates. Ask your agent:

Turn this skill into a Claude Code plugin and set up a marketplace repo for
it on GitHub. Write the .claude-plugin/plugin.json and the
.claude-plugin/marketplace.json, push it, and give me the install commands
to send people.

Your agent builds the layout the docs specify — a plugin.json manifest, the skill under skills/, and a top-level .claude-plugin/marketplace.json listing the plugin — and pushes it. [confirmed] The recipient runs the two commands you hand them (next section).

Plugin skills are namespaced. A skill review inside a plugin my-tools is invoked as /my-tools:review, not /review — that's deliberate, so two plugins can't collide. [confirmed]

What the recipient does

From a repo folder: point their agent at the link — "install the skill in this repo" — or drop the folder into ~/.claude/skills/ themselves. New to GitHub and it's a private repo? They accept your invite first (~2 min). [confirmed]
From a marketplace: two lines in their Claude Code — register your catalog, then install: [confirmed]
```
/plugin marketplace add your-github-user/your-repo
/plugin install your-plugin@your-marketplace-name
```
Then /reload-plugins (or restart) and the skill is live as /your-plugin:your-skill. [confirmed]
Either way they should glance at the SKILL.md first. A skill runs with their agent's tools on their machine — only install from someone you trust. Claude Code's own docs flag this. [confirmed]

If it doesn't work

Skill doesn't show up in / or "What skills are available?" → the folder layout is off. It must be ~/.claude/skills/<name>/SKILL.md — the file named exactly SKILL.md, one folder deep, not loose in ~/.claude/skills/. If you created the top-level ~/.claude/skills/ directory after Claude Code was already open, restart once so it starts watching the new directory. [confirmed]
Where do skills live on my OS? → same path everywhere: ~/.claude/skills/ for your personal skills (all your projects), or .claude/skills/ inside a project for that project only. On Windows ~ is your user folder, e.g. C:\Users\you\.claude\skills\. Plugin skills live under the installed plugin, not here — manage those with /plugin. [confirmed]
Skill never triggers on its own (you always have to type the command) → the description is too vague. It's the only thing the agent sees when deciding. Rewrite it to name the situation and the user's actual words — "Use when the user pastes meeting notes or asks for a summary" beats "summarises text". Lead with the key use case. [confirmed]
Skill fires when you don't want it to → make the description narrower, or add disable-model-invocation: true to the frontmatter so only you can trigger it with /name and the agent never reaches for it on its own. [confirmed]
Two skills with the same name → a folder name has to be unique within a level. Personal beats project when they clash; plugin skills are namespaced (/plugin:skill) so they never collide with yours. Rename the folder to fix it. [confirmed]
Description looks cut off / keywords missing → if you have many skills, Claude Code trims descriptions to fit a budget and can drop the keywords it needs to match you. Run /doctor to see if the budget's overflowing, and keep each description's key use case first (it's capped at ~1,536 characters). [confirmed]
Recipient installed the plugin but the skill isn't there → they need /reload-plugins (or a restart) after installing. If it's still missing, the plugin cache can go stale — rm -rf ~/.claude/plugins/cache, restart, reinstall. [confirmed]
Anything else → Anthropic's skills troubleshooting and plugin troubleshooting cover the rest.

Prefer to do it by hand?

No agent — just you, a text editor, and a terminal.

Make the folder and file:
```
mkdir -p ~/.claude/skills/my-skill
```
Create ~/.claude/skills/my-skill/SKILL.md with a description: line in --- frontmatter and your instructions below it (see the example above). [confirmed]
In Claude Code, type /my-skill to run it, or "What skills are available?" to confirm it's registered. [confirmed]
To share: put the my-skill folder in any GitHub repo and send the link; the recipient copies the folder into their own ~/.claude/skills/. For the one-command install, follow Anthropic's plugin marketplace walkthrough to add plugin.json + marketplace.json. [confirmed]

Watch / read

YouTube blocked transcript pulls on 2026-06-07, so these aren't line-by-line verified — the first is Anthropic's own channel, so it tracks the official model.

Claude Agent Skills Explained — Anthropic, 3:15. The shortest authoritative overview of what a skill is and how the description drives it. Why this one: official, and the fastest way to get the mental model before you build.
Claude Skills Tutorial (2026): Build, Run, and Share — Kevin Stratvert, 14:33. Walks the full build → test → share arc end to end. Why this one: the only well-known walkthrough that covers sharing, not just building — longer, but on-task by its chapters. [unclear] — transcript blocked 2026-06-07, verify against the current install flow.

Best written walkthrough: Anthropic's own Extend Claude with skills — the authoritative source every command and path here was checked against. Pair it with Create plugins for the one-command-install path. [confirmed]

Want others to run a tool you built, not extend their agent? → a GitHub repository hands over the whole project to run locally.
Connecting your agent to an external service (an API, a database)? → that's a job for an MCP server, not a skill — skills are instructions, MCP servers are connections.
Just want someone to use a finished thing in a browser? → a Claude Artifact or a deployed website.

Sources

Extend Claude with skills — Claude Docs (what a skill is, SKILL.md folder layout, description as the trigger, frontmatter fields incl. disable-model-invocation, where skills live per scope, live change detection, the 1,536-char description cap, /doctor, troubleshooting) — checked 2026-06-07
Create plugins — Claude Docs (wrapping a skill as a plugin, plugin.json manifest, skills/ directory, namespacing, --plugin-dir testing, /reload-plugins) — checked 2026-06-07
Discover and install plugins — Claude Docs (/plugin marketplace add owner/repo, /plugin install name@marketplace, install scopes, trust warning, cache-clear fix) — checked 2026-06-07
Create and distribute a plugin marketplace — Claude Docs (.claude-plugin/marketplace.json path + minimal name/owner/plugins structure, hosting on GitHub) — checked 2026-06-07