What are Agent Skills? SKILL.md explained for beginners

1. 1

   What problem do skills solve?

   A general AI agent is smart but does not know your way of doing things: your report format, your company’s brand rules, the exact steps to fill a tricky form. You could paste those instructions into every chat, but that is tiring, and long instructions crowd the model’s context window (its working memory).

   On 16 October 2025, Anthropic introduced Agent Skills. Its engineering team compares a skill to an onboarding guide for a new hire: a packet of instructions, scripts and resources that an agent can find and load when a task needs it. You write the guide once, and the agent opens it only when it is relevant.

   Key idea

   A skill teaches an agent how to do one kind of task, and it is loaded only when that task comes up.

2. 2

   What is inside a skill?

   A skill is just a folder. The only required file is SKILL.md, a Markdown text file. It starts with a short header in YAML (a simple "key: value" format) that the spec calls frontmatter, followed by plain instructions.

   The open spec at agentskills.io sets two required fields. name: up to 64 characters, lowercase letters, numbers and hyphens, and it must match the folder name. description: up to 1,024 characters, saying what the skill does and when to use it. Everything else is optional.

   pdf-processing/
   ├── SKILL.md       # required: name, description, instructions
   ├── scripts/       # optional: code the agent can run
   ├── references/    # optional: longer docs, read when needed
   └── assets/        # optional: templates, images, data

3. 3

   How does an agent load a skill? (progressive disclosure)

   Skills load in layers, which Anthropic calls progressive disclosure. At startup the agent reads only each skill’s name and description, about 100 tokens per skill according to the spec. When your request matches a description, the agent reads the full SKILL.md. Only if the instructions point to another file, or to a script, does the agent open or run that too.

   This is why you can install dozens of skills without slowing the agent down. Anthropic notes that scripts help in a second way: code like sorting or extracting form fields gives the same result every time, and the agent can run a script without reading the whole script into its context.

   1. Startup: names and descriptions only↓→
   2. Your task matches a description↓→
   3. Agent reads full SKILL.md↓→
   4. Opens extra files or runs scripts only if needed↓→
   5. Does the task

   Key idea

   The description is the trigger. If it is vague, the agent will not know when to use the skill.

4. 4

   Skills vs prompts vs MCP vs subagents: what is the difference?

   These four get mixed up because they all change what an agent does. Anthropic’s "Skills explained" post (March 2026) separates them like this:

   • Prompt: what you type in one chat. It is gone when the chat ends.
   • Skill: a saved "how to do this task" package that loads itself when relevant, in any chat.
   • MCP: a connection to outside tools and data, like GitHub or a database. In Anthropic’s words, "MCP connects Claude to data; Skills teach Claude what to do with that data."
   • Subagent: a separate helper with its own context window and tool permissions, for handing off a whole job.

   Key idea

   MCP gives the agent hands; a skill gives it a recipe.

5. 5

   How do you write your first SKILL.md?

   Make a folder with a lowercase, hyphenated name and put one SKILL.md inside. Write the description as "what it does + when to use it", using words a user would actually type. Keep the instructions short and numbered. The spec suggests keeping SKILL.md under 500 lines and moving long reference material into separate files.

   In Claude Code, put the folder at ~/.claude/skills/interview-answer-coach/ for all your projects, or .claude/skills/ inside one project to share it with your team. Claude uses it when your request matches, or you can call it directly by typing /interview-answer-coach.

   ---
   name: interview-answer-coach
   description: Rewrites a job interview answer in STAR format (Situation, Task, Action, Result). Use when the user pastes an interview answer or asks how to answer a behavioral question.
   ---
   
   # Interview answer coach
   
   1. Read the question and the user’s answer.
   2. Rewrite it in STAR order, 120 to 180 words, first person.
   3. Keep every fact the user gave. Never invent numbers; write [add a number].
   4. End with one line naming the strongest result.

6. 6

   Who supports skills, and are they safe?

   On 18 December 2025, Anthropic published Agent Skills as an open standard, now documented at agentskills.io, which says the format "was originally developed by Anthropic" and is open to contributions. As of Nov 2026, the official docs of these tools say they read SKILL.md folders: Claude apps, Claude Code and the Claude API; Cursor; Gemini CLI; GitHub Copilot in VS Code; and OpenAI Codex. In Claude’s apps, the help center lists Skills for Pro, Max, Team and Enterprise plans.

   Skills can contain code, so treat them like software you install. Anthropic warns that a harmful skill could tell the agent to leak data or take actions you did not want.

   • Install skills only from sources you trust.
   • Before using someone else’s skill, read SKILL.md and every script in it.
   • Be wary of instructions that send data to unknown websites.

From the people who built it

Straight from the source

The original idea, then the same idea taken apart, then how you use it today.

Anthropic Engineering team

The team that created Agent Skills for Claude

Equipping agents for the real world with Agent Skills (engineering post, October 2025)

1 · Understand

General agents need specific know-how, so package it like an onboarding guide: a folder the agent discovers by its name and description and opens only when a task calls for it.

2 · Break it down

• Level 1: name and description always loaded, so the agent knows when a skill applies.
• Level 2: the full SKILL.md is read only when the skill is relevant.
• Level 3: extra files and scripts are opened or run only if needed, so a skill can hold a lot without filling the context.
• Code inside a skill gives repeatable results for jobs like sorting or extracting form fields.

3 · Use it

Start by noticing where an agent keeps getting your task wrong, then write a small skill for just that task and refine it as you watch the agent use it.

Agent Skills open standard

The open format, originally developed by Anthropic, now used by many agent tools

Agent Skills overview and specification (agentskills.io)

1 · Understand

A skill is "a folder containing a SKILL.md file" with a name, a description and instructions, so the same skill works in any compatible agent.

2 · Break it down

• Only two fields are required: name and description.
• The description should say what the skill does and when to use it, with words users actually type.
• Keep SKILL.md short and move long material into references/ files one level deep.

3 · Use it

Write your skill once to the open spec, and you can use the same folder in Claude Code, Cursor, Gemini CLI or Copilot instead of rewriting it for each tool.

5 terms

Words to know

Agent Skill

A folder with a SKILL.md file (and optional scripts and references) that teaches an agent how to do one kind of task.

SKILL.md

The required file in a skill: a short header with name and description, then plain Markdown instructions.

Frontmatter

The header between two --- lines at the top of SKILL.md, written in YAML "key: value" style.

Progressive disclosure

Loading information in layers: names and descriptions first, full instructions only when needed, extra files only if asked for.

Context window

The amount of text a model can keep in view at once. Skills save space in it by loading only when relevant.

2 videos · plays here

Watch

Hand-picked from the people who explain this best. The video loads only when you press play.

Hands-on · 10 minutes or less

Try it

Write and test your own interview-coach skill

1. 1Create a folder named interview-answer-coach and, inside it, a plain text file named SKILL.md.
2. 2Copy the example from step 5 into SKILL.md. Change the description so it uses the words you would type.
3. 3If you use Claude Code, move the folder to ~/.claude/skills/. In Cursor or VS Code with GitHub Copilot, put it in .agents/skills/ inside a project. In Gemini CLI, follow its skills page.
4. 4Start a new session and paste a rough interview answer without naming the skill. Check whether the agent picks it up on its own; if not, make the description more specific.
5. 5No agent installed? Paste SKILL.md into any free chatbot and say "follow these instructions for my next message". You lose the automatic loading, but you can test and improve the instructions.

Agent Skills quickstart (agentskills.io)

3 questions · instant feedback

Check yourself

Pick an answer to see if you are right, and why.

Question 1

Question 1 of 3

What does an agent read about every installed skill at startup?

AThe whole SKILL.md and all scriptsBOnly the name and descriptionCNothing until you type the skill’s nameDOnly the scripts folder

Question 2

Question 2 of 3

You want the agent to follow your team’s 8-step code review checklist whenever someone asks for a review. What fits best?

AAn MCP serverBA skillCA longer prompt in each chatDA bigger model

Question 3

Question 3 of 3

Which skill name follows the Agent Skills spec?

AInterview_CoachBinterview-coachC-interview-coachDinterview--coach

Lesson 22 of 36

Done? Keep going

Mark this lesson complete to keep your place. Progress is saved on this device, no login.

Mark lesson complete

Up next · Lesson 23 · 13 minSubagents and multi-agent systemsA multi-agent system splits one big job across several AI agents. Usually a lead agent (the orchestrator) plans the work, sends pieces to helper agents (subagents or workers), each with its own fresh context, and combines what they return. It helps most when the pieces can run in parallel, like broad research, and it hurts when the pieces depend on each other, because it costs many more tokens and the agents can miss each other’s decisions.← Previous: What is an AI agent?

People also ask

Questions people ask

What is the difference between Agent Skills and MCP?+

MCP connects an AI app to outside tools and data, such as GitHub, Google Drive or a database. A skill is a folder of instructions (and sometimes scripts) that teaches the agent how to do a task. They work together: MCP gives access, the skill says what to do with it.

Are Agent Skills only for Claude?+

No. Anthropic created the format and published it as an open standard at agentskills.io in December 2025. As of Nov 2026, Cursor, Gemini CLI, GitHub Copilot in VS Code and OpenAI Codex also read SKILL.md folders.

Do I need to know how to code to write a skill?+

No. A basic skill is a text file with a name, a description and numbered instructions in plain English. Scripts are optional and only help when a step should run the same way every time.

11 sources · checked Nov 2026

Sources and further reading

• Anthropic Engineering: Equipping agents for the real world with Agent Skills (Oct 2025, updated Dec 2025)
• Claude blog: Introducing Agent Skills (Oct 2025)
• Claude blog: Skills explained (Mar 2026)
• Agent Skills: overview (agentskills.io)
• Agent Skills: specification
• Claude Code docs: Skills
• Claude Help Center: Using Skills in Claude
• VS Code docs: Agent Skills in GitHub Copilot
• Gemini CLI docs: Agent Skills
• Cursor docs: Agent Skills
• OpenAI: Skills catalog for Codex (GitHub)

Related on this site

Previous: What is an AI agent?Next: Subagents and multi-agent systemsWhat is MCP?Context engineeringClaude Code for beginnersAI engineer career guideFree AI skills resources