Most people using Claude, ChatGPT or Cursor every day have never written an Agent Skill, and assume it requires code. It does not. An Agent Skill is a Markdown file. If you can write a decent onboarding document for a new colleague, you can write one this afternoon.
This matters because skills solve the single most annoying problem intermediate AI users have: repeating the same setup instructions in every new chat. You paste your brand voice rules, your report format, your client naming conventions, again and again. A skill turns that repetition into a file the agent loads by itself, only when it is relevant.
What is an Agent Skill?
An Agent Skill is a folder containing a single SKILL.md file: YAML frontmatter with a name and a description, followed by a Markdown body of step-by-step instructions. The agent reads the description to decide when the skill is relevant, then loads the body only at that moment. Optional scripts and reference files can sit alongside it.
Anthropic released the SKILL.md format in October 2025 and documents it in the Agent Skills overview. It has since been adopted beyond Claude, which means a skill you write once can be reused across several agent tools without conversion.
The practical difference from a saved prompt is triggering. A saved prompt sits in a document until you remember to paste it. A skill is discovered by the agent from its description and pulled in automatically when the task matches.
The practical difference from a custom GPT or a Project is portability and scope. A Project applies its instructions to everything inside it. A skill applies only to the tasks it describes, so you can have thirty of them installed and only the relevant one loads.
How does progressive disclosure work, and why does it matter for your context window?
Progressive disclosure means the agent sees skill names and descriptions at startup, loads the full SKILL.md body only when a skill becomes relevant, and opens deeper reference files only when it needs that specific detail. This keeps thirty installed skills from consuming your context window before you have typed anything.
The three tiers work like this:
--- Tier 1, discovery. Only the YAML name and description are in context at all times. The cost is roughly 80 tokens per skill, so twenty skills cost you about 1,600 tokens of standing overhead.
--- Tier 2, activation. When the agent judges the skill relevant, the full Markdown body loads. Bodies typically range from around 275 tokens for a tight skill up to roughly 8,000 tokens for a heavy one.
--- Tier 3, reference. Files linked from the body, such as a style guide or a data schema, load only when the agent actually needs them.
This is why the Claude skill authoring guidance recommends keeping the SKILL.md body under 500 lines. Past that, you are paying activation cost for instructions the agent may not need. Split the overflow into reference files.
The takeaway for your own writing: put decisions in the body, put lookup material in reference files. A checklist belongs in the body. A 40-page brand manual does not.
How do you write the description field so the skill actually fires?
The description is the trigger, not documentation. It must state both what the skill does and when to use it, in under 1,024 characters. A vague description is the single most common reason a skill never fires, because the agent matches your request against this text and nothing else.
Write it as a matching surface, not a summary. Include the concrete nouns and phrasings you actually type.
Weak description that will not fire:
--- description: Helps with writing tasks.
Nothing here tells the agent which writing tasks, so it competes with every other writing-adjacent skill and usually loses.
Strong description that will fire:
--- description: Draft and edit LinkedIn posts in the company voice. Use when the user asks to write a LinkedIn post, turn an article into a post, rewrite a draft for LinkedIn, or mentions "LinkedIn", "social post", "thought leadership post". Covers hook, body structure, and hashtag rules.
Three habits make the difference. Name the artefact ("LinkedIn post", not "content"). List the trigger phrases in the words you use, including the sloppy ones. State the boundary, so the agent knows what the skill does not cover.
One caution worth knowing: a description that is too broad is as bad as one that is too vague. If your description says "use for any content task", it will hijack requests it cannot handle well.
What goes in the SKILL.md body? A copy-paste template
The body is the procedure the agent follows once the skill loads. Effective bodies share four parts: when to use and when not to use, the inputs needed, the numbered steps, and a quality checklist. Write it as instructions to a competent new hire, not as a description of a process.
Here is a complete skill you can copy, rename and adapt in about fifteen minutes.
Try this: save as .claude/skills/meeting-notes/SKILL.md
---
name: meeting-notes
description: Turn a raw meeting transcript or rough notes into a structured summary with decisions, owners and deadlines. Use when the user pastes a transcript, uploads meeting notes, or asks to "summarise the meeting", "write up the call", "pull the action items", or "what did we decide". Produces a fixed 4-section format.
---
# Meeting Notes
## When to use
Use when the input is a transcript, recording summary or rough notes from a real meeting.
Do NOT use for drafting an agenda before a meeting, or for one-to-one performance conversations.
## Inputs required
- The transcript or notes.
- If missing, ask once: who attended, and what was the meeting for?
## Steps
1. Read the whole input before writing anything.
2. Produce exactly four sections: Decisions, Action items, Open questions, Context.
3. Decisions: one line each, past tense, no hedging. Only what was actually agreed.
4. Action items: format as "Owner - task - deadline". If no owner was named, write "UNASSIGNED" rather than guessing.
5. Open questions: anything raised and left unresolved.
6. Context: maximum 3 sentences, for someone who missed the meeting.
## Quality checklist
- Every action item has an owner field, even if UNASSIGNED.
- No invented deadlines. If a date was not stated, write "no date set".
- Total output under 400 words.
Notice what the body does not contain: no explanation of what a meeting is, no motivational preamble, no "you are a helpful assistant". Every line is either a rule or a constraint.
Notice also the two guardrails against the most common failure mode. "UNASSIGNED rather than guessing" and "no invented deadlines" exist because summarisation models fill gaps confidently. Write your guardrails as explicit instructions, not hopes.
How do you install and test a skill without writing code?
Drop the folder into .claude/skills/ for a single project, or ~/.claude/skills/ to make it available everywhere. No build step, no terminal command, no package to install. Then test by phrasing a request the way you normally would and checking whether the skill loads.
Testing is the step most people skip, and it is where skills quietly fail. Run these three checks.
--- The trigger test. Type three different natural phrasings of the same request. If the skill fires on only one of them, your description is missing the vocabulary you actually use. Add the missing phrasings.
--- The false-positive test. Type an adjacent request the skill should not handle. For the meeting-notes example, try "draft an agenda for tomorrow's call". If the skill fires, your description is too broad. Tighten the "Do NOT use" line.
--- The output test. Run it on three genuinely different inputs, including a messy one. A skill that only works on clean input is a demo, not a tool.
Iterate on the description first when triggering is wrong, and on the body only when the output is wrong. Mixing the two is how people end up with a 300-line skill that still does not fire.
Where do Agent Skills break down?
Skills fail in four predictable ways: descriptions that are too vague to trigger, bodies bloated past 500 lines, overlapping skills that compete for the same request, and instructions that assume context the agent does not have. None of these are model limitations. All four are authoring problems you can fix.
Overlap is the one that surprises people. Once you have eight or nine skills, two of them will describe similar territory and the agent will pick inconsistently. The fix is boundary lines in every description: state what the skill excludes, and name the sibling skill that handles it.
Skills do not make a weak model strong. A skill supplies procedure and constraints. It does not add capability. If the underlying model cannot reliably do the task in a well-written one-off prompt, packaging it as a skill will not change that.
Skills also do not guarantee determinism. The same skill on the same input will not produce byte-identical output every run. If you need exact reproducibility, such as a fixed table structure, specify the structure explicitly in the body and add it to the quality checklist. That gets you close, not to zero variance.
One security habit worth adopting: a skill is executable instruction text. Read any skill you download from a public directory before installing it, the same way you would read a browser extension's permissions.
Try it now: your first skill in 20 minutes
Pick the instruction block you have pasted into a chat most often in the last month. That is your first skill. The whole exercise takes about 20 minutes and the payoff compounds every time you skip the paste.
Use this prompt to get a first draft, then edit it yourself. Do not ship the draft unedited, because the model does not know your real trigger vocabulary.
Copy-paste prompt:
I want to turn a repeated instruction set into an Agent Skill in SKILL.md format.
Here is what I paste into chat every time:
[PASTE YOUR USUAL INSTRUCTIONS]
Here are three ways I actually phrase the request:
1. [PHRASING 1]
2. [PHRASING 2]
3. [PHRASING 3]
Write a complete SKILL.md with:
- YAML frontmatter: name (kebab-case) and description under 1024 characters that states what it does AND when to use it, incorporating my three phrasings verbatim.
- A body under 150 lines with these sections: When to use / Do NOT use, Inputs required, Steps (numbered), Quality checklist.
- At least two explicit guardrails against the model inventing information.
Then list three adjacent requests that should NOT trigger this skill, so I can test for false positives.
Save the output, install it, and run the three tests. Then write your second skill. The second one takes ten minutes.
If the repeated task you picked involves moving data between apps rather than shaping text, a skill may be the wrong container for it. Our breakdown of Zapier, Make and n8n covers where a no-code automation platform is the better fit.
The takeaway
The gap between someone who uses AI well and someone who uses it very well is rarely prompt cleverness. It is whether their good instructions live in a file the agent can find, or in a scratchpad they keep re-pasting.
Agent Skills close that gap with plain Markdown. Write the description as a trigger, keep the body under 500 lines, test for false positives, and be honest that a skill supplies procedure rather than capability.
That last point is the one worth holding onto. Tools should reduce the number of things you have to remember, not add to them. 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
Writing your first skill is the easy part. Making a whole team's work run on skills, connected to your real tools and data, is where most people stall. We'll walk you through every step, from mapping which tasks are worth packaging to configuring, testing and deploying them.
