How users install skills

Individual installation (Claude.ai)

1. Zip the skill folder (the folder containing SKILL.md)
2. Go to Settings > Capabilities > Skills
3. Upload the zip file
4. Skill is immediately available in all new conversations

The zip should contain the skill folder as root (e.g., code-reviewer/SKILL.md), not a loose SKILL.md at the zip root.

Claude Code installation

# Copy your skill to Claude Code's skills directory
cp -r ./my-skill ~/.claude/skills/my-skill

Claude Code automatically detects skills in this directory. Changes take effect in the next conversation.

Organization-wide deployment

Admins can deploy skills workspace-wide:

• Automatically available to all members without individual installation
• Updates propagate when the admin updates the skill
• New team members get all skills immediately

This is the recommended approach for team skills, everyone uses the same version.

Skills as an open standard

Anthropic published Agent Skills as an open standard. Your skill folder is a portable artifactWhat is artifact?The output files produced by a build step (like a dist/ folder) that are ready to be deployed to a server. Ask AI for more, you can version control it in git, share it on GitHub, and others can forkWhat is fork?A personal copy of someone else's repository on a platform like GitHub, letting you make changes freely and propose them back via pull request. Ask AI for more and improve it. The format is documented and stable.

Distributing with an MCPWhat is mcp?Model Context Protocol - a standard that lets AI tools connect to external services like databases, issue trackers, or APIs. Ask AI for more integration

Bundling skills with your MCP server is a significant advantage:

Without a bundled skill: Users connect your MCP but don't know what to do next. Support tickets pile up. Each user discovers workflows independently.

With a bundled skill: Pre-built workflows activate automatically. Best practices are embedded from the first sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more. Users get value within minutes, not hours.

Here's what a bundled MCP + Skill distribution looks like:

your-product-mcp/
├── src/                    ← MCP server code
│   └── index.ts
├── skills/                 ← Bundled skills
│   ├── setup-project/
│   │   └── SKILL.md
│   └── generate-report/
│       ├── SKILL.md
│       └── references/
│           └── report-formats.md
└── README.md               ← Installation guide (at repo root)

What to include in your skill package

your-skill-name/            ← Root folder (kebab-case)
├── SKILL.md                ← Required
├── scripts/                ← Optional: only if needed
│   └── process.py
├── references/             ← Optional: internal docs
│   └── api-patterns.md
└── assets/                 ← Optional: templates
    └── report-template.md

Do NOT include:

• README.md inside the skill folder (confuses the skill loader, put it at repo root instead)
• Large binaryWhat is binary?A ready-to-run file produced by the compiler. You can send it to any computer and it just works - no install needed. Ask AI for more files (images, videos, compiled executables)
• Secrets or APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more keys (even in reference files, these get distributed with the skill)
• Dependencies or node_modules (note requirements in compatibility instead)
• Generated or temporary files (.DS_Store, __pycache__, etc.)

For GitHub distribution: Add a README.md at the repositoryWhat is repository?A project folder tracked by Git that stores your files along with the complete history of every change, inside a hidden .git directory. Ask AI for more root (not inside the skill folder).

Version your skill like code

Skills are files, treat them like code with version control and meaningful commitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. Ask AI for more messages.

# Initialize a git repo for your skill
git init my-skill
cd my-skill

# Track changes over time
git add SKILL.md
git commit -m "v1.0: initial release with sprint planning workflow"

# When you improve it based on feedback
git commit -m "v1.1: fix undertriggering on paraphrased requests"

# When you add a new workflow
git commit -m "v1.2: add backlog grooming workflow"

Update the version field in your YAMLWhat is yaml?A human-readable text format used for configuration files, including Docker Compose and GitHub Actions workflows. Ask AI for more metadata when you ship meaningful changes:

metadata:
  version: 1.2.0
  changelog: "Added backlog grooming workflow, improved trigger coverage"

Building a skill ecosystem

A well-designed skill ecosystem is more valuable than the sum of its parts.

A thoughtful distribution strategy turns individual productivity gains into organizational ones.