What Is an Agent Skill, and How Is It Different From a Prompt?
An Agent Skill is a folder containing a SKILL.md file with instructions, plus optional templates and scripts, that an AI assistant loads automatically when your request matches its description. A prompt lives in one conversation. A Skill is installed once and applies itself every time it is relevant.
That is the whole idea, and it is why Skills matter more than another prompt-library bookmark. You stop being the person who remembers to paste the instructions.
Anthropic's own Agent Skills documentation describes them as "modular capabilities" built from three things: instructions, metadata, and optional resources. Nothing in that list requires you to write code.
The practical difference shows up on the tenth repeat. A saved prompt still needs you to find it, paste it, and remember which version was the good one. A Skill has one canonical location, and the assistant reads it on its own.
Why Does a Skill Beat a Saved Prompt for Repeat Work?
Because of progressive disclosure. A Skill loads in stages instead of dumping everything into the context window upfront. Only the name and description sit in context at all times, at roughly 100 tokens per Skill, so you can install many Skills without paying for any of them until one is actually triggered.
Anthropic's documentation sets out three loading levels, and understanding them is what separates people who write Skills that work from people who write 4,000-word mega-prompts:
--- Level 1: Metadata loads always, at startup. Around 100 tokens per Skill. This is just the name and description from the YAML frontmatter.
--- Level 2: Instructions load only when the Skill is triggered. Target under 5,000 tokens. This is the body of SKILL.md.
--- Level 3: Resources and code load only when referenced. Zero token cost until accessed. Extra markdown files, templates, reference data, scripts.
The Level 3 behaviour is the part most people miss. You can bundle a 40-page brand guideline, a full product catalogue, and six example outputs into a Skill, and none of it costs you context until the assistant actually needs one of those files.
Scripts are even better on this axis. When the assistant runs a bundled script, the script's code never enters the context window. Only its output does. That makes a 200-line formatting script cheaper than asking the model to generate equivalent logic on the fly, and more reliable, because the same code runs every time.
How Do You Create a Custom Skill Without Writing Code?
Write a plain text file named SKILL.md, put YAML frontmatter at the top with a name and a description, write your instructions below it in normal markdown, then zip the folder and upload it. On claude.ai that upload happens in Settings > Features. No terminal, no repository, no build step.
Pick a task you repeat weekly and already have opinions about. Client email replies. Weekly reporting format. Social captions in your brand voice. The best first Skill is a workflow where you already know what "wrong" looks like, because that knowledge is what you are encoding.
Here is a complete, copy-paste-ready starting point. Replace the bracketed parts and you have a working Skill:
Try this SKILL.md template:
---
name: weekly-client-report
description: Writes the weekly client status report in our house format. Use when the user asks for a weekly report, client update, status summary, or mentions reporting to a client.
---
# Weekly Client Report
## When to use this
Use whenever the user asks for a weekly client report or status update.
## Required structure
1. One-sentence headline: the single most important thing that happened.
2. "Shipped this week" section: 3 to 5 bullets, each starting with a past-tense verb.
3. "In progress" section: item, owner, expected date.
4. "Needs a decision from you" section: never more than 2 items. If there are none, write "Nothing blocked."
5. Close with next scheduled check-in date.
## Voice rules
Direct and short. No adjectives about our own work. Never write "we are excited to" or "we have been working hard on".
Numbers over adjectives: write "cut load time from 4.1s to 1.3s", not "significantly improved performance".
## Never do this
Do not invent metrics. If a number is missing, write "[number needed]" so the human fills it in.
Do not exceed 350 words total.
That is a real Skill. It is roughly 200 words, it contains no code, and it will produce a more consistent report than a prompt you retype from memory each Friday.
Notice what makes it work: it defines structure, it defines voice with a concrete before-and-after example, and it names the specific failure modes to avoid. Vague instructions produce vague output whether they live in a prompt or a Skill.
Where Can You Use Custom Skills, and What Do You Need to Enable?
Custom Skills work on claude.ai, in Claude Code, and through the Claude API, but each surface has its own upload path and its own requirements. On claude.ai you upload a zip through Settings > Features, available on Pro, Max, Team, and Enterprise plans, and it requires code execution to be enabled first.
The three paths, per Anthropic's documentation:
--- claude.ai uploads a zip through Settings > Features. Requires code execution enabled. Skills are individual to each user, not shared across an organisation.
--- Claude Code is filesystem-based with no upload at all. Drop the folder in ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
--- Claude API uploads through the /v1/skills endpoints, requires the code execution tool and the skills-2025-10-02 beta header, and shares Skills workspace-wide.
Four Skills come pre-built and need no setup at all: PowerPoint (pptx), Excel (xlsx), Word (docx), and PDF. If you have ever wondered why asking for a formatted spreadsheet sometimes produces a genuinely usable file, that is a pre-built Skill doing the work.
For a practitioner, the claude.ai route is the one that matters, and it is worth checking your plan before you spend an hour writing. Code execution has to be on, or the upload option will not behave as expected.
What Makes a Skill Actually Trigger?
The description field. It is the only part of your Skill the assistant sees before deciding whether to load it, and it must state both what the Skill does and when to use it. A description that only says what it does will sit unused while you wonder why nothing happens.
Compare these two. The first is what most people write. The second is what actually fires:
--- Weak: description: Helps with client reports.
--- Strong: description: Writes the weekly client status report in our house format. Use when the user asks for a weekly report, client update, status summary, or mentions reporting to a client.
The strong version lists the actual phrases you type. That is the mechanism: your request is matched against the description, so the description should contain your vocabulary, not a tidy abstract summary of the Skill.
There are hard limits worth knowing before you name anything. The name field allows a maximum of 64 characters, lowercase letters, numbers and hyphens only, and it cannot contain the reserved words "anthropic" or "claude". The description allows up to 1,024 characters. Neither field may contain XML tags.
Use the description budget. 1,024 characters is room for a dozen trigger phrases, and every extra phrase is another way for the Skill to catch a request you phrased differently on a Tuesday.
What Are the Gotchas Nobody Mentions?
Custom Skills do not sync across surfaces. A Skill you upload to claude.ai is not available through the API, a Skill uploaded through the API is not available on claude.ai, and Claude Code Skills are separate from both. You maintain each surface yourself, which means version drift is a real risk.
Three more constraints that change how you plan a Skill:
--- On claude.ai, custom Skills are per-user. Each team member uploads their own copy, and there is no centralised admin distribution. A "team standard" Skill is a file you send around, not a setting someone switches on.
--- On the Claude API, Skills run in a sandboxed container with no network access and no runtime package installation. A Skill that needs to call an external service will not work there.
--- In Claude Code, Skills have the same network and filesystem access as any program on your computer. That is powerful and it is exactly why the next point matters.
Treat installing a Skill like installing software. Anthropic's documentation is unusually blunt about this: use Skills only from sources you created yourself or obtained from Anthropic, because a malicious Skill can direct the assistant to invoke tools or execute code in ways that do not match its stated purpose. Skills that fetch data from external URLs carry particular risk, since fetched content can carry instructions of its own.
The audit is not complicated. Open every file in the folder, including scripts, and look for anything that does not match what the Skill claims to do. Unexpected network calls and odd file access are the signals.
One honest limitation on the technique itself: a Skill will not rescue a workflow you have not thought through. Writing a Skill forces you to specify structure, voice, and failure modes explicitly. If you cannot describe what "good" looks like for a task, the Skill will be as vague as your prompts were, and you will have added a file for nothing.
How Do You Test This in the Next 20 Minutes?
Take the last three times you pasted the same block of instructions into a chat. Open those conversations, copy what you pasted, and consolidate it into one SKILL.md using the template above. Then run the same request without pasting anything and compare the output.
Run it as five concrete steps:
--- Minutes 0 to 5: Find your three repeat instruction blocks. Note the phrases you actually typed when you asked for the task.
--- Minutes 5 to 12: Write SKILL.md. Name, description with those exact phrases, structure rules, voice rules, and a "never do this" section.
--- Minutes 12 to 15: Zip the folder and upload it through Settings > Features, with code execution enabled.
--- Minutes 15 to 18: Make the request in a fresh conversation using your natural wording. Paste nothing.
--- Minutes 18 to 20: If it did not trigger, add three more phrasings to the description. That is almost always the fix.
The failure mode to expect on the first attempt is a Skill that never fires. It is nearly always the description, not the instructions. Broaden the trigger phrases before you touch anything else.
Once one Skill works, the second takes ten minutes. The compounding is the point: every recurring task you encode is a task you stop re-explaining, and the instructions get better each time you notice an output you did not want.
If you want to go further, a Skill pairs naturally with two things we have covered before: setting up AI memory properly so the assistant holds your standing context, and connecting MCP servers so it can reach the tools your work actually lives in. Skills tell it how to work. Memory tells it who you are. MCP tells it where the data is.
The Takeaway
Skills move your expertise out of your head and out of your clipboard, into a file the assistant reads on its own. The technical requirement is one markdown file. The real requirement is being specific about what good work looks like.
That second part is the work nobody can do for you, and it is also where the leverage is. Every hour spent writing down how you want a task done is an hour you never spend explaining it again.
We understand AI. We understand you better. With UD by your side, AI doesn't feel cold. Twenty-eight years of helping Hong Kong teams turn technology into something that actually works on a Monday morning.
Turn One Skill Into a Working System
One Skill saves you an hour a week. A connected set of them changes how your whole team works. UD helps you go from a single SKILL.md file to a reliable AI workflow, and we'll walk you through every step, from choosing which tasks to encode, to tool setup, to deployment across your team.
Reviewed by the UD AI team. Facts in this article were verified against Anthropic's Agent Skills documentation as published on 3 August 2026. Product behaviour and plan requirements change; check the official documentation before relying on a specific setting.
