If you've spent any time around Claude lately — Anthropic's family of AI models — you may have come across the term SKILL.md. It looks like a technical detail. It isn't. SKILL.md is the small piece of plumbing that's quietly changing how people direct an AI to do useful work — not just answer questions, but follow a procedure, in a particular voice, with a particular set of constraints. This piece explains what it is, where it came from, and why someone outside engineering should care.
A SKILL.md file is a short text document, written mostly in plain English, that tells Claude how to handle a specific kind of task — and Claude reads it automatically, only when the task at hand actually calls for it.
A SKILL.md file is just a Markdown file — the same lightweight format a lot of blogs and notes apps use — with a small header at the top, written in YAML, a structured layout that looks a bit like an entry in a contact book:
---
name: weekly-report-writer
description: Drafts a weekly status report from a few rough notes.
Use when the user asks for a "weekly update", "status report", or
shares meeting notes asking for synthesis.
---
# How to handle this
1. Read the user's notes.
2. Group items by theme (shipped, in progress, blocked).
3. Output in this exact format...
The header — those two fields name and description — is the part Claude scans first. The body below it contains the actual instructions: how to do the work, in what order, with what voice, ending with what shape of output.
That's the whole thing. There is no compiled binary, no special tooling, no proprietary syntax. If you can write a memo, you can write a SKILL.md. Everything that follows is consequence.
Through most of 2024 and early 2025, large language models like Claude had a striking weakness: they could do almost anything in principle, but the user had to re-explain — every time — exactly how. If you wanted Claude to write a code review the way your team liked them, you'd paste the same instructions into every conversation. If you wanted it to draft a sales email in your brand's voice, same story. The instructions worked. The repetition was exhausting.
Anthropic's answer, introduced as part of an Agent Skills release in October 2025,[1] was structural. Rather than expect people to re-introduce themselves every session, Claude would learn to look in a known place — a folder on the user's machine, or on a shared team server — for these instruction packets, and load whichever one matched the task just typed. The instruction packets are SKILL.md files.
It is a small idea with disproportionate consequences. It means an organisation can write a single SKILL.md describing how it wants Claude to handle, say, expense reports — and every employee, every session, going forward, gets the same handling without re-explaining. It means a freelancer can pack up a useful procedure once and share it with the next freelancer. It means there is now something to share at all.
This is where the design becomes elegant. When you start a session with Claude, the model does not load every SKILL.md in your collection — that would be wasteful, and the relevant ones for most prompts would be a tiny fraction. Instead it reads only the description field of each one. Two or three sentences each. Then, when you type a prompt, Claude matches your intent against those descriptions and loads — into its working memory for just that conversation — the body of the one that fits.
The whole mechanism reads like an old-fashioned reference desk. You arrive with a question. The librarian does not hand you the entire library. She glances at the spines of the relevant books, picks the one that fits, opens it to the right chapter, and reads from there. The SKILL.md description is the spine.
This pattern has a name in Anthropic's documentation: progressive disclosure.[2] The skill stays compact when it is not needed and expands when it is. It is the kind of design that is invisible when it works and obvious in retrospect.
Within weeks of Agent Skills launching, two things became clear. First, the SKILL.md format is portable in the most generous sense — it is just a Markdown file, anyone can write one, and they spread the way any good document does. Second, no central marketplace appeared. Anthropic published a small catalog of officially-maintained skills on GitHub[3] — a few dozen reference implementations — but most authorship moved instantly to the community.
That has produced, by mid-2026, an ecosystem of roughly 69,000 publicly-indexed SKILL.md files scattered across GitHub.[4] There are skills for triaging customer-support tickets, for writing screenplay outlines, for managing Kubernetes deployments, for translating contracts into plain English, for analysing chess positions, for generating financial close checklists. ClaudSkills — the catalog this article sits inside — is the place where those scattered files are gathered, searchable, and ranked. We did not invent the format. We catalog what people are doing with it.
If your work involves repeated decisions with implicit standards — and most professional work does — SKILL.md is probably going to touch you. Three concrete ways:
The broader point is that the question "what can an AI do?" is being replaced by "what skills has it been given?" A SKILL.md is the unit of that giving.
If you have made it this far, you have the conceptual model. The next questions are practical ones, and we cover them in companion pieces:
You do not need to know how the engine of a car works to drive it well. But knowing that there is an engine — that is worth something. SKILL.md is the engine.
anthropics/skills — Anthropic's official open-source repository of reference SKILL.md files. https://github.com/anthropics/skillsSKILL.md file. See the methodology write-up: How I indexed 69,000 Claude Code skills.Have a clarification, correction, or topic to add? Email [email protected] or submit a PR via GitHub.
SKILL.md files, not affiliated with, endorsed by, or sponsored by Anthropic.