What Is an Agent Skill, and Why Is Everyone Suddenly Writing One?
An Agent Skill is a folder containing a single Markdown file called SKILL.md. It holds a name, a description, and plain instructions telling an AI assistant how to do one specific job. No code. No API. The same file works across more than 30 AI tools.
Anthropic published the Agent Skills specification on 18 December 2025. Within 48 hours, OpenAI and Microsoft had shipped support for it.
That speed is the interesting part. Competing companies almost never agree on a file format this fast. They agreed because the problem was universal: everyone had prompts they retyped every single day, and no way to carry them between tools.
If you have ever pasted the same 400-word briefing into ChatGPT for the fifth time this week, you already understand the problem a Skill solves. You are doing manually what a file should be doing for you.
What Does a Skill Do That a Saved Prompt Does Not?
A saved prompt waits for you to fetch it. A Skill loads itself. The assistant reads the description field, decides the current request matches, and pulls in the instructions on its own. You never have to remember it exists, which is exactly why it gets used.
This is the difference between a recipe card in a drawer and a chef who already knows the dish.
The second difference is portability. A prompt saved in ChatGPT's custom instructions is trapped in ChatGPT. A SKILL.md file written for Claude runs unchanged in OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Goose, and roughly 40 products listed on the agentskills.io showcase as of June 2026.
The third difference is that a Skill can be handed to someone else. A prompt lives in your account. A folder lives in a shared drive, a repository, or a Slack message. Your colleague drops it in and gets your exact workflow.
Why Does the Description Field Matter More Than the Instructions?
The description is the only part the assistant reads before deciding whether to load your Skill. If it does not match how you actually phrase requests, the Skill never fires and the instructions are never seen. When a Skill fails, it is almost always the description, not the body.
Most first attempts describe what the author thinks the Skill is about, in the author's own vocabulary.
A weak description: "Content guidelines for our team." Nobody types that. It matches nothing.
A working description follows a two-part shape: what it does, then a "Use when" clause listing the actual trigger words a real person uses.
--- What it does, in one sentence, using concrete nouns
--- "Use when" plus 5 to 10 phrases you genuinely type, including the sloppy ones
--- Under 1,024 characters, which is the spec limit
The official specification's own example is deliberately blunt: "Extract PDF text, fill forms, merge files. Use when handling PDFs." That is the register you want. Not marketing copy. Routing instructions.
Write the description last, after the body exists. You will know by then what the Skill genuinely covers, which is usually narrower than you first imagined.
How Do You Write Your First Agent Skill in 20 Minutes?
Pick the one task you re-explain most often, write the instructions as if briefing a competent new hire, and save it as SKILL.md inside a folder named after the skill. Two frontmatter fields are required: name and description. Everything else in the specification is optional.
Here is a complete, working Skill you can copy, rename, and edit today. It is a real one: a weekly client update that most account managers rewrite from scratch every Friday.
Copy this into a file called SKILL.md
---
name: weekly-client-update
description: Draft the Friday client status update from raw notes. Use when writing a weekly update, client status email, Friday report, progress summary, or when the user pastes messy meeting notes and asks for a client-ready version.
---
# Weekly Client Update
Turn raw notes into a client-ready update. Never invent a status, a date, or a number that is not in the notes.
## Structure, in this exact order
1. One-line headline: the single most important thing that happened this week.
2. Shipped: what is now done and visible to the client. Bullet points, past tense.
3. In progress: what is moving, plus the expected finish date. If a date is missing from my notes, write TBC and flag it at the end.
4. Blocked: what needs a decision from the client. Name the decision and the deadline.
5. Next week: three items maximum.
## Rules
- Maximum 200 words total.
- No adjectives like "great", "exciting", or "significant".
- Never write "we are working on it" without naming what happens next and when.
- If something slipped, say so in the first two lines. Do not bury it.
- End with a section called MISSING listing anything you had to mark TBC.
## Before you finish
Re-read the draft and delete any sentence that would survive being cut without losing information.
Where to put it
Two conventions cover most cases. A folder at the account level makes the Skill available everywhere you work. A folder inside a specific project makes it available only in that project, which is what you want for client-specific rules. In Claude Code and most compatible tools, those locations are the personal skills folder and the project skills folder respectively.
If you use a desktop AI app rather than a terminal, look for the Skills or Capabilities panel in settings. The file format is identical either way.
Which AI Tools Actually Support Agent Skills in 2026?
As of March 2026, 32 tools supported the specification, and by June 2026 roughly 40 products appeared on the agentskills.io showcase. The list spans Anthropic, OpenAI, Microsoft, Google, JetBrains, AWS, Databricks, Snowflake, ByteDance and Mistral AI.
Named support includes Claude and Claude Code, OpenAI Codex CLI, GitHub Copilot and VS Code, Cursor, Gemini CLI, Block's Goose, AWS Kiro, Sourcegraph Amp, and JetBrains Junie.
Be honest with yourself about that list, because it matters for which Skill you write first. A large share of those 40 products are developer tools that live in a terminal or an IDE. If your day is spreadsheets, decks and email, the surfaces that matter to you are the desktop and web assistants, not the CLIs.
Two further milestones show the ecosystem is real rather than announced. Vercel launched skills.sh, a marketplace with command-line installation, on 20 January 2026. AWS shipped Agent Skills support in its Kiro IDE on 5 February 2026.
The practical takeaway is that portability now has actual value. A Skill you write this month is unlikely to be stranded when you switch assistants next year, and that was not true of any prompt library you have built so far.
Where Do Agent Skills Break Down?
Skills fail in four predictable ways: the description does not match real phrasing, the Skill tries to cover too many jobs, the instructions are long enough to crowd out the actual task, and nobody checks whether the Skill fired at all. All four are fixable in minutes once you know to look.
One Skill, one job
A Skill called "marketing" that covers social posts, email, SEO briefs and ad copy will trigger constantly and help with none of them. Four narrow Skills beat one broad one every time, because the description can be precise about each.
Length is not quality
The instructions occupy part of the context window that would otherwise hold your actual document. Keep SKILL.md lean and push reference material into companion files that load only when needed. If your Skill is 3,000 words of preamble before the first instruction, cut it.
Silent non-firing
This is the one that wastes weeks. You assume the Skill is working, the output looks plausible, and the Skill never loaded. Ask directly: "Which skills did you use for that answer?" If the answer is none, your description is the problem.
Skills do not check facts
A Skill shapes output. It does not verify it. A Skill that says "never invent a number" reduces invented numbers; it does not eliminate them. Every claim still needs your eyes on it, particularly prices, dates and names. The same discipline applies here as with any AI-generated draft, which is why grounding your AI in real source documents remains a separate and necessary step.
How Do You Test a Skill Before You Trust It?
Run the trigger test and the blind test. The trigger test checks whether the Skill loads from phrasing you did not design for. The blind test checks whether the output is genuinely better than what you get without it. Both take under ten minutes and catch nearly every problem.
Try this now
Open your assistant and paste this, replacing the bracketed part with your own Skill's job:
I have a skill installed for [drafting weekly client updates]. I am going to give you five different ways a real colleague might ask for this. For each one, answer only YES or NO: would you load that skill for this request? Do not explain, do not soften your answer, and do not tell me the descriptions look fine.
1. "can you sort out the friday thing for Acme"
2. "client wants a progress note by 5pm"
3. "here are my notes from the call, make it presentable"
4. "draft the weekly"
5. "what did we ship this week"
Then list every trigger phrase from these five that is missing from my skill description.
The forced binary answer is what makes this work. Ask an assistant to "review my description" and you get reassurance. Force it to commit to YES or NO on each specific phrasing and you get the gaps.
Then run the blind test. Same input, once with the Skill and once with it removed. If you cannot tell the two apart, your instructions are describing what a competent assistant already does by default, and the Skill is not earning its place.
What Should You Build This Week?
Start with the task you have explained more than three times, not the most impressive one. Skills earn their value through repetition, so the boring recurring job pays back faster than the ambitious one. One narrow Skill, tested properly, beats a library of ten that never fire.
Candidates worth ten minutes each: the client update, the format your finance team insists on for expense notes, the exact tone your CEO wants in internal announcements, the checklist you apply before publishing anything externally.
None of these are glamorous. All of them are the things you currently re-explain, and every re-explanation is a small tax you pay for not having written the file.
The format is deliberately simple because it has to be readable by people who do not write software. That is the quiet significance of Agent Skills: for the first time, the thing that configures an AI tool is a document, and documents are something you already know how to write.
We understand AI. We understand you better. With UD by your side, AI doesn't feel cold. Knowing the format is the easy half; building it into how your team actually works is where most people stall, and that is the part nobody should have to figure out alone.
Turn One Skill into a Working System
Writing your first SKILL.md takes twenty minutes. Turning a handful of them into a workflow your whole team relies on is a different job. UD has spent 28 years helping Hong Kong businesses make technology stick, and we'll walk you through every step, from choosing which tasks to package, to testing that they fire reliably, to deploying them across your team.
Reviewed by the UD AI team.
