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:

1. Drop into a personal scope. Copy the directory into ~/.claude/skills/<name>/. Loads on the next Claude session.
2. 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.
3. 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. Org-level deployment via 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.

3. GitHub Copilot — repo commits, gh skill, and the Extensions detour

Copilot does not have a plugin/marketplace concept for Agent Skills today. The primary 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 that expose up to 5 HTTP API endpoints to Copilot Chat under the "Skillsets" architecture. 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 + descriptions	SKILL.md directory
Discovery	@<extension> mention in chat	Model-invocable from description
Trust	App reviewed by GitHub Marketplace	Trust = trust in the source repo
Cross-vendor	No, Copilot-only	Yes, runs on Claude / Codex / Cursor / Gemini

3.3 Org-level distribution

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

• An internal skills monorepo that every project in the org references as a submodule or as a CI-deployed 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.

Visual Studio support: As of the April 2026 update, Visual Studio 2026 now discovers Agent Skills from .claude/skills/, .agents/skills/, and .github/skills/ paths, bringing it in line with VS Code (GitHub Changelog, Apr 30, 2026). The earlier gap between VS Code and VS for Agent Skills has closed.

3.4 GitHub CLI — gh skill

GitHub shipped gh skill in GitHub CLI v2.90.0 on April 16, 2026 (GitHub Changelog, Apr 16, 2026). It is the first cross-vendor package-manager–style interface for installing, updating, and publishing Agent Skills, and it brings supply-chain guarantees that the "clone and copy" approach lacked.

Installing:

# Browse a skills repository interactively
gh skill install github/awesome-copilot

# Install a specific skill
gh skill install github/awesome-copilot documentation-writer

# Target a specific agent host and install scope
gh skill install github/awesome-copilot documentation-writer --agent claude-code --scope user

# Pin to a release tag
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

# Pin to a commit SHA for maximum reproducibility
gh skill install github/awesome-copilot documentation-writer --pin abc123def

The --agent flag places the skill in the correct directory automatically. Supported hosts and their install targets:

Host	Install location
GitHub Copilot	.github/skills/ / user skills dir
Claude Code	.claude/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/
Gemini CLI	.gemini/skills/
Antigravity	.antigravity/skills/

Keeping skills current:

gh skill update                 # interactive check for all installed skills
gh skill update git-commit      # update one skill
gh skill update --all           # update everything without prompting

gh skill update reads provenance metadata embedded in the installed SKILL.md frontmatter by the install step (repository, git ref, tree SHA) and compares the local tree SHA to upstream. Only real content changes trigger an update prompt — version-bump-only releases without content changes are silently skipped.

Publishing:

gh skill publish          # validate all skills against the agentskills.io spec
gh skill publish --fix    # auto-fix common metadata issues

The publish command validates spec compliance, checks remote security settings (tag protection, secret scanning, code scanning), and optionally enables immutable releases — once a tag is published, even the repo owner cannot alter it. Pinned installs are therefore protected against supply chain compromise even if the repo is later taken over.

Supply-chain design: Each installed Skill carries tracking metadata (repository URL, git ref, tree SHA) inside its own frontmatter. The record survives moves, copies, and reorganizations because the provenance travels with the file itself. This is the same model that npm and cargo use for lock files, applied at the individual Skill level.

Discovery:

gh skill search mcp-apps

The community collection github/awesome-copilot is the most comprehensive public catalogue of cross-vendor Skills as of mid-2026.

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.

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. Migration is mechanical: take the Markdown body, add YAML frontmatter with name 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

• 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. Anthropic plugins only.
• Git tag per Skills repo. Natural fit for the Copilot / Codex commit-and-clone model.
• gh skill provenance tracking. Since April 2026, gh skill embeds tree SHAs in installed Skill frontmatter, enabling content-addressed change detection independent of version strings.

The runtime does not enforce that an installed Skill matches the latest version; users pull updates manually (or run gh skill update).

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. None of the three vendors ship a Skills-specific signing or sandboxing layer beyond what gh skill provides at the git level. De facto trust model:

• 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.
• Use gh skill with version pinning. Pin to a commit SHA for production deployments.

Vendor-side security knobs:

• Anthropic's experimental allowed-tools lets a Skill declare the minimum tool surface it needs.
• Copilot's disable-model-invocation: true forces a Skill to be user-invoked.
• Codex's policy.allow_implicit_invocation: false is the equivalent for Codex.

8. Organisation-level deployment

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

1. A central Skills repo under source control, owned by a small platform team.
2. A naming convention (<team>-<task> or <system>-<verb>) so Skill names don't collide across teams.
3. A test fixture per Skill, in the same repo, using the approach from the testing sub-page.
4. A CI job that runs the fixture on every PR.
5. A distribution job that publishes the latest Skills — plugin marketplace for Anthropic users, gh skill install with pinned tags for Copilot/Codex users, dotfiles for the rest.
6. A retirement process for superseded Skills; leave a one-line redirect tombstone pointing at the replacement.

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 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).

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; 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, SPDX identifier) is set if the Skill is leaving the org.
• [ ] Scripts under scripts/ have a shebang and are executable.
• [ ] 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.
• [ ] (If using gh skill) Run gh skill publish to validate against the agentskills.io spec before tagging a release.

Pass the checklist, then publish: plugin marketplace for Anthropic users; gh skill install with a pinned tag for Copilot/Codex users; dotfiles for everyone else; .agents/skills/ commit for all agents at once.

Changelog

• 2026-05-11 — Page created from the Anthropic authoring guide PDF (chapter 4) generalized across Claude / Copilot / Codex. Confidence 87.
• 2026-05-17 — Added §3.4 gh skill CLI (GitHub CLI v2.90.0, Apr 16 2026): install/update/publish with supply-chain provenance, version pinning, immutable releases. Updated §3.3 to reflect VS 2026 April update (VS now reads Agent Skills from .claude/skills/ and .agents/skills/). Added two new sources.