The Art Of Skill Writing

Did you know that most Skill files never work? Skills sound simple but there is still some craft involved. Find out how to write ones that work.

Photo by Google DeepMind

Interestingly (and alarmingly) I learned that most skills people install never fire.

You may have written a few or generated some with your favourite model, where they get saved and then never initiate. When you prompt for the exact task the skill was made for, weirdly the model answers from scratch as if the skill were never there or makes something new up.

When I built the 241 design skills that many of you have been downloading, I had also discovered this. What ensures each one of my skills fires is one field at the very top of the file: Description.

---

First, what is a skill?

A skill is a small markdown file that’s used to teach the model how you want a particular job done, like giving it a recipe. You write it using your own ideas of how things should be done so you never have to explain it again. The idea is that you write it once, and the model fetches it and uses it whenever the moment is right.

I’ve built more than 240 of these (and counting), they are free and open source and cover everything from user research to design systems to interface critique. You can download the whole set here and have them working in moments. This post explains the template and how they work, so you can write your own. You should write some of your own or modify some of mine for your own use.

---

How it works

The mechanics of it are quite simple.

The model doesn’t read your whole skill up front. What it sees first are only two things: the name and the description fields. Everything else stays on disk until the description tells the model that this moment is the moment your skill was made for.

Which means the description is the trigger mechanism.

Here is a description from a color-system skill:

Build a comprehensive color system with palette generation, semantic mapping, and accessibility compliance.

Notice the structure and how it’s written:

It opens with a verb and it says exactly what the skill makes, it clearly articulates the specifics so the model can spot the pattern when it shows up. It’s doing a job if that makes sense, it’s not describing itself to you.

That precision is the entire skill of skill-writing. If you can write that one sentence well, the rest is easy.

I learned this the hard way because my first ones said things like 'helps with design' and just sat there. The worst part of that I didn’t notice at first. Another issue with poorly written skills and skill collections is collisions: multiple skills appear to do the same thing, the model favours one and ignores the rest. This happened to me as well, and it came back down to be precise and clear. Yes, I know: how annoying... You also will be tempted to let the model run a few skills based on your templates, and this will work about 60-80% - you still have to fine tune and consider the whole collection.

---

The architecture

Every one of the skills files follows the same structure.

---
name: color-system
description: Build a comprehensive color system with palette
  generation, semantic mapping, and accessibility compliance.
---

# Color System

You are an expert in building systematic, accessible colour
palettes for digital products.

## What You Do

You create comprehensive colour systems with raw palettes,
semantic mapping, and accessibility compliance.

## [The domain sections]

The actual method. For colour that is palette layers,
accessibility thresholds, colour relationships. For a
component spec it is anatomy, variants, states. This is
the heart of it, and it is where your real knowledge goes.

## Best Practices

- The handful of things you would tell a sharp new colleague
  on their first day.
- The traps you already know about.
- The judgement calls that separate good output from generic.

One small rule that is easy to miss and that is also totally fatal: the skill’s name must match the name of its folder. If you get that wrong and it won’t load at all.

You’ll notice that none of my skills are long, most are twenty to thirty five lines. There are no giant reference files or appendices, and no sprawling documentation. I focus on one file, making it really tight, making sure it’s doing its one job well. I think that restraint is the part people find the hardest, because we all want to be exhaustive but that doesn’t mean we’re clear. The model is already very capable so your skill isn't there to teach it everything, but to give it your judgement and pov quickly, and then get out of the way.

---

Skills, but also Commands and Plugins

There are three other layers to think about.

Alongside the skills, each plugin has a few commands. A command composes the skills, to avoid repetition. For example, my critique-screen command has no instruction about how to read a layout. It commands the work to be done and references the skills that already know how to do that: hierarchy, composition, typography, colour, affordance, etc…each its own skill. It then gathers everything they flag into a single fix list ranked P1 to P3.

That is the architecture really: small, single-minded skills at the bottom, and commands on top that chain them into a workflow. You write each skill once, really really well, and then you reuse it in a dozen different flows.

For that reuse to work however, the structure has to stay clean. My contributor guide is very strict about it. A command never uses another plugin’s skills, and follow-ups are only ever suggested in plain language, and never hard-wired in. Keep each skill self-contained and it will work. Commands should get their own description and an argument-hint, so the model knows what to do with them.

There is one last layer, and it’s packaging. A plugin is a bundle of related skills and commands that install together. In the repo, design-research is a plugin, ui-design is a plugin for example, and they’re all sorted into five collections. You don’t need to think about plugins to write a good skill, you only make them when you have a cluster that belongs together and you want the whole set to be neatly packaged up, like a kit.

---

Why you should make your own

You should use skills like mine, but also write your own, and make sure they fire correctly. Mine have my own pov and my references in them. You might want to adjust them for yourself.

When you plan your own skills or skill collections, think in layers. The small, those repeatable moments of thought or tasks are your skills. The sequences you run again and again become commands. When a cluster starts to feel like a kit, then it’s a plugin.

Go and make your own, start with writing the description first, in plain words, very clear, sparing and descriptive of the job to be done. Keep the rest tight and then test it, and that’s it. Build yours this week, feel free to contribute to my repo or make your own.