Agent Skills — distribution and sharing¶

A Skill that lives only on the author's laptop has done a fraction of its job. This page covers the distribution end of the lifecycle: how to package a Skill so others can install it, what the per-vendor install flow looks like in practice, how the plugin and marketplace wrappers work, and how organisations roll Skills out at scale.

The high-level story is simple. Skills are plain-text directories under source control, so the technical act of "sharing" is just sending the directory. The complication is discovery (how does someone find your Skill?), trust (how does an installer know it's safe?), and lifecycle (versioning, updates, deprecations). Each vendor has its own answer for those three. The portable core — pure SKILL.md plus assets — stays identical; the wrappers around it diverge.

1. The portable starting point¶

A Skill is a directory. Distribution starts by zipping that directory or committing it to source control. Nothing more is needed for the basic case.

release-notes/
├── SKILL.md
├── scripts/build-notes.py
├── references/template.md
└── assets/header-logo.svg

That folder is a complete, portable Skill. Any of the three hosts will load it if it lands in one of the locations they scan (see §5). Everything below — plugins, marketplaces, org rollouts — is added on top of this base, not a replacement for it.

2. Anthropic — Skills, plugins, marketplaces¶

Anthropic distinguishes between Skills (individual capability directories) and plugins (bundles that wrap one or more Skills plus other components into a single distributable unit). For sharing one Skill informally, you send the directory. For sharing a coherent set — plus sub-agents, hooks, MCP servers, slash commands — you build a plugin.

2.1 Single Skill install¶

Three install flows are documented:

Drop into a personal scope. Copy the directory into ~/.claude/skills/<name>/. Loads on the next Claude session.
Commit into a project scope. Add the directory under .claude/skills/<name>/, commit to the project's repo, share via the normal git flow. Loads for anyone who pulls the repo.
Upload via Claude apps. The Claude apps (Settings → Capabilities → Skills) accept a .zip of the Skill directory and install it into the user's personal scope. This was the original install model and is still the easiest path for non-developer users; org-level deployment via the Claude apps shipped on December 18, 2025.

Precedence at load time is project > user > plugin, so a Skill checked into a repo always wins over the same Skill in the user's home directory.

2.2 Plugin manifest¶

A plugin is a directory containing a manifest at .claude-plugin/plugin.json plus the components it ships. The manifest enumerates which Skill/agent/hook directories are part of the bundle.

{
  "name": "secure-review",
  "version": "1.2.0",
  "description": "Adds a code-review sub-agent, a PR-summary skill, and a destructive-bash blocker hook.",
  "components": {
    "skills":     ["./skills"],
    "agents":     ["./agents"],
    "hooks":      ["./hooks/hooks.json"],
    "mcpServers": ["./mcp-servers/github.json"]
  }
}

The plugin's skills/ subdirectory contains one or more Skill directories with the usual SKILL.md shape. The plugin's name is its unit of install; its version is its unit of update; its components block tells the runtime which subdirectories to scan.

2.3 Plugin marketplaces¶

Plugins are distributed through decentralized git marketplaces rather than a central registry. A marketplace is just a git repository whose top-level structure follows a convention the Claude CLI recognises. The install model is:

/plugins marketplace add <git-url>
/plugins install <plugin-name>

Anthropic hosts an official marketplace at claude.com/plugins and a reference repository at github.com/anthropics/claude-plugins-official. Third parties run their own — internal corporate marketplaces, team marketplaces, public ones — by hosting a git repository that matches the convention. There is no central registry; trust is established by the marketplace URL, much like apt sources or brew taps.

2.4 Update model¶

Plugins get updates by the marketplace's git repository being updated and the user running /plugins update. Versioning is semantic by convention but not enforced. Marketplaces are responsible for signing or otherwise vouching for their contents — there is no in-runtime signature verification today.

3. GitHub Copilot — repo commits and the Extensions detour¶

Copilot does not have a plugin/marketplace concept for Agent Skills today. The distribution model is "commit the Skill directory into a repository and have your team check out that repository." Personal Skills go under ~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/; project Skills go under .github/skills/, .claude/skills/, or .agents/skills/.

3.1 Repo-level distribution¶

For a team's Skills repo:

team-skills/
├── .github/
│   └── skills/
│       ├── release-notes/
│       │   └── SKILL.md
│       ├── bug-triage/
│       │   └── SKILL.md
│       └── …
└── README.md

Team members clone the repo or set up VS Code to point at it. The path under .github/skills/ is conventional but not load-bearing — Copilot in VS Code also reads from .claude/skills/ and .agents/skills/, which makes the same repo usable by Claude installs and by vendor-neutral installs without modification.

3.2 Copilot Extensions ≠ Skills¶

The largest naming trap in the Copilot ecosystem is Copilot Extensions / Skillsets, which are not the cross-vendor SKILL.md analogue. Extensions are GitHub Apps (announced May 2024) that expose up to 5 HTTP API endpoints to Copilot Chat under the "Skillsets" architecture (announced Nov 19, 2024). The author is the GitHub App owner; the distribution is via the GitHub Marketplace with the Copilot Extensions filter; the user does not author a SKILL.md and there is no on-disk Skill folder.

Feature	Copilot Skillset (Extensions architecture)	Copilot Agent Skill
Author	GitHub App owner	End user / project author
Distribution	GitHub Marketplace (Copilot Apps filter)	File checked into repo or personal directory
Format	Up to 5 HTTP endpoints + natural-language descriptions	`SKILL.md` directory
Discovery	`@<extension>` mention in chat	Model-invocable from description
Trust	App is reviewed by GitHub Marketplace	Trust = trust in the source repo
Cross-vendor	No, Copilot-only	Yes, runs on Claude / Codex / Cursor / Gemini

If a wiki article or vendor blog says "Copilot skill," check whether it means a Skillset (an Extensions architecture) or an Agent Skill (a SKILL.md file). The two are entirely separate products sharing one root word.

3.3 Org-level distribution¶

GitHub does not yet ship a built-in "deploy this Skill across the org" workflow. The common in-the-field patterns:

An internal skills monorepo that every project in the org references as a submodule or as a CI-deployed ~/.copilot/skills/ mirror.
A dotfiles approach where each developer's ~/.copilot/skills/ is populated by an org-wide dotfiles repo.
A DevContainer / Codespace that pre-populates the Skills directories on startup.

Surface support to keep in mind: Visual Studio (the IDE) as of the April 2026 update does not yet ship Agent Skills support (only VS Code, JetBrains in preview, GitHub.com, and the Copilot CLI do). If your team uses Visual Studio, Skills will not load — and that constrains org rollout planning until the gap closes.

4. OpenAI Codex — file paths and emerging catalogues¶

Codex's distribution model is the closest to "just put the file in the right place." Discovery is filesystem-walk-based and goes from the nearest scope outward:

Location	Scope
`$CWD/.agents/skills/<name>/`, walking up to the repo root (closer wins)	Project
`$HOME/.agents/skills/<name>/`	Personal
`/etc/codex/skills/<name>/`	System / machine-wide
System-bundled Skills	Shipped with Codex itself

Codex has no plugin wrapper today and no first-party marketplace. The team or org that wants to distribute Skills puts them in a git repository and either commits them into project repos or copies them into ~/.agents/skills/ via a dotfiles flow. Catalogues — community-curated lists of useful Codex Skills — are emerging on GitHub but are not first-party.

The Codex sidecar (agents/openai.yaml) ships with the Skill directory. Codex picks it up automatically; Claude and Copilot ignore it. There is nothing distribution-specific to do beyond making sure the sidecar lives alongside its SKILL.md.

4.1 Migration from deprecated Custom Prompts¶

Codex previously distributed user-authored extensions as ~/.codex/prompts/*.md Custom Prompts (invoked as /prompt-name). The Custom Prompts docs page is officially marked deprecated in favor of Skills as of the 2026 release. Existing Custom Prompts continue to work — no end-of-life date is documented — but new authoring should target Skills. Migration is mechanical: take the Markdown body, add YAML frontmatter with name (matching directory) and description, move it under ~/.agents/skills/<name>/SKILL.md.

5. Where Skills live — quick reference¶

Vendor	Project locations	Personal locations
Anthropic	`.claude/skills/<n>/`, inside a plugin (`.claude-plugin/`)	`~/.claude/skills/<n>/`
GitHub Copilot	`.github/skills/<n>/`, `.claude/skills/<n>/`, `.agents/skills/<n>/`	`~/.copilot/skills/<n>/`, `~/.claude/skills/<n>/`, `~/.agents/skills/<n>/`
OpenAI Codex	`.agents/skills/<n>/` (walks up to repo root)	`~/.agents/skills/<n>/`, `/etc/codex/skills/<n>/`

Two implications worth internalising:

.agents/skills/ is the path that's read by both Copilot and Codex natively. For a Skill intended to be cross-vendor, that is the right default project path.
.claude/skills/ is read natively by Claude and by Copilot. It is the right project path when interop matters and Codex isn't a target.

6. Versioning and updates¶

The spec offers metadata.version per Skill; in practice authors use it inconsistently. Three patterns work in the field:

Semantic version per Skill in metadata.version. Update by replacing the directory. Works for any vendor.
Bundle version on the plugin (plugin.json's version). Skills inside the plugin all move forward together. Works for Anthropic plugins specifically.
Git tag per Skills repo. Plays naturally with the Copilot / Codex commit-and-clone model.

The runtime does not enforce that an installed Skill matches the latest version on the marketplace; users have to pull to get updates. This is identical to how apt or brew behave by design.

7. Trust, signing, and supply-chain audit¶

Skills load into the agent's context and can declare scripts that run with the agent's permissions. The trust model matters.

As of May 2026, none of the three vendors ship a Skills-specific signing or sandboxing layer. The de facto trust model is:

Trust the marketplace / repo URL. Treat a Claude plugin marketplace URL the way you treat an apt source.
Trust the author. A Skill from your own team is implicitly trusted; a Skill from an unknown third party is not.
Audit before install. Read SKILL.md and the contents of scripts/. Skills are plain text — there is nothing to hide.

Vendor-side security knobs that affect distribution:

Anthropic's experimental allowed-tools lets a Skill declare the minimum tool surface it needs. This is a declaration, not an enforcement; the host runtime decides whether to honour it.
Copilot's disable-model-invocation: true forces a Skill to be user-invoked rather than model-invoked. Useful for destructive operations.
Codex's policy.allow_implicit_invocation: false is the equivalent of Copilot's disable-model-invocation.

For org rollout it is worth picking one of these per Skill and documenting it in the Skill's body, even when only one host enforces it — the documentation is what survives across hosts.

8. Organisation-level deployment¶

A team or company rolling out Skills at scale typically combines:

A central Skills repo under source control, owned by a small platform team.
A naming convention (<team>-<task> or <system>-<verb>) so Skill names don't collide across teams.
A test fixture per Skill, in the same repo, using the testing approach from the testing sub-page.
A CI job that runs the fixture on every PR.
A distribution job that publishes the latest Skills into wherever users pick them up — a plugin marketplace mirror for Anthropic, a project-level submodule for Copilot, a dotfiles repo for Codex.
A retirement process for Skills that have been superseded; on a tombstone, leave a one-line redirect pointing at the new Skill.

This is the same pattern that internal shell-scripts and snippets repositories have used for decades. Skills inherit those operating principles cleanly.

9. The open-spec / open-foundation backdrop¶

The reason distribution works across vendors is that the format is governed by an open spec (agentskills.io, donated December 18, 2025) and that two of the adjacent specs — MCP and AGENTS.md — are now Linux Foundation projects under the Agentic AI Foundation, donated December 9, 2025, with 146 members and 8 platinum sponsors (AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, OpenAI) by the Linux Foundation's Feb 24, 2026 press release. The Agent Skills spec sits next to those and is moving the same way.

Practical implication: a Skill you ship today has a credible expectation of running on the same three vendors a year from now and on additional ones as they adopt the spec. That stability is what makes investment in a Skills monorepo and a CI fixture suite pay off.

10. Distribution checklist¶

Before publishing a Skill outside your own laptop:

[ ] SKILL.md frontmatter has only the required fields plus the spec optional ones in its main block; vendor-specific fields are in a clearly labelled section.
[ ] name matches the directory name exactly, kebab-case, no reserved substrings.
[ ] description passes the positive and negative trigger fixtures.
[ ] Body cites scripts and references by filename; nothing inline that should be a level-3 fetch.
[ ] metadata.version is set; bumped on every change.
[ ] License (license: field, ideally an SPDX identifier) is set if the Skill is leaving the org.
[ ] Scripts under scripts/ have a shebang and are executable, or are explicitly run with python/node/bash from the body.
[ ] No secrets in any file under the Skill directory.
[ ] README (next to SKILL.md, not part of the spec) for human installers.
[ ] Test fixture lives next to the Skill or in a sibling location, and passes.

Pass the checklist, then publish via whichever channel matches the audience: plugin marketplace for Anthropic users; project commit for Copilot users; dotfiles / ~/.agents/skills for Codex users; a cross-vendor .agents/skills/ project commit for everyone at once.

Changelog¶

2026-05-11 — Page created from the Anthropic authoring guide PDF (chapter 4) generalized across Claude / Copilot / Codex. Confidence 87.