What Are Claude Agent Skills?

Anyone who has used Claude for some time will have retyped the same instructions: format a spreadsheet, follow a code-review checklist, or build a deck to a house style. Agent Skills exist so that those instructions need not be restated. This guide explains what a skill is, how the SKILL.md format works, and how skills differ from prompts, plugins, and MCP.

A skill is a folder with a SKILL.md file

A skill is a directory containing a single SKILL.md file. That file has two parts:

• YAML frontmatter — a short block at the top with a name and, most importantly, a description. The description is the trigger: it tells the model when to reach for this skill.
• Markdown instructions — everything below the frontmatter: the actual how-to knowledge, written as if you were briefing a capable new teammate.

A minimal skill looks like this:

---
name: excel-reports
description: Create formatted .xlsx spreadsheets with working formulas,
  pivot tables and charts. Use when the user asks for an Excel file,
  a spreadsheet, or a financial model.
---

# Creating Excel reports

When building a spreadsheet:
1. Put raw data on a "Data" sheet and analysis on a "Summary" sheet.
2. Use real formulas (SUMIF, XLOOKUP) so numbers stay live.
3. Format headers bold, freeze the top row, add a title.
...

The description is the whole game

The single biggest factor in whether a skill helps you is its description. Claude reads only the name and description of every installed skill up front — the full instructions are loaded on demand. So the description has to clearly name the situation the skill is for, not just the topic. “Helps with documents” is useless; “Fills, extracts and summarizes PDF forms; use when the user uploads a PDF or asks to extract a table” is what makes the skill fire at the right moment.

Progressive disclosure: why skills stay cheap

Skills are designed around progressive disclosure. Only the name and description sit in context at all times (a few tokens each). When your request matches, Claude pulls in the full SKILL.md body. If that body points to extra files — a reference.md, a script, a template — those are read only if needed. The result: you can have dozens of skills installed without paying a token cost for the ones you are not using right now.

Skills vs prompts vs plugins vs MCP

These four things are easy to confuse. Here is the short version:

They are complementary, not competing. A common pattern: MCP gives Claude access to your database, and a skill teaches it the right way to query that database. Want to build one of your own? See how to create a Claude skill, or if a skill is misbehaving, jump to why skills stop working.

Official vs community skills

Official skills come from Anthropic’s own repository — the built-in document skills (PDF, Excel, Word, PowerPoint), plus tools like the Skill Creator and MCP Builder. Community skills are written by developers and teams solving their own problems. Both can be excellent; the difference is provenance and testing. OpxSkills rates every skill with an OpxScore (documentation, practicality, evidence, and source trust) and marks whether that score is reviewed or provisional, so you can tell them apart at a glance.

Who should use skills?

Anyone who does a task with Claude more than once. Writers package their house style; engineers encode their review checklist and testing workflow; analysts save their reporting format. Good first skills are the built-in document ones and the Skill Creator, which scaffolds new skills for you. Browse by what you do in the Coding, Writing, and Analysis categories, or see every skill that works with Claude.

Frequently asked questions