Back to blog

What is a Claude Code skill and why should you care

by Mack 3 min read explainerskills

The one-sentence version

A skill is a markdown file that gives Claude standing instructions for a specific task.

That is it. No code to write. No framework to learn. A text file with structure.

What problem it solves

When you use Claude through a chat interface, you start from zero every session. No memory of how you like things formatted. No memory of the context that matters for your work. No memory of the edge cases you sorted out last time.

So you rebuild that context every time. You retype the background. You re-explain the format. You remind it what matters and what to skip.

That is waste. Not because Claude cannot remember, but because you have not given it a permanent home for those instructions.

A skill file is that home.

How a skill works

You write a SKILL.md file. It contains:

  • What this skill does and when to use it
  • The specific instructions Claude should follow
  • The format the output should take
  • Any edge cases, constraints, or context worth preserving

When you run the skill, Claude loads those instructions and operates within that frame. Same behavior, every time.

Here is a minimal example:

# Skill: Meeting Summary

## What this does
Takes raw meeting notes and returns a clean summary with decisions,
action items, and open questions.

## Instructions
1. Read the notes provided.
2. Identify every decision made in the meeting.
3. List every action item with an owner if one was mentioned.
4. Flag anything left unresolved.
5. Write a 2-sentence summary for someone who was not in the meeting.

## Output format
**Summary:** [2 sentences]

**Decisions:**
- [decision 1]

**Action items:**
- [item] — Owner: [name or "unassigned"]

**Open questions:**
- [question]

Run this once and you have a meeting summarizer. Run it fifty times and it behaves exactly the same way on the fiftieth run as it did on the first.

The folder structure

A skill lives in a folder. That folder usually contains:

meeting-summary/
  SKILL.md          — the instructions (required)
  examples/         — sample inputs and outputs (optional)
  scripts/          — helper code if the skill calls tools (optional)
  references/       — background docs Claude can read for context (optional)

The only required file is SKILL.md. Everything else is there to make the skill more reliable or more capable.

The examples folder matters more than people expect. One good input/output pair teaches Claude exactly what quality looks like for your specific use case. More than any amount of descriptive text.

Why this matters

Three properties make skills worth building:

Portable. A skill is a text file. It lives on your machine. It goes with you to any project, any session, any team. You are not locked into a platform or a subscription to keep your capabilities.

Shareable. Because it is a text file, you can send it to a colleague in thirty seconds. They install it and have the same capability you built. No configuration, no credentials, no setup guide.

Composable. Skills stack. A research skill can feed a writing skill. A writing skill can feed a review skill. You build each piece once and chain them together. The output of one becomes the input of the next.

That composability is where skills turn into systems. And systems are what save 10-20 hours a week instead of 20 minutes here and there.

What skills are not

Skills are not magic. They do not fix bad prompting or turn vague instructions into good results. If your SKILL.md is ambiguous, Claude will produce inconsistent output. The quality of your instructions determines the quality of your results.

Skills are also not code. You cannot run loops or call external APIs directly from a SKILL.md file. For that, you need scripts, and skills can call scripts. But the skill itself is instructions, not logic.

Think of SKILL.md as the spec. Scripts are the execution layer when you need one.

Where to start

Build a skill for the task you do most often with AI.

If you write weekly summaries, build a summary skill. If you do client research, build a research skill. If you write content, build a content skill.

Write the instructions as specifically as you can. Include an example. Run it ten times. Fix whatever breaks.

That is the whole method. No framework. No architecture review. One file, one task, running better every time you refine it.

A year of building skills this way produces a library of capabilities. Each one earns its place because you built it for something real.

All of our tools are free on GitHub. The full system is $497 lifetime at realityresearch.studio.