Most people who use AI every day do not know that there is now a standard file format for teaching a model a task once and having it done the same way every time after that. It is called a skill. It is a single Markdown file. Roughly 40 AI products already read it.
If your outputs feel inconsistent, if you keep pasting the same 400-word instruction block into a fresh chat, or if you have a "good prompt" saved in a Notes file that you keep forgetting to use, this is the thing you are missing. It takes about 20 minutes to write your first one.
What is an Agent Skill, and how is it different from a saved prompt?
An Agent Skill is a folder containing a SKILL.md file: a Markdown document with a short YAML header that tells an AI agent what the skill does and when to use it. Unlike a saved prompt, you do not paste it. The agent reads the header, decides the skill is relevant, and loads the instructions itself.
That difference matters more than it sounds. A saved prompt requires you to remember it exists, find it, and paste it in the right order. A skill sits in a folder and fires when the task matches.
Anthropic published Agent Skills as an open standard on 18 December 2025, with the specification hosted at agentskills.io. It was not kept proprietary, which is why the format spread quickly.
As of June 2026, roughly 40 products read the same format, including Claude, OpenAI Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI, Goose, OpenCode, Databricks Genie Code and Snowflake Cortex Code. One file, many tools. See the official skill authoring guidance for the canonical rules.
Why do your AI outputs drift, and how does a skill file fix it?
Outputs drift because the instruction changes every time you retype it. You compress a step, you drop a constraint you thought was obvious, you forget the example that made last week's output good. The model is consistent. Your input is not.
A skill file removes that variable. The instruction becomes a fixed artefact you edit deliberately rather than rewrite from memory.
It also fixes a second problem: the instruction stops living in your head. A colleague can use your skill and get your output, which is the difference between a personal trick and a team process.
There is some evidence this is worth doing well rather than doing casually. SkillsBench analysed 47,150 publicly shared skills and found an average quality score of 6.2 out of 12, while curated skills raised agent pass rates by an average of 16.2 percentage points. Treat that as directional, not as a controlled study, because the sample is scraped public files rather than a matched experiment. The direction still holds: a good skill helps measurably, a vague one does very little.
What goes inside a SKILL.md file?
A SKILL.md file has two parts: a YAML header between two lines of three dashes, and a Markdown body of instructions. The header must start at the very first byte of the file. Only two fields are required, name and description, and everything else is optional.
The permitted header keys are name, description, license, allowed-tools, metadata and compatibility. Runtimes that meet the spec ignore keys they do not recognise, so an unknown field is harmless rather than fatal.
The rules that actually trip people up:
--- name takes lowercase letters, numbers and hyphens only, caps at 64 characters, cannot start or end with a hyphen, and must match the parent folder name exactly. Mismatch it and the skill silently never loads.
--- description caps at 1,024 characters and must say both what the skill does and when to use it. This is the field the agent reads to decide whether to open your skill at all.
--- allowed-tools restricts which tools the agent may call while the skill is active. Claude Code and OpenClaw enforce it; several other agents accept the field and quietly ignore it, so do not treat it as a security boundary.
The body is where you write the actual method: the steps, the constraints, the format, the examples. Keep it lean. Skills are loaded through progressive disclosure: the name and description are injected into the system prompt on every run at almost no cost, and the full body is only loaded when the agent decides your skill applies. A common guideline is to keep the body under roughly 500 tokens and push long material into separate reference files the agent can open on demand.
How do you write your first Agent Skill in 20 minutes?
Pick the task you have explained to AI more than three times. Not your hardest task, your most repeated one. A weekly report format, a client email tone, a way of turning meeting notes into actions, a rewrite pass you always run on drafts.
Then create a folder named exactly like your skill and put one file in it. Here is a complete template you can copy and fill in:
Copy this into a file called SKILL.md
---
name: weekly-client-update
description: Turns raw notes from the week into a client-ready update email in our house format. Use whenever the user asks for a weekly update, client status email, or Friday summary, or pastes rough notes and asks to send them to a client.
---
# Weekly Client Update
## When to use this
The user has raw notes, bullet points or a meeting transcript and needs a client-facing update.
## Steps
1. Sort every item into Shipped, In progress, Blocked, or Needs a decision from the client.
2. Drop anything internal: staffing, tooling complaints, unconfirmed plans.
3. Write the email: one line of context, then the four sections as short bullets, then a single clear ask.
4. Keep it under 200 words. No adjectives about our own performance.
## Format
Subject line: [Client] weekly update, [date range]
Sign off with the sender's first name only.
## Do not
--- Do not invent dates or numbers. If a figure is missing, write TBC and flag it at the end.
--- Do not apologise for delays unless the notes say the delay was ours.
## Example of a good ask
"Can you confirm the landing page copy by Wednesday so we can keep the launch on 12 March?"
Now test it three times with three different sets of messy notes. Every time the output is wrong, do not correct the chat. Correct the file. That habit is the whole skill: your instructions get better permanently instead of temporarily.
If writing the file from scratch feels like work, hand the job to the model. Paste this:
Try this prompt
"I want to turn a task I repeat into an Agent Skill in SKILL.md format. Here is the task, described badly: [paste your rough description, plus one example of a good output and one example of a bad output].
Write the complete SKILL.md. Requirements: YAML frontmatter with only name and description; name in lowercase-hyphen form under 64 characters; description under 1,024 characters that states both what the skill does and the situations that should trigger it, using the words I would actually type. Body under 500 words with sections for When to use this, Steps, Format, and Do not. Extract the rules that are implicit in my good and bad examples and write them out explicitly. At the end, list the three assumptions you made that I should check."
Where does the skill file go, and which tools will read it?
A skill is a folder with SKILL.md inside it, placed in the skills directory your tool watches. In Claude Code and Cowork that is a skills folder in your project or your user configuration; in Cursor, Copilot, Codex and Gemini CLI the location differs slightly but the file format does not.
Because the format is a shared standard, the same folder can be reused across tools rather than rewritten per tool. Community collections such as VoltAgent's awesome-agent-skills index more than 1,000 skills built to work across Claude Code, Codex, Gemini CLI, Cursor and others.
The volume of available skills is now genuinely large. Directory sites index enormous catalogues, with SkillsMP alone listing roughly 1.9 million public skills scraped from GitHub. That is a reason to be selective, not impressed. Read any skill before you install it, because you are handing it your instructions and, in some setups, your tool access.
Skills also compose. Once you have three or four, an agent can chain them: research with one, draft with another, check against a third. That is the point at which this stops being a tidier prompt library and starts being a workflow, which is the same shift described in our guide to AI workflow automation.
What are the five mistakes that stop a skill from firing?
Skills fail quietly. There is no error message when a skill does not activate, so a broken skill looks identical to a skill you forgot to use. These are the five failures worth checking first.
--- A description written for humans, not for routing. "Best practices for client comms" tells the agent nothing about when to fire. Write the trigger conditions in the words you actually type.
--- A name that does not match the folder. The name field and the parent folder name must be identical. This is the single most common silent failure.
--- Frontmatter that does not start at byte 0. A blank line, a stray comment or a BOM before the first three dashes and the header is not parsed.
--- A body that has become a manual. Two thousand words of context loads slowly and buries the actual instruction. Keep the method in SKILL.md and move the background into reference files.
--- Trusting allowed-tools as a guardrail. It is enforced in some runtimes and ignored in others, so never rely on it to prevent an action you genuinely cannot allow.
One honest limitation to hold on to: a skill makes your instruction consistent, not your model. The same skill run on a different model, or on the same model after an update, can still produce different output. If reliability matters, pin the model you tested on and re-test after upgrades, the same discipline described in our note on prompting reasoning models.
Try it now: turn your most-repeated task into a skill
Open your AI chat history and find the instruction you have retyped most often this month. That is your first skill, and you already know it works, which is exactly why it is the right one to formalise.
Spend 20 minutes: write the SKILL.md, run it three times on real inputs, and edit the file rather than the chat every time the output misses. By the third run you will have something better than your best prompt, because it will contain the corrections you normally forget.
Then leave it alone for a week and use it. The value of a skill is not the day you write it. It is the fortieth time it saves you from re-explaining yourself.
This is the unglamorous part of getting good at AI: less prompt hunting, more building small durable pieces. We understand AI. We understand you better. With UD by your side, AI doesn't feel cold.
Reviewed by the UD AI team.
Turn One Skill Into a Working System
One skill fixes one task. A set of skills, connected to your real tools and data, changes how the work gets done. Now that you have the technique, the next step is building it into a workflow that runs reliably every time. We'll walk you through every step, from choosing the right tools to designing the workflow and putting it into daily use.
