If you use an AI assistant seriously for more than a few weeks, you end up with a prompt you keep pasting. The one that finally got the tone right. The eight-line checklist you run before sending anything important. You keep it in a note, you paste it in, you tweak it slightly, and next month you paste a slightly different version and get a slightly different result.

A skill is the fix for that. It’s the same instructions, written down once in a place the assistant can find on its own.

What a skill actually is

Strip away the branding and a skill is a folder containing a Markdown file called SKILL.md. That file has two parts: a short block of metadata at the top, and your instructions underneath. Optionally the folder holds supporting material — reference documents, templates, a script.

That’s the whole format. There’s no app to install and nothing to compile.

weekly-update/
├── SKILL.md          ← required: metadata + instructions
├── references/       ← optional: background it can consult
└── assets/           ← optional: templates, examples

And SKILL.md itself:

---
name: weekly-update
description: Turns rough notes into a weekly status update. Use when the user
  pastes messy notes and asks for an update, summary, or status write-up.
---

Take the notes provided and produce a weekly update in this structure:

1. **Shipped** — what actually finished. Past tense, one line each.
2. **In flight** — what's moving, with the current blocker named explicitly.
3. **Needs a decision** — anything waiting on someone else. Name who.

Rules:
- No more than 150 words total.
- Never invent a date, number, or name that isn't in the notes.
- If something is ambiguous, list it under "Needs a decision" rather than guessing.

The useful thing here is that this format is a genuine open standard — the Agent Skills spec — and both Anthropic and OpenAI have adopted it. A skill you write for Claude works in ChatGPT and Codex, and the other way round. That’s rare enough in this industry to be worth noticing.

Why bother

It stops the drift. A prompt you retype is a prompt that quietly changes. A skill is one file, so improving it means editing that file, and every future use inherits the improvement.

It costs nothing until it’s used. This is the part people miss. The assistant only holds the description in mind at all times — a single line. The full instructions load only when the skill is actually triggered. So a skill can carry two thousand words of hard-won detail about how you like something done without slowing down every unrelated conversation. Stuffing that same detail into a general “custom instructions” box does not have this property.

It triggers itself. Once the description is written well, you stop having to remember the skill exists. You describe the task in ordinary language and the right instructions load.

It’s portable. A skill is a folder. You can copy it, back it up, put it in a repository, or send it to someone. It isn’t locked inside one vendor’s chat history.

The honest limit: a skill is instructions, not intelligence. It makes a capable assistant consistent. It won’t make a bad output good.

Build one, step by step

1. Pick a task you’ve done at least three times

Not the most impressive task — the most repeated one. Reformatting notes. Drafting a particular kind of email. Running your own pre-send check on a document. Three repetitions is roughly the point at which you actually know what “good” looks like, which is the thing you’re about to write down.

Keep it narrow. One skill, one job. “Write things well” is not a skill. “Turn notes into a weekly update in my format” is.

2. Create the folder

Name the folder in lowercase with hyphens, and make the folder name match the name in your metadata. Mismatches are the single most common upload error.

mkdir -p weekly-update

3. Write the metadata

Two fields are required: name and description. In Claude, name is capped at 64 characters and description at 200.

Spend your effort on the description. It is the only part the assistant sees before deciding whether to use the skill, so it is doing two jobs: saying what the skill does, and saying when to reach for it. Write it in terms of what the user would say, not what the skill contains.

Weak: description: A skill for writing updates.

Better: description: Turns rough notes into a weekly status update. Use when the user pastes messy notes and asks for an update, summary, or status write-up.

If a skill never seems to fire on its own, the description is almost always the reason.

4. Write the instructions like a procedure, not an essay

Below the metadata block, write what you’d tell a sharp new colleague who has never seen your work. Numbered steps. Explicit inputs and outputs. Concrete constraints — word counts, formats, things to never do.

Two rules that pay off immediately:

  • Include a real example of good output. One worked example does more than three paragraphs of description.
  • Write the failure modes down. “Never invent a figure that isn’t in the source” is worth more than any amount of positive instruction, because it targets the thing that will actually go wrong.

Prefer plain instructions over scripts. Only reach for a script when you need the same deterministic result every single time — a specific calculation, a file conversion.

5. Test it, and then test it badly

Start a fresh conversation. First, invoke it directly by name and check the output. Then — the real test — describe your task in your own words without naming the skill, and see whether it fires on its own. If it doesn’t, go back and rewrite the description in the words you just used.

Try it three or four times with different messy inputs. You’re looking for the place where your instructions were ambiguous, then closing that gap in the file.

6. Put it where the assistant will find it

Where depends on the tool, and this is the one part likely to shift over time:

  • Claude, in the app or on the web — enable code execution under Settings, then go to Customize → Skills and upload a ZIP of your folder. The ZIP must contain the folder, not the loose files.
  • Claude Code — drop the folder in ~/.claude/skills/ to have it everywhere, or in a project’s .claude/skills/ to keep it to that project. It’s picked up without a restart.
  • Codex — put it in ~/.agents/skills/ for personal use, or in .agents/skills/ inside a project. Invoke it with $skill-name.
  • ChatGPT — upload it from the Skills section of settings.

There’s a fuller walkthrough of installing skills, including ones you didn’t write, in How to install a skill you downloaded.

The shortcut worth knowing

Both platforms ship a skill whose job is writing skills. In ChatGPT it’s @skill-creator; in Codex, $skill-creator. Claude will build one with you conversationally if you describe the task and ask it to make a skill.

This is genuinely the fastest way to start — but treat the result as a first draft and read every line. The generated version will be structurally correct and slightly generic, and the entire value of a personal skill lives in the specific parts: your format, your constraints, the mistake you’re tired of correcting.

Three ways this goes wrong

Collecting skills you never use. It’s satisfying to install twenty and use none. Every enabled skill is a line of description competing for attention. Keep the ones you actually reach for and turn the rest off.

Making one skill do four jobs. Broad skills trigger unpredictably, because the description has to be vague enough to cover everything. Split them.

Writing instructions you’d never say out loud. If you wouldn’t tell a colleague “be thorough and professional,” don’t write it in a skill. It’s not an instruction, it’s a mood.

Keeping this current

Skills are new and the details move — menu names, limits, supported fields. The concepts above are stable; the click paths are not. When something doesn’t match what you see on screen, the source of truth is the vendor:

Written 30 July 2026. Verified against both sets of documentation on that date.

If you want the layer underneath this — what these systems actually are, where they fail, and the vocabulary to follow the conversation — The AI Primer is the plain-English version. $23.97.