Claude skills: what they are, when to use them and how to build one

Anyone who uses Claude daily ends up repeating the same instructions: “use the company report template”, “format dates like this”, “no pie charts, please”. A skill is a way to write those instructions once, keep them in a folder and let Claude use them on its own whenever the task calls for it. This article explains, from scratch, what a skill is, how it works under the hood, when it is worth creating one and how to build it step by step. To keep it concrete, at the end I build a complete skill: one that teaches Claude to make charts following the principles of the book Storytelling with Data, by Cole Nussbaumer Knaflic.

§1What a skill is

A skill is a folder with instructions and, optionally, supporting files, which Claude loads when the task matches it. At its core is a file called SKILL.md: Markdown text with a small header stating the skill’s name and when to use it. Next to it there may be reference documents, templates, examples and scripts.

An analogy: Claude is a capable generalist. A skill is the procedures manual you hand them on day one — “this is how we write reports here”, “our charts follow these rules”, “this script converts the spreadsheet correctly”. They do not need to memorise the manual: they know it exists, know what it is for and open the right page when needed.

Three things define a skill:

• It is procedural knowledge, not facts. It teaches how to do something your way (the flow, the standard, the pitfalls), not information that changes every week.
• It is triggered by context. You do not need to call it: Claude decides to use it when the request matches the description. In Claude Code you can also invoke it explicitly with /skill-name.
• It is portable. The same folder works in Claude Code, the Claude app (claude.ai) and the API. You can version it in Git and share it with your team.

§2How it works: loading in layers

What makes skills practical is that they do not occupy the model’s context all the time. The context (the model’s working space, measured in tokens) is limited; if every installed skill poured all its content into every conversation, you could not have many. So loading happens on three levels — what Anthropic calls progressive disclosure:

In practice: Claude “knows” there is a chart skill because it read its one-line description. When you ask for a chart, it opens SKILL.md. If SKILL.md says “to choose the chart type, see references/escolha-do-grafico.md”, it opens that file — and only that one. That is why you can install dozens of skills without weighing anything down, and why a skill can carry extensive material: what is not needed stays on disk.

§3Skill, prompt, CLAUDE.md, MCP, subagent: which to use

Claude’s ecosystem has several ways to “teach” or “equip” the model, and they are easy to confuse. The difference is when each is loaded and what it provides:

A simple way to think about it: MCP gives Claude hands (access to systems); a skill gives Claude know-how (how to do it well). They combine: an MCP connector fetches the sales data; a skill says how to turn it into a chart that communicates.

§4What it is for, and when to create one

Create a skill when:

• You keep repeating the same instructions across conversations. If you have pasted the same guidance paragraph three times, it should be a skill.
• There is a house standard: visual identity, report format, proposal structure, writing style guide, conventions of an internal library.
• The task has a multi-step flow the model tends to skip or do out of order: contract review against a checklist, data analysis with validation, release preparation.
• There is domain knowledge the model lacks or applies inconsistently: the rules of a reference book (like this demo), company policies, quirks of a file format.
• Part of the work is deterministic and should be code, not generated text: converting formats, validating a file, applying a style. The skill can ship the script.

Don’t bother when:

• It is a one-off — write it in the prompt.
• It is a rule that applies to everything in a project — it belongs in CLAUDE.md.
• What is missing is access to a system, not instructions — that is an MCP connector.
• The information changes every week (prices, stock, news) — the skill goes stale; fetch the data at the time.

§5Anatomy of a skill

The minimal structure is a folder with one file. The typical structure, the one of the skill I am going to build, is this:

storytelling-charts/
├── SKILL.md                     # required: header + main instructions
├── references/                  # read on demand
│   ├── principios.md            #   the full principles, with the why
│   ├── escolha-do-grafico.md    #   reader's question → chart type table
│   └── checklist.md             #   review before delivering
└── scripts/
    └── sc_style.py              # matplotlib helpers (style, direct labels)

(The skill itself is written in Portuguese — Claude follows instructions in any language, and replies in the user’s.) SKILL.md starts with a YAML header between --- lines:

---
name: storytelling-charts
description: Builds explanatory charts that communicate a message, following
  the principles of "Storytelling with Data". Use whenever the user asks for a
  chart, visualization, data slide or dashboard to present to someone, and when
  they ask to review or "make clearer" an existing chart.
---

# Charts with storytelling

This skill turns "make a chart" into "communicate a conclusion with data".
...

• name: the skill’s identifier — lowercase letters, digits and hyphens, up to 64 characters. It is what appears in /storytelling-charts.
• description: the most important field of the whole skill (up to 1,024 characters). It is the only thing Claude sees before deciding whether to use it. It must say what the skill does and when to use it.
• Body: the instructions, in plain Markdown. Write as you would for a competent colleague who has never seen your process: imperative, direct, with examples. Keep SKILL.md under roughly 500 lines and move detail to files in references/.
• Supporting files: the body has to point to them (“read references/principios.md the first time”). A file no instruction mentions will probably never be opened.

In Claude Code the header accepts optional fields beyond these two — for example, restricting which tools the skill may use. To start, name and description are enough.

§6Building one step by step

1. Do the task once, in the chat, without a skill. Ask for the chart, fix what comes out wrong, write down every correction you had to make. Those corrections are the skill’s content. A skill written before you have done the task by hand tends to teach the obvious and forget what matters.

2. Write the description. It should contain the words you would use when asking (“chart”, “visualization”, “slide”, “dashboard”) and the boundaries (“not for quick exploratory plots”). Vague descriptions — “helps with data” — make the skill fire at the wrong time or never.

3. Write the body as a process. Numbered steps, in the order they should happen, with the why behind each rule. Explaining the reason (“pie charts are hard to compare because the eye judges angles poorly”) works better than just forbidding: the model generalises to cases you did not foresee.

4. Move detail into references/. Long tables, catalogues, extended examples, niche rules. SKILL.md stays lean and says when to open each file.

5. Turn what is mechanical into a script. If the model rewrites the same 30 lines of matplotlib setup every time, put them in a .py and have the skill use it. Code is deterministic, testable and costs no context to be “remembered”.

6. Install it. Where the folder goes depends on where you use Claude:

For this skill, in Claude Code:

# personal (works in any project)
cp -r skills/storytelling-charts ~/.claude/skills/

# or only in this repository
mkdir -p .claude/skills && cp -r skills/storytelling-charts .claude/skills/

7. Test and adjust (details in §10).

§7The description: the detail that decides everything

Since only the name and description are always visible, a great skill with a poor description is a skill that never runs. Three practical rules:

• State the trigger, not just the topic. “Visualization principles” describes a subject; “Use whenever the user asks for a chart, data slide or dashboard” describes a situation. Claude decides by situation.
• Include the synonyms people use. Chart, graph, plot, visualization, figure. Also indirect cases: “review an existing chart”, “make it clearer”.
• Say when not to use it, if there is a natural boundary. That keeps the skill out of neighbouring tasks.

Models tend to under-use skills — when in doubt, they do not load them. So the description can (and should) be a little pushy: “use whenever…” works better than “can be used for…”.

§8The demo: the book in six steps

Storytelling with Data is one of the most widely used books for teaching chart communication in business. Its central thesis is that an explanatory chart is an argument: it exists to lead a specific audience to understand something and act, and software defaults (designed to serve any data) almost never serve that goal. The book organises the work into six lessons, which became the six steps of SKILL.md:

1. Understand the context. Before opening the software: who the audience is (specific, not “management”), what they should know or do, and how they will see it (live presentation or a document read alone). Separate exploratory analysis (looking for what is interesting) from explanatory (showing what you found). Sum it all up in a big idea — one sentence with a point of view and what is at stake — and be able to tell the story in three minutes. Sketch the sequence on paper (storyboard) before producing anything.
2. Choose an effective visual. A small repertoire covers almost everything: simple text for one or two numbers, table, heatmap, scatter, lines, slopegraph, bars (vertical, horizontal, stacked), waterfall. Avoid pies and donuts, 3D and dual axes. Bars always start at zero.
3. Eliminate clutter. Every element without a function adds cognitive load. The Gestalt principles (proximity, similarity, closure, continuity, connection, enclosure) explain why borders, gridlines and legends are usually dispensable. Align, use white space, label directly.
4. Focus attention. Preattentive attributes — colour, intensity, size, position, bold — are perceived before conscious reading. The recipe: everything grey, colour only where the message is. If everything stands out, nothing does.
5. Think like a designer. Make it obvious how to “use” the chart (what to look at first), make it accessible (a title that states, labelled axes, annotations, plain language), care about aesthetics and plan for the audience’s acceptance of new formats.
6. Tell a story. Beginning (context and conflict), middle (the data that develops the problem and the options), end (the call to action). Check it via slide titles read in sequence (horizontal logic) and each slide’s content (vertical logic). Repeat the message at the start and the end.

The file references/principios.md develops each step with the why, the recurring patterns of good charts and the narrative tactics; escolha-do-grafico.md holds the “reader’s question → chart” table; checklist.md is the final review. The full folder is in this site’s repository.

§9Before and after

The same (made-up) data in two versions. First, what comes out of software with default settings, or of a generic request like “chart the returns by product line”:

Now the same chart after going through the skill’s six steps. The big idea was defined first: returns of the kids’ line doubled after the supplier change in March. Everything else serves that sentence:

Notice what left: border, gridlines, markers, legend, decimals, slanted dates, two colours. And what came in: a concluding sentence, one annotation, two numbers. On a slide, the next step would be the call to action — say, “we propose going back to the previous supplier for the Christmas collection” — and, when presenting, revealing the grey lines first (normal), then the blue one (the problem).

The skill’s scripts/sc_style.py produces this version in matplotlib with a few calls: setup() applies the defaults, declutter() removes borders and ticks, label_line_end() places the label at the end of the line and title_block() builds the left-aligned concluding title. Running the file directly produces the demo chart:

python skills/storytelling-charts/scripts/sc_style.py demo.png

§10Testing and improving the skill

A skill is text that changes a model’s behaviour — and the only way to know it works is to test it. A lean routine:

• Test the trigger. Make requests that should activate the skill (“build a chart of sales by region for the meeting”) and neighbouring ones that should not (“what is the mean of this column?”). If it does not fire, or fires too much, the problem is in the description.
• Compare with and without. Same request, one session with the skill and one without. If the result is the same, the skill is not teaching anything the model did not already do.
• Read what the model did, not just the result. Did it open the reference files? Skip steps? If it ignores an instruction, maybe it is buried mid-text, or lacks the why.
• Fix the cause, not the case. If the chart came out with a legend, do not add “no legend in this sales chart”; reinforce the general principle and its reason (“a direct label saves the eye a round trip”).
• Keep it lean. Instructions that change nothing in the result only spend context. Cut them.

In Claude Code and claude.ai there is an official skill for this, skill-creator: it interviews you about what the skill should do, writes the draft, runs test cases with and without the skill and helps tune the description. A good starting point for a first skill.

§11Takeaways

• A skill is a folder with a SKILL.md (name, description and instructions) and, if needed, reference files and scripts.
• It is loaded in layers: only the description is always visible; the rest comes in when the task needs it. So it can be extensive without weighing anything down.
• Use a skill for recurring procedures and domain knowledge; CLAUDE.md for always-on rules; MCP for system access; the prompt for one-offs.
• The description decides whether the skill runs: write the trigger, the synonyms and the boundaries.
• Build the skill from a real task, explain the why behind the rules, move detail into references/, turn the mechanical into scripts and test with and without.
• The storytelling-charts skill shows the full pattern applied to a book: context → visual → declutter → attention → design → story.

References: Agent Skills documentation and skills in Claude Code (Anthropic); Anthropic’s public skills repository; Cole Nussbaumer Knaflic, Storytelling with Data: A Data Visualization Guide for Business Professionals (Wiley, 2015). The full skill: skills/storytelling-charts. The chart data is made up.