Distribution
How to ship skills across Claude.ai, Claude Code, and the API — plus the GitHub workflow Anthropic recommends.
January 2026 Distribution Model
Skills work identically across Claude.ai, Claude Code, and the API — build once, ship everywhere. The distribution path differs by surface: Claude.ai uses an upload flow, Claude Code reads from a local directory, and the API loads skills via the Messages API.
| Use Case | Best Surface |
|---|---|
| End users interacting with skills directly | Claude.ai / Claude Code |
| Manual testing and iteration during development | Claude.ai / Claude Code |
| Individual, ad-hoc workflows | Claude.ai / Claude Code |
| Applications using skills programmatically | API |
| Production deployments at scale | API |
| Automated pipelines and agent systems | API |
Individual Users
- ▸Download the skill folder.
- ▸Zip the folder (if needed).
- ▸Upload to Claude.ai via Settings → Capabilities → Skills, OR place in the Claude Code skills directory.
Organizations
Since December 18, 2025, admins can deploy skills workspace-wide. This enables automatic updates, centralized management, and guarantees that every member of the org sees the same skill definitions.
API
For programmatic use cases — applications, agents, automated workflows — the API gives direct control over skill management. Skills in the API require the Code Execution Tool beta.
- ▸/v1/skills endpoint for listing and managing skills
- ▸Add skills to Messages API requests via the container.skills parameter
- ▸Version control and management through the Claude Console
- ▸Works with the Claude Agent SDK for building custom agents
Agent Skills are published as an open standard, alongside MCP. A skill that respects the standard is portable across Claude and other AI platforms. Use the compatibility field when a skill depends on platform-specific capabilities.
Recommended GitHub Workflow
The current best practice is to host the skill folder in a public GitHub repo with a repo-level README (for human visitors — not inside the skill folder itself), example usage with screenshots, and an installation guide. Then link the skill from your MCP documentation and explain why the combination is more valuable than either alone.
## Installing the [Your Service] skill
1. Download the skill:
- Clone repo: `git clone https://github.com/yourcompany/skills`
- Or download ZIP from Releases
2. Install in Claude:
- Open Claude.ai > Settings > Skills
- Click "Upload skill"
- Select the skill folder (zipped)
3. Enable the [Your Service] skill:
- Toggle on the [Your Service] skill
- Ensure your MCP server is connected
4. Test:
- Ask Claude: "Set up a new project in [Your Service]"Positioning: Outcomes, Not Features
The description in your README determines whether users understand the value. Describe what users accomplish, not what the skill contains internally. The skill-folder-with-YAML-and-Markdown is an implementation detail; the saved hour of manual setup is the product.
# Good — outcome-focused
"The ProjectHub skill enables teams to set up complete project workspaces in seconds — including pages, databases, and templates — instead of spending 30 minutes on manual setup."
# Bad — implementation-focused
"The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools."When positioning an MCP + skill combination, tell the full story: the MCP server gives Claude access; the skill teaches Claude the workflow; together they enable AI-powered management of the domain.