Marcus Andrey Study
Ler em português Library

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.md with 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

  1. 1Choose

    A frequent task with an agreed "right way".

  2. 2Write

    Description, steps, output, rules.

  3. 3Test by hand

    A colleague follows it without asking you.

  4. 4Install

    In the tool you use.

  5. 5Check

    Five past cases; change one thing; repeat.

Your first skill in five steps. Diagram: Marcus Andrey, CC BY 4.0.

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.md under about 500 lines. Put long references in a references/ folder next to it.

Download: this skill as a zip, ready to upload (folder error-microcopy/ with its SKILL.md) · SKILL.md only.

A typewritten recipe card for pound cake, listing ingredients and the steps in order.
A recipe card is a skill on paper: a name, the ingredients, steps in order and the one warning that matters. Anyone can follow it without asking the cook. Photo: SJGW, Wikimedia Commons, CC BY-SA 4.0.

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

AppClaude (claude.ai)

Upload a zip in Customize → Skills.

All plans; code execution on
FolderClaude Code

~/.claude/skills/<name>/

Loads by description or /name
FolderChatGPT desktop and Codex

~/.agents/skills/<name>/

Check your plan
FolderGitHub Copilot

~/.copilot/skills or .github/skills

Personal or per project
FolderCursor

~/.cursor/skills (also reads ~/.claude/skills)

Personal
Where the same skill folder goes in each tool, as of November 2026. Diagram: Marcus Andrey, CC BY 4.0.
  • 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/skills or 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

  1. Pick one task you repeated this month.
  2. Write its SKILL.md, using the example in section 3 as a template.
  3. Test it by hand with a colleague (section 4).
  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

Books, courses and videos to go deeper

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

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close