AI for UX · Labs · 4 min read
Build your first skill
A hands-on lab: turn a task you repeat into an AI skill, a small folder of instructions that Claude, ChatGPT, Copilot, Cursor and other tools can load. Write it, test it by hand, install it, check it on past work, and improve it.
If you've written the same prompt three times, it's time for a skill. A skill is a folder with one instruction file,
SKILL.md, that tells an AI tool how to do one kind of task: the steps, the output and the rules. Since December 2025 it has been an open format, Agent Skills, so the same folder works in several tools. You don't need to code to write one: it's a short, precise document, the kind designers write all the time.
What you'll be able to do after this lab:
- Choose a task that deserves a skill
- Write a
SKILL.mdwith a description, steps, output and rules - Install it in the tool you use
- Check it against past work and improve it
Products and paths are as of November 2026. For the concepts (skills, sub-agents, connectors, plugins), see UX agents and skills: a guide for designers.
1. The lab in five steps
- 1Choose
A frequent task with an agreed "right way".
- 2Write
Description, steps, output, rules.
- 3Test by hand
A colleague follows it without asking you.
- 4Install
In the tool you use.
- 5Check
Five past cases; change one thing; repeat.
2. Choose the task
A good first skill is a task that is frequent, has a "right way" your team already agrees on, and produces a text output you can check. For example:
- Rewrite technical error messages into your product's microcopy pattern.
- Turn rough meeting notes into a decision log entry.
- Check a screen description against your accessibility checklist.
Avoid, for a first skill: anything that posts, publishes or deletes, and anything with personal or confidential data.
3. Write SKILL.md
The file starts with two required fields, then plain instructions:
---
name: error-microcopy
description: Rewrite technical error messages into our three-line microcopy
pattern (title, message, action). Use when someone pastes an error code,
a stack trace or a raw system message and asks for user-facing copy.
---
# Error messages to microcopy
## Steps
1. Read the technical error and work out what happened for the person.
2. Write a title of up to 5 words that says what happened, without blame.
3. Write one sentence that says why, or what is still safe.
4. Write one action label that starts with a verb.
## Output
Title: …
Message: …
Action: …
## Rules
- Never invent a cause the error doesn't show. If unsure, say "Something went wrong".
- No technical codes, no exclamation marks, no "Oops".
- If the error involves payment or personal data, add: "Check with the product team before shipping."
The rules of the format (specification):
name: up to 64 characters, lowercase letters, numbers and hyphens, and the same as the folder name (error-microcopy/SKILL.md).description: up to 1,024 characters. Say what it does and when to use it, in the words people actually type. It's how the tool decides to load your skill.- Keep
SKILL.mdunder about 500 lines. Put long references in areferences/folder next to it.
Download: this skill as a zip, ready to upload (folder error-microcopy/ with its SKILL.md) · SKILL.md only.
4. Test it by hand, before any AI
Give your SKILL.md and three real inputs to a colleague. Ask them to follow it exactly, without asking you anything. Wherever they hesitate, the AI will guess. Fix those spots.
5. Install it
Upload a zip in Customize → Skills.
All plans; code execution on~/.claude/skills/<name>/
Loads by description or /name~/.agents/skills/<name>/
Check your plan~/.copilot/skills or .github/skills
Personal or per project~/.cursor/skills (also reads ~/.claude/skills)
Personal- Claude (claude.ai): available on all plans, with code execution turned on. Zip the folder and upload it in Customize → Skills. On Team and Enterprise, an owner first turns skills on in the organisation settings. claude.ai rejects frontmatter fields that aren't in the standard.
- Claude Code: put the folder in
~/.claude/skills/error-microcopy/. It loads on its own when your request matches the description, or with/error-microcopy. - Other tools: ChatGPT's desktop app and Codex read
~/.agents/skills; GitHub Copilot reads~/.copilot/skillsor a project's.github/skills; Cursor reads~/.cursor/skills(and~/.claude/skills). Check each tool's docs for your plan.
6. Check it on past work
Run the skill on five past cases where you already know the good answer. For each, note: right, partly right, wrong, and why. Then change one thing in SKILL.md and run the five again. That's a tiny eval: see Write an eval set.
7. Common mistakes
- A vague description ("helps with copy"): the tool never loads the skill.
- Wishes instead of steps ("be clear and friendly").
- No output format, so every answer looks different.
- No rules about what it must never do.
- Sharing it before checking it on past work.
- Installing someone else's skill without reading every file. See the review checklist in UX agents and skills: a guide for designers.
8. Vocabulary
| Term | Meaning |
|---|---|
| Skill | A folder of instructions an AI tool loads for one kind of task |
SKILL.md |
The skill's main file: frontmatter plus instructions |
| Frontmatter | The block between --- lines at the top, with name and description |
| Agent Skills | The open format for skills, used by several tools |
| References | Extra files the skill reads only when needed |
9. Try it
- Pick one task you repeated this month.
- Write its
SKILL.md, using the example in section 3 as a template. - Test it by hand with a colleague (section 4).
- Install it in one tool and run it on five past cases (section 6).
Reflection questions: What did writing the rules teach you about your own process? Which rule would you add after the five test cases?
Checklist
Learn more
- Format: Agent Skills · Specification · Quickstart
- Tools: Claude Code skills · Anthropic skills repository
Books, courses and videos to go deeper
Related
UX agents and skills: a guide for designers · Building an AI agent roadmap for your UX team · Prompt patterns for designers · AI for content design · Write an eval set · Context files