What is a skill, really?
A skill is the simplest way to teach an AI assistant to handle a specific task: a single Markdown file with YAML frontmatter at the top, optionally accompanied by reference files and executable scripts. The agent reads the file on demand when the description matches the user's request. That is the entire model. Everything else (how you distribute it, how it gets installed, what UI a catalog wraps around it) is built around that one file.
The four-way comparison: skill vs MCP vs system prompt vs CLI
It is easier to understand what a skill IS by understanding what it is NOT.
| Tool | What it is | When you'd write one |
|---|---|---|
| Agent skill | A Markdown file the LLM reads on demand to learn how to handle a specific task type | You want the LLM to know HOW to do something without you having to repeat the instructions in every conversation |
| MCP server | A network service the LLM calls to get live data or perform stateful operations | You need the LLM to read or write external state (a database, an API, a file system) |
| System prompt | Persistent instructions injected at conversation start | You want behavior that applies to ALL of an assistant's interactions, not just task-specific |
| CLI tool | A program a human runs directly | The user knows the exact command they want to run; no natural-language routing needed |
A common confusion: people write a skill when they actually need an MCP. If your "skill" boils down to "the LLM should call this API and return the JSON," that is an MCP server, not a skill. Skills are for HOW to do something (decision rules, structure, judgment); MCPs are for accessing live state.
A second common confusion: people write a skill when they actually need a system prompt. If you want Claude to always speak in your brand voice across every conversation, that is a system prompt or a custom GPT, not a skill. Skills are loaded ON DEMAND when the user's intent matches the skill's description.
The skill format, in one paragraph
Every skill is a folder containing at minimum a SKILL.md file with YAML frontmatter. The frontmatter requires two fields per the Anthropic spec, name (kebab-case slug) and description (one or two sentences the LLM reads to decide whether to load the skill). license is conventional in the upstream spec and is expected by most ecosystem tooling. The body is plain Markdown, loaded into the LLM's context once the skill is invoked. Optionally the folder can contain a references/ subfolder (static files the LLM reads when needed) and a scripts/ subfolder (executable code the agent's shell tool can run). That is the entire spec.
When NOT to write a skill (the decision tree)
Before you write a single line of SKILL.md, run this check:
- Does the LLM already do this well without a skill? If you ask Claude "format this Israeli phone number" and it does it correctly on the first try, you do not need a phone-formatter skill. Skills are for cases where the default behavior is wrong, incomplete, or culturally tone-deaf.
- Does the task require live data? If the answer changes hourly (stock prices, government API responses, traffic), the skill is the wrong abstraction. Write an MCP server.
- Is the task purely computational with a single right answer? A simple checksum or format converter might be better as a one-line scripts/ entry called from inside a larger skill, not as its own skill.
- Are you sure the audience needs it? Talk to 3 prospective users before writing. Skills nobody uses get quietly abandoned by their authors; pre-validating saves you the disappointment.
The most common mistake in Chapter 1: writing a skill where an MCP would fit better. Symptom: your skill's body is mostly "call this URL, parse this JSON, return this field." Fix: convert to an MCP server with a single tool, and your "skill" becomes a one-line MCP invocation.
If your topic survives the decision tree, move on to Chapter 2 to learn what to put in SKILL.md.