Claude Code Skills: a folder and one note

1The same instructions, every single chat

You know the feeling. Every new chat, you paste the same instructions. The same brand rules. The same "no, do it this way." Over. And over.

None of it sticks, because none of it was written down anywhere the AI can find it. So you retype it, or you dig through an old conversation to copy it out, and the version you paste this week is slightly different from the version you pasted last week. The output drifts with it.

Now imagine the other version. You hand your AI a short note, written once, and from then on it just knows. It knows your style, your steps, your tools. You never explain that job again.

That note is a Skill. And here is the part nobody tells you: there is no magic to it at all.

2A Skill is a folder

Not a plugin. Not a config format you have to learn. A Skill is a folder. That is it.

Inside that folder is one text file, called SKILL.md. Everything a Skill needs to work lives in that one file, and everything else in the folder is optional extra weight you can add later if the job calls for it.

If you can write a checklist for a new teammate, you have already written a Skill.

my-first-skill/
└── SKILL.md          ← the note. This is the only required file.

---
name: <what this Skill is>
description: <when to reach for it>
---

Use this template.
Apply this voice.
Run this script.

3The two lines at the top

Open the file and look at the top. Two lines: a name and a description. That is the only part you truly need.

They do different jobs, and it is worth being clear about which is which:

The description is the line that decides whether your Skill ever gets used. It is what your AI reads when it is deciding whether this job is the job you wrote the note for. Everything else in the file is instructions for after that decision has already gone your way.

4Below that, just steps

Below those two lines? Plain English. Just steps.

Real ones, in the order you would say them out loud:

Use this template.
Apply this voice.
Run this script.

That is the whole register. No code required. No special syntax. A folder, and a note.

The test to hold yourself to is the one you already know how to pass. If you can write a checklist for a new teammate, you can write this. You are not programming anything. You are writing down, once, the thing you have been saying out loud every week.

5How your AI reads a Skill, in three stages

Here is the clever bit, the thing that makes Skills actually work at scale. Your AI does not read the whole folder up front. It peeks, in three stages.

1. Discovery

   At startup, it reads only the name and description. Just enough to know the Skill exists, and nothing more. That is about a hundred words of memory. Nothing.

2. Activation

   The moment your task matches, then it opens the full instructions. Not before. Until that moment the steps you wrote are sitting on disk, costing nothing.

3. Execution

   The extra files, the scripts, the brand guide, those stay on the shelf until the exact moment they are needed. Some of them are never opened at all on a given job, and that is the point.

It is called progressive disclosure.

This is why a shelf full of Skills does not make your AI slower or vaguer. It stays sharp, because it is never drowning in things it does not need yet.

6Watch it think: filling in a PDF form

Abstract is fine, but watch it happen on a real job. Say you ask it to fill out a PDF form.

1. You ask

   Nothing special. You describe the job the way you would describe it to a person.

2. It spots the matching Skill

   Your request lines up with a description it read at startup, so it opens that Skill and reads the instructions.

3. It skips what it does not need

   This is the smart part. It sees a file for forms that this particular job does not call for, and it skips it. Leaves it on disk. Never spends a moment on it.

4. It runs a ready-made script

   The Skill carries a small script for the actual work, and it runs it. Here is the kicker: that script runs without the AI having to read the code. It just gets the result.

So it grabs only what the job needs. Real steps, real tools, not guesswork. That is the whole trick.

7Write it once, use it everywhere

One more thing, and it is the best part. A Skill is an open standard.

Write it once, and it runs across Claude and a growing list of other tools. The note you wrote this afternoon is not tied to the one place you wrote it. You are not locked in.

You are teaching once, and using everywhere.

8Make your first folder

So here is your move, and the whole instruction fits in a line: do not overthink it.

1. Make a folder

   Give it a name that says what the job is. That name is already half of the note.

2. Write down a job you keep repeating

   In plain words. The one you find yourself explaining again every few days is the right one to start with.

3. That is your first Skill

   There is no step four. The AI was never the scary part. It has been waiting for you to hand it the note.