Claude Skills – Creating and Sharing Skills

In our previous blog, Model Context Protocol (MCP) – A Deep Dive, we built a small MCP server for an IT service help desk. It lets employees and the IT service team raise, find and update tickets from an AI assistant, instead of filling in forms and searching through queues.

An MCP server on its own leaves two gaps. New users have to work out what to ask before they get anything useful out of it. And a task that should come out the same way every time, such as the morning review of a team’s ticket queue, has to be asked for in full each time. Even then, there is no guarantee that it comes back in the same format.

Claude Skills close both gaps. In this blog, we will look at what a skill is, how it differs from an MCP server, the skills that suit a help desk, and the ways to share skills across an organization, including a plugin marketplace. Setting up a marketplace and a plugin is much simpler than the terms suggest.

A Claude Skill is a packaged folder of Markdown instructions, helper scripts and resources that teaches Claude how to perform a specialized, repeatable task. A prompt gives Claude instructions for one conversation. A skill stays installed, and Claude uses it whenever the task comes up.

What Goes Into a Skill?

Every skill is a folder with a SKILL.md file at its root. Below is the layout of a typical skill:

queue-brief/
├── SKILL.md            instructions, with the name and description at the top
├── brief-format.md     reference file, read only when needed
└── scripts/
    └── sla_check.py    helper script, run rather than read

The SKILL.md file has two parts:

• Frontmatter: A short YAML block at the top with the skill’s name and a description. The description is the most important line in the skill, because Claude uses it to decide when the skill applies.
• Instructions: Plain Markdown that tells Claude what to do, step by step, and what the result should look like.

Below is a simplified example, a queue brief for the IT service team. It lists the open tickets in the team’s queue, with the ones close to breaching their service level agreement (SLA) first:

---
name: queue-brief
description: >-
  Summarizes the open tickets in an IT help desk queue. Use when the
  user asks what is open, for the morning brief, or which tickets are
  close to breaching their SLA.
---

# Queue brief

1. Use the user's own team, unless they name a different one.
2. Call the list_tickets tool for the open tickets in that team's queue.
3. Run scripts/sla_check.py to find the tickets close to their SLA.
4. Group the tickets by priority, and list the SLA risks first.
5. Write the brief in the format described in brief-format.md.

How Does Claude Load a Skill?

Claude does not read every installed skill in full. It loads each skill in three layers, which Anthropic calls progressive disclosure:

• At startup: Only the name and description of each installed skill.
• When the task matches: The full SKILL.md, once Claude decides that the skill applies. In Claude Code, users can also run a skill as a slash command, such as /queue-brief.
• When needed: Supporting files, such as the reference file above, are read only when the instructions point to them. Scripts are run without their code being loaded into the conversation.

This is why you can install many skills without filling Claude’s context window, the same context bloat we warned about for MCP tools in our previous blog.

Skills and MCP servers are often mentioned together, but they solve different problems. An MCP server gives Claude access to a system. A skill gives Claude the know-how to use that access for a particular task. This table shows the main differences:

The two work best together. In the help desk example, the MCP server provides the tools, and each skill describes which tools to call, in what order, and how to present the result.

Skills on top of an MCP server help in three ways:

• To help new users get started: A new user can run a skill without knowing what to ask. Running the queue brief gives a new member of the IT service team a useful report straight away, and it also shows them what the server can do.
• To make tasks repeatable: A skill fixes the steps and the format, so the same report comes out the same way every day, whoever asks for it.
• To capture the team’s know-how: Rules that live in a few people’s heads, such as which category of ticket goes to which team, can be written into a skill that everyone uses.

Below are some skills that suit an IT help desk:

Note that raise-ticket does more than call create_ticket. It first searches the knowledge base, so that a known fix can save a ticket altogether, and it asks for any missing details, such as the device or the location, instead of guessing them.

A skill only helps the people who have it installed. There are four ways to share skills, and they differ mainly in how new versions reach your users:

Which option fits depends on how many people need the skills and how often they change. When skills are used across several teams and change over time, a plugin in a marketplace gives everyone one place to install them from and to get updates. That is the option we will set up below.

The two terms sound heavier than they are:

• Plugin: A folder that bundles skills with a small manifest file. It can also carry other things, such as slash commands, subagents, hooks and MCP server settings.
• Marketplace: A catalog of plugins. In practice, it is a Git repository with one JSON file that lists the plugins and where to find them.

Below is a simplified layout of a Git repository that holds both:

helpdesk-skills/                      marketplace root (the Git repository)
├── .claude-plugin/
│   └── marketplace.json              lists the plugins in this marketplace
└── plugins/
    └── helpdesk/
        ├── .claude-plugin/
        │   └── plugin.json           the plugin's manifest
        └── skills/
            ├── queue-brief/
            │   └── SKILL.md
            ├── raise-ticket/
            │   └── SKILL.md
            └── triage-ticket/
                └── SKILL.md

The marketplace file needs a name, an owner and the list of plugins, each with a name and the path to its folder:

{
  "name": "helpdesk-skills",
  "owner": { "name": "IT service team" },
  "plugins": [
    {
      "name": "helpdesk",
      "source": "./plugins/helpdesk",
      "description": "Skills for the IT help desk"
    }
  ]
}

The plugin’s manifest only needs a name, though a version and a description help users:

{
  "name": "helpdesk",
  "version": "1.0.0",
  "description": "Skills for the IT help desk"
}

Keep the plugin’s name the same in both files, because it is the name users type when they install it.

Once the repository is pushed, each user runs three commands in Claude Code:

/plugin marketplace add your-org/helpdesk-skills
/plugin install helpdesk@helpdesk-skills
/reload-plugins

• The first command registers the repository as a marketplace.
• The second finds the plugin in that marketplace and installs it.
• The third loads the new skills into the running session, without a restart.

Skills from a plugin are named after the plugin, so the queue brief runs as /helpdesk:queue-brief and cannot clash with a personal skill of the same name. A plugin can also declare MCP servers in a .mcp.json file, so one install can give users both the tools and the skills that use them.

Anthropic’s documentation on skills covers the details. Three points from it are worth keeping in mind from the start:

• Write the description for Claude: Say what the skill does and when to use it, in the words users actually use, such as “my tickets” or “SLA”. Claude picks a skill by its description, so a vague one means the skill is rarely used.
• Keep SKILL.md short: Anthropic recommends keeping it under 500 lines. Move long reference material into separate files, and point to them from the instructions.
• Use scripts for fixed logic: When a step must give the same result every time, such as working out the business hours left before an SLA breach, a script does it more reliably than written instructions.