What skills are and why they matter

# What skills are and why they matter

Type "build me a budget model" into a stock chatbot and you get a wall of text describing what a budget should contain. Type it into Claude with the right Skill loaded and you get back an actual budget_model.xlsx file, formulas wired up, summary tab included, ready to open in Excel. That difference is what this lesson is about.

A Skill is a packaged folder of instructions and supporting files that Claude loads only when a task calls for it. It is the mechanism that turns a general-purpose assistant into a domain specialist on demand, without you re-explaining the domain every single time.

The core idea: progressive disclosure

You already know the context windowcontext windowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.View full definition → is finite and that stuffing it with instructions is wasteful. Skills solve this with progressive disclosure: Claude reads only a short description of each available Skill up front, then loads the full instructions and files *only when* a task matches.

Think of it in three layers:

1. Metadata (always visible): a name and a one-line description, e.g. "Creates and edits Excel spreadsheets with formulas and charts." This is tiny and costs almost nothing in context.

2. Instructions (loaded on match): a SKILL.md file with the detailed how-to. Claude pulls this in once it decides the Skill is relevant.

3. Bundled resources (loaded as needed): scripts, templates, reference docs, schemas. Claude reaches for these only when the specific step requires them.

So a workspace can have twenty Skills installed and pay almost no context tax until one is actually triggered. That is the whole trick, and it is why Skills scale where a giant master prompt does not.

The official reference lives at docs.claude.com, and Anthropic publishes example Skills openly at github.com/anthropics/skills.

Anatomy of a skill

A Skill is just a folder. At minimum it contains a SKILL.md file with a YAML frontmatter block at the top and instructions below it.

Here is what the frontmatter for a spreadsheet Skill looks like:

name: xlsx-builder
description: >
  Build and edit real .xlsx files from structured requests like budgets,
  forecasts, and trackers. Use when the user wants a downloadable spreadsheet
  with working formulas, not a description of one.

The description is the most important line you will write. It is the metadata Claude reads at all times, and it is how Claude decides whether to load the Skill. Vague descriptions get ignored; precise, trigger-word-rich descriptions get picked up at the right moment.

Below the frontmatter, the SKILL.md body holds the actual playbook in plain Markdown. For our spreadsheet Skill it might say:

• Use the openpyxl library to write files.
• Always create a Summary tab plus one tab per data category.
• Reference cells in formulas, never hard-code totals.
• Save output to a file the user can download.

A Skill can also bundle a real script so Claude does not reinvent it each time:

# scripts/build_budget.py
from openpyxl import Workbook

def build_budget(categories: dict[str, float], path: str) -> str:
    wb = Workbook()
    ws = wb.active
    ws.title = "Budget"
    ws.append(["Category", "Monthly", "Annual"])

    for row, (name, monthly) in enumerate(categories.items(), start=2):
        ws.cell(row=row, column=1, value=name)
        ws.cell(row=row, column=2, value=monthly)
        ws.cell(row=row, column=3, value=f"=B{row}*12")

    last = len(categories) + 1
    ws.append(["Total", f"=SUM(B2:B{last})", f"=SUM(C2:C{last})"])
    wb.save(path)
    return path

Notice the formulas (=B2*12, =SUM(...)) are written *into* the file. The user gets a live model they can edit, not a static snapshot. That is the leap from "describe a budget" to "deliver a budget."

A Skill is not a one-off prompt

This is the distinction that matters most, so let's make it concrete.

A one-off prompt is a message you type once. Even a brilliant one is gone the moment the conversation moves on. To repeat the result, you copy-paste it, tweak it, and hope you remembered every nuance. It does not version, it does not carry files, and your teammates cannot reuse it without you sharing the raw text.

A Skill is a reusable asset:

• It persists. Once installed, it is available across conversations without re-pasting.
• It carries files. Scripts, templates, and reference data ride along. A prompt can only contain words.
• It is shareable and versionable. A folder can be committed to git, reviewed, and improved over time. "Make the budget Skill always include a 12-month projection" is a one-line edit that everyone inherits.
• It loads conditionally. A prompt is always in your context if you paste it. A Skill costs nothing until it is needed.

A prompt tells Claude what to do *this once*. A Skill teaches Claude how to be good at a *category* of task, every time, with the tooling attached.

Where Skills run

Skills are not tied to one surface. The same packaged capability shows up across the Anthropic ecosystem:

• The Claude apps (web, desktop, mobile): you enable Skills in your settings, and Claude invokes them automatically when a task matches. This is where the spreadsheet example produces a downloadable file directly in the conversation.
• Claude Code: Skills extend Claude's behavior inside your terminal and editor, so a "generate a release-notes doc" Skill works the same way it does in the web app.
• The Anthropic API and the Claude Agent SDK: when you build your own agents, you can ship Skills so your application's Claude has the same specialist behaviors. See the Claude Agent SDK docs for how managed agents load them.

One folder, many runtimes. You author the capability once and it travels.

Skills vs. the rest of the toolbox

You have met several Claude features by now, and it is easy to blur them. Here is the clean mental model:

• Projects group conversations and shared context (files, instructions) around a body of work. They are *where* you work.
• Artifacts are the live output pane for code, documents, and apps Claude generates. They are *what you see* as a result.
• Styles shape Claude's tone and voice. They change *how it sounds*.
• Connectors and MCP give Claude access to external data and tools (your Google Drive, a database, an internal APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →) over a standard protocol. They change *what Claude can reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition →*. More on these at

The useful pairing: a Connector lets Claude pull last quarter's actuals from your finance system, and a Skill knows how to turn those numbers into a properly structured .xlsx model. ReachReachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → and know-how are different problems, and Skills own the know-how half.

When to build a Skill (and when not to)

Not every task deserves a Skill. The test is repetition plus specificity.

Build a Skill when:

• You do the same *kind* of task repeatedly (monthly board decks, contract summaries, formatted exports).
• The task has rules that are tedious to restate ("always two decimal places," "company brand colors," "this exact tab structure").
• The task benefits from bundled code or templates that would be painful to paste each time.

Skip it when:

• The task is genuinely one-off. A good prompt is faster.
• The "rule" is really just your taste in tone. That is a Style, not a Skill.
• You mainly need *access* to a system rather than procedure. That is a Connector, not a Skill.

A quick gut check: if you find yourself pasting the same long instruction block for the third time, that block wants to be a Skill.

How Claude decides to use one

Claude does not run every Skill on every message. It reads the available descriptions, compares them to your request, and loads the best match. This is why the description field is doing real engineering work.

Compare:

• Weak: description: helps with spreadsheets