Explainer · 5 min read
What are agent skills? A plain-English guide to SKILL.md
An agent skill is a folder that teaches an AI agent how to do one kind of job well. At its heart is a single text file called SKILL.md: a short description of when the skill applies, followed by instructions written the way you'd brief a capable colleague. Some skills also carry scripts, templates or reference documents. The agent doesn't read every skill all the time. It glances at the descriptions, and only opens a skill when your request matches one.
What's inside a skill
Open any skill folder and you'll usually find a SKILL.md file and, optionally, a few supporting files. SKILL.md starts with a small block of frontmatter (a few lines of metadata between two lines of dashes), then the instructions in ordinary Markdown.
A minimal SKILL.md
---
name: meeting-notes
description: Turn a raw meeting transcript into a short summary with decisions, owners and deadlines. Use when the user pastes a transcript or asks for meeting notes.
---
# Meeting notes
1. Read the whole transcript before writing anything.
2. List decisions first, then action items with an owner and a date.
3. Quote the transcript when a decision is ambiguous.
4. Keep the summary under one page.- name: a short identifier, usually matching the folder name.
- description: one or two sentences saying what the skill does and when to use it. This is the most important line in the file.
- The body: steps, rules, examples and pitfalls. Good skills read like a checklist written by someone who has done the job many times.
- Optional extras: scripts the agent can run, templates it can fill in, or longer reference files it reads only when needed.
How agents decide when to use a skill
When a session starts, the agent sees a compact list of the skills you have installed: just each name and description. That list is cheap, so you can install many skills without crowding the conversation. When you ask for something, the agent compares your request with those descriptions. If one fits, it reads the full SKILL.md and follows it, pulling in any extra files the instructions point to.
This is why the description matters so much. A vague description (“helps with writing”) means the skill is either ignored or used at the wrong moment. A specific one (“use when the user asks to rewrite landing-page copy for conversions”) gets picked up exactly when it should. You don't need a special command: you just ask for the task in your own words.
If a skill isn't being used, read its description and ask yourself whether your request clearly matches it. Naming the task the way the description does (“audit the SEO of this page”) usually does the trick.
Where skills live
| Where | Location | Good for |
|---|---|---|
| Claude Code, all projects | ~/.claude/skills/<skill-name>/ | Personal skills you want everywhere |
| Claude Code, one project | .claude/skills/<skill-name>/ inside the repo | Team skills that travel with the code |
| Claude apps (web and desktop) | Settings → Capabilities → Skills, then upload the ZIP | Using skills without a terminal |
Project skills are worth a special mention. Because they sit in the repository, everyone who clones the project gets the same skills, and changes to them go through code review like everything else. Other agents and tools are adopting the same folder-plus-SKILL.md format, so a well-written skill is increasingly portable.
Why skills matter
- Consistency: the agent follows the same proven steps every time instead of improvising.
- Less repetition: you stop pasting the same long prompt into every conversation.
- Shareable know-how: a team's best practice for code review, release notes or SEO audits becomes a file anyone can install.
- Small context cost: only the descriptions are loaded up front, so skills you aren't using don't get in the way.
A skill is different from a saved prompt in one useful way: you don't have to remember to use it. It's also different from a plugin or connector, which gives an agent access to a new system. A skill gives it a method. Many of the most useful skills simply encode discipline, such as writing a test before the code or finding the root cause before fixing a bug.
Test-Driven DevelopmentAgent skillA classic discipline skill: makes the agent write a failing test first.Agent skill · MITBrainstorming Before BuildingAgent skillGets the agent to clarify requirements before it builds anything.Agent skill · MIT
Copywriting AssistantAgent skillA marketing skill: shows skills aren't only for code.Agent skill · MIT
Skill CreatorAgent skillA skill for writing and improving other skills.Agent skill · MITSafety: read before you install
A skill is instructions plus, sometimes, code. When an agent follows a skill it may run the scripts inside it with the same permissions the agent has on your machine. That's what makes skills powerful, and it's also why you should treat a skill like any other software you download.
- Read SKILL.md from top to bottom. It's short, and it tells you exactly what the agent will be asked to do.
- Open every script in the folder. Look for network calls, file deletion, or anything that sends data somewhere you don't expect.
- Prefer skills from repositories you can inspect, with a clear licence and an active maintainer.
- Keep your agent's permission prompts switched on, especially for shell commands, until you trust a skill.
- Be wary of skills that ask the agent to ignore other instructions or hide what it is doing.
Every skill ZIP we offer is the original folder from its GitHub repository, packaged with its licence and an attribution note. We don't modify the contents, so the responsibility to review what it does is still yours.
Getting started
The easiest way to understand skills is to install one and watch it work. Pick something you do every week, such as code review or writing a content brief, install a matching skill, and ask for the task as you normally would. Then open the SKILL.md and compare its steps with what the agent did. You'll quickly see which skills earn their place, and you'll have a template for writing your own.
Put it into practice
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Written by the AI Tool Garage editors. Tool details link to their catalogue pages, which are refreshed weekly; spotted something out of date? Tell us.