skillsrun

primer

What is a Claude skill, and why does yours never trigger?

A skill is a folder with a SKILL.md file that Claude opens only when the description matches your request. That single sentence explains most of what goes wrong.

A skill is a folder, not a plugin

Strip the marketing off and a skill is this: a directory with one SKILL.md file in it. Nothing compiles, nothing runs as a service, there is no server to host. Claude reads the front matter, decides whether the skill is relevant to what you just asked, and if it is, opens the instructions and follows them.

my-skill/
└── SKILL.md

That is the whole minimum. Bigger skills add scripts/, references/ and assets next to it — the document skills inside anthropics/skills ship scripts that build and inspect real .docx and .pptx files.

What goes inside SKILL.md

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[instructions Claude follows when this skill is active]

## Examples
- Example usage 1

## Guidelines
- Guideline 1

Two front-matter fields are required: name (lowercase, hyphens for spaces) and description. The description is not decoration — it is the matching surface. Claude chooses from it, so "helps with code" loses to "reviews a git diff for correctness, naming and missing tests".

How triggering actually works

Three consequences worth internalising:

  1. Vague asks skip skills. "Make this better" matches nothing. "Review my working tree before I commit" matches a review skill, because that is how the skill describes itself.
  2. Naming it is allowed. You can say "use the code-review skill on this diff" and it loads regardless of phrasing.
  3. Install scope is not global by default. A skill added in one project's agent does not automatically appear in another tool. When something seems broken, check it is installed where you are actually working before blaming the skill.

Skill, MCP server, plugin

Thing What it is What it is good for
Skill A folder of instructions and resources Teaching a repeatable workflow, house style, checklists
MCP server A connection exposing tools and data Letting the agent reach a database, an API, a browser
Plugin A package that can bundle skills, commands, MCP config Installing a whole setup in one move

They stack. You use an MCP server so the agent can reach your CMS, a skill so it knows your publishing checklist, and a plugin to ship both to a teammate.

Where skills come from

The mistake everyone makes first

Installing twenty skills. Each one costs context when it loads and adds another description the model has to weigh, so a bloated set makes triggering worse, not better. Install find-skills, then add one skill per real repeatable task — a review skill, the design skill for the stack you actually use, and nothing else until you feel the gap.

Questions people actually ask

What exactly is a Claude skill?
A folder containing a SKILL.md file: YAML front matter with a name and a description, then instructions in Markdown. Claude loads it dynamically when your request matches the description, and follows the instructions as context. It can also carry scripts and reference files.
How do I install one?
Through the skills CLI (npx skills add https://github.com/OWNER/REPO --skill NAME) or, inside Claude Code, by adding anthropics/skills as a plugin marketplace and installing a plugin from it. Copy the exact command from the skill's own page — the --skill flag matters when a repo holds several skills.
Do skills cost money?
No. Skills are open-source folders of text and scripts. What costs money is the model usage when Claude runs them, and the paid Claude.ai tier that bundles the document skills.
Why does a skill never fire when I ask for the work?
The description in SKILL.md is what gets matched, so phrase the request the way the skill describes itself, or name the skill outright. If that still fails, confirm the skill is installed for the agent and directory you are working in.