Skills, Explained

Skills, Explained

Everything below is the how-to, not the theory. Open a row, take the three bullets, go build.

1. 01 What a skill actually is A folder with a text file that teaches your AI tool how you work.

   The short version

   • A skill is one folder with a file named SKILL.md inside.
   • The top of that file is a label. The rest is instructions.
   • The label says what the skill does and when to use it.
   • Your AI tool reads the label at startup, nothing more.
   • It opens the full instructions only when your request matches.

   Do this

   1. Make a folder named after the job, like writing-case-studies.
   2. Put one file inside it, named exactly SKILL.md.
   3. Write the label at the top, then the steps below it.

   Why

   Your AI tool can't keep every instruction you've ever written in mind at once. A skill lets it carry a one-line label all the time and open the full instructions only when you need them.

   Example

   writing-case-studies/
   └── SKILL.md

   Watch out for: The filename is case-sensitive. Skill.md and skill.md won't be found.

1. 02 The label at the top The 3-line header that decides whether your skill ever gets used.

   The short version

   • It sits between two --- lines at the very top of the file.
   • You need two things: a name and a description.
   • The name is lowercase with hyphens, no spaces, under 64 characters.
   • The description is one to three sentences, under 1,024 characters.
   • The opening --- must be line one. Nothing above it.

   Do this

   1. Name it after the activity: reviewing-contracts, not helper or utils.
   2. Write the description in third person: "Reviews contracts and flags risk."
   3. Add a "Use when..." sentence naming the exact words you'd actually type.

   Why

   The label is the only part your tool reads before it decides. If the label is wrong, the instructions under it never get their chance.

   Example

   ---
   name: reviewing-contracts
   description: Reviews vendor contracts and flags risky clauses. Use when the user asks to review, check, or redline a contract or agreement.
   ---

   Watch out for: Names like helper, tools, or data are too vague to match anything.

2. 03 Writing a description that fires Your description is a trigger, not a tagline. Write it for matching.

   The short version

   • Your tool picks a skill by reading descriptions, sometimes 100 of them.
   • Vague descriptions lose. "Helps with documents" matches nothing.
   • Include the words you'd really type, plus file types and tool names.
   • Say what goes in and what comes out.
   • Say when NOT to use it. That boundary prevents wrong matches.

   Do this

   1. Write down five ways you'd actually ask for this. Use those exact words.
   2. State the inputs and the output: "Takes a raw CSV, returns a summary deck."
   3. Add one line: "Do not use this for X."

   Why

   Your tool compares your request against every description it has. The words you actually type are the words it's looking for.

   Example

   Before:
   description: Helps with spreadsheets.
   
   After:
   description: Takes a raw CSV export and returns a one-page summary with totals and trends. Use when the user asks to summarize, clean up, or explain a CSV or spreadsheet. Do not use for building charts.

   Watch out for: Writing it for a human reader. It's read by a matcher, not a person.

1. 04 The one-screen rule Keep the main file short. Long files get skimmed and ignored.

   The short version

   • Everything loaded competes for room with your actual conversation.
   • Keep SKILL.md under 500 lines. Performance drops past that.
   • Don't explain things the model already knows. It's smart already.
   • Move rarely-needed detail into separate files in the same folder.
   • Link those files by name from the main file so it knows they exist.

   Do this

   1. Delete any sentence explaining a general concept the model already has.
   2. Move long reference material into reference.md next to SKILL.md.
   3. Add one line in the main file: "For full field list, see reference.md."

   Why

   Every line in the main file takes up room your conversation needs. A short file gets followed. A long one gets skimmed.

   Example

   ## Steps
   1. Ask which client the case study is for.
   2. Pull out the problem, the fix, and the result.
   3. Write it in 300 words or fewer.
   
   For the full style guide, see style-guide.md.

   Watch out for: Chains. Main file to file A to file B breaks. Keep it one hop deep.

2. 05 Load only what's needed Layers. Label first, full instructions second, extras only on demand.

   The short version

   • Layer one: just the name and description, always loaded.
   • Layer two: the full main file, loaded when your request matches.
   • Layer three: extra files, opened only when that step comes up.
   • An always-loaded reference file can waste tens of thousands of words.
   • Treat the main file like a table of contents, not the whole manual.

   Do this

   1. Ask of each block: is this needed every single time?
   2. If no, move it to its own file and name the file for what's in it.
   3. For any file over 100 lines, put a short contents list at the top.

   Why

   Your tool can only hold so much at once. Anything loaded just in case pushes out something it needs right now.

   Example

   writing-case-studies/
   ├── SKILL.md           every time
   ├── style-guide.md     when writing
   └── past-examples.md   when asked

   Watch out for: Dumping everything in one file "just in case." That's the main failure.

3. 06 How tight to hold the reins Match how specific you get to how badly the task can break.

   The short version

   • Many valid approaches? Give direction, not steps. Let it choose.
   • One preferred pattern? Give a template with a few settings.
   • Fragile or destructive? Give the exact command and forbid changes.
   • Code reviews are loose. Database changes are locked down.
   • Guessing wrong in either direction wastes effort or breaks things.

   Do this

   1. Ask: if this goes sideways, is it annoying or expensive?
   2. Annoying, write heuristics. Expensive, write the exact command.
   3. For locked steps, add: "Run this exactly. Do not add flags."

   Why

   Too loose on a risky step, and it improvises where it shouldn't. Too tight on a creative one, and every answer comes out the same.

   Example

   Loose:
   Review the draft for tone and clarity. Suggest fixes.
   
   Locked:
   Run exactly: python scripts/backup.py --all
   Do not add flags. Do not skip this step.

   Watch out for: Over-specifying creative work. It gets rigid and worse, not better.

4. 07 Scripts vs. instructions Mechanical work belongs in code. Judgment belongs in prose.

   The short version

   • Fetching, reformatting, validating: put it in a small script.
   • Scripts run without being read, so they cost you nothing in context.
   • Judgment calls and messy edge cases: write those as instructions.
   • Sorting a list in code beats asking the model to do it.
   • Say clearly whether a file should be run or read.

   Do this

   1. Put runnable files in a scripts/ folder inside the skill.
   2. In the main file, write: "Run scripts/clean.py. Do not read it."
   3. Keep the script's logic separate from the prose, so either can change alone.

   Why

   The model can sort a list. It can also get one wrong. A script does it the same way every time, and it costs your conversation nothing.

   Example

   writing-case-studies/
   ├── SKILL.md
   └── scripts/
       └── word_count.py
   
   In SKILL.md:
   Run scripts/word_count.py on the draft. Do not read it.
   If the count is over 300, cut the background first.

   Watch out for: Asking the model to chain five steps it could just run in order.

5. 08 What does NOT belong The stuff that quietly ruins a skill.

   The short version

   • No passwords, keys, or tokens. Ever. Not even temporarily.
   • No entire-domain skills. Broad ones perform worse than focused ones.
   • No non-actionable filler. If it isn't a step, cut it.
   • No unchecked input and no silent destructive actions.
   • No instructions telling the model to obey text it finds in outside data.

   Do this

   1. Read your file and delete every line that isn't a decision or a step.
   2. Move credentials to your environment settings, referenced by name only.
   3. Add a stop: "Confirm with the user before anything that changes data."

   Why

   A skill gets copied, shared, and reused. Everything in it travels with it, including the password you meant to take out later.

   Example

   Cut:
     This skill is really useful and saves a lot of time.
   Cut:
     Password: (anything at all)
   Keep:
     Confirm with the user before deleting or overwriting any file.

   Watch out for: Skills copied from strangers. Read every bundled file before you run it.

6. 09 Why yours isn't firing The ranked list of reasons your skill sits there doing nothing.

   The short version

   • The description doesn't contain the words you actually typed. Most common by far.
   • The label at the top is broken, so it's skipped without a warning.
   • The folder is in the wrong place for the tool you're using.
   • Two skills overlap, so neither clearly wins.
   • The file is named wrong, or --- isn't on line one.

   Do this

   1. Rewrite the description using your real phrasing, word for word.
   2. Ask for the task in three different ways and see if it fires each time.
   3. Still silent? Remove the competing skill and test again.

   Why

   A skill that doesn't fire fails silently. There's no error message, so you have to go looking.

   Example

   You type:
     Can you tidy up this CSV?
   The description says:
     Summarizes spreadsheet data.
   The fix:
     Add "tidy up" and "CSV" to the description.

   Watch out for: Force-loading it to "prove" it works. If it only works forced, it's broken.

7. 10 One skill, or three? How to split work without creating a traffic jam.

   The short version

   • One to three skills per task is the sweet spot.
   • More than that, they start fighting and confusing each other.
   • Nearby unrelated skills make the right one less likely to load.
   • Narrow scope with a clear boundary beats one giant do-everything skill.
   • Group related skills by subject so their names don't blur together.

   Do this

   1. Write the job in one sentence. Two verbs means two skills.
   2. Add "do not use for X" to each one so the edges are clear.
   3. If you pass five, add a simple router skill that points to the right one.

   Why

   When two skills could both answer, your tool has to guess. A clear edge on each one takes the guess away.

   Example

   The job: "Write the case study and post it to LinkedIn."
   Two verbs, two skills:
   
   writing-case-studies
     Do not use for social posts.
   writing-linkedin-posts
     Do not use for long case studies.

   Watch out for: Building a skill for something your tool already does well.

8. 11 Build it by watching it fail Don't write a skill from imagination. Write it from a real miss.

   The short version

   • Run the real task first with no skill and watch where it struggles.
   • Write the skill to close only that specific gap.
   • Watch it work on real requests, not made-up ones.
   • When it goes off track, ask it what confused it, then fix that line.
   • Ask it to fold the approach that worked back into the file.

   Do this

   1. Do the task cold, once, and note every place you had to step in.
   2. Turn each of those moments into one line in the skill.
   3. Re-run the same task next week and trim whatever went unused.

   Why

   A skill written from imagination fixes problems you don't have. A skill written from a real miss fixes the one you do.

   Example

   Cold run: 800 words, and it never mentioned the result.
   
   Two new lines in SKILL.md:
   - Keep it under 300 words.
   - Always end with the result, in numbers if there are any.

   Watch out for: Writing the whole thing up front. You'll guess wrong about what's needed.

1. 12 Making it work everywhere The same file works across most AI tools, with one catch.

   The short version

   • SKILL.md is an open format that many tools now read.
   • Plain-language instructions carry over. Tool-specific tricks don't.
   • What differs is where each tool looks for the folder.
   • So the same skill may need to sit in more than one place.
   • Skills that patch a model's weak spot expire. Skills that capture your process last.

   Do this

   1. Write instructions in plain language, with no tool-specific commands.
   2. Check where your tool looks for skills, and put the folder there.
   3. To use it in two tools, copy or link the folder into both locations.

   Why

   Tools change faster than the way you work. Plain instructions move with you. Tool-specific tricks stay behind.

   Example

   Tool-specific:
     Use the /review command.
   Plain language:
     Read the draft and list the three weakest sentences.

   Watch out for: Depending on one tool's quirks. That's the thing that won't travel.