sxsphinxstack

Home / What is a skill?

What is a skill?

A skill is a short instruction sheet, written in ordinary English, that you give to an AI assistant before it starts a task. It records how the task should be done: when the instructions apply, the steps in order, the rules that must hold, and what must be true at the end. This page starts from zero and ends at writing your own; each part assumes a little more than the one before.

Part 1: the idea

This part assumes nothing. If you already use an AI assistant, the first section will be familiar.

First, the assistant

Programs such as ChatGPT and Claude are called AI assistants. You type a request in plain language, such as "write me a cover letter" or "explain this bill", and the program answers the same way. The newer ones can also carry out work over many steps, such as reading a folder of files or building a simple website. When an assistant works through steps on its own like that, people call it an AI agent. For this page the difference does not matter; "assistant" covers both.

The problem

An assistant will attempt almost anything you ask, immediately, whether or not it knows how you want the task done. Ask one to "write my cover letter" and you get a finished letter in seconds. It reads smoothly. It is also generic: enthusiastic about a company you never mentioned, and padded with claims about you that the assistant made up to fill the page. Nothing in your one-line request told it what a good cover letter requires, so it guessed.

A recipe card, for work

A recipe card does not cook anything. It records how a dish is made by someone who has made it well: what goes in, the steps in order, the warnings ("do not open the oven door early"), and the test for done ("a skewer comes out clean"). Hand the card to a capable cook who has never made the dish, and the dish comes out the way it is supposed to.

A skill is a recipe card for a piece of work. Someone who has done the task well writes their method down in a file. You hand that file to the assistant before it starts, and it follows the method instead of improvising one.

The same idea, in places you already know it

Written-down method is not an AI invention. Once you see the shape, it is everywhere:

A pilot's checklist. Airline pilots have thousands of hours of training and still read a printed checklist before every takeoff, because under pressure even an expert skips a step. The checklist does not fly the plane; it makes sure the flying happens in the right order. A skill's steps do the same for the assistant.

Sheet music. A good musician can improvise something pleasant on any tune. Sheet music is for when you want the piece as the composer meant it, the same way at every performance. A skill is the sheet music for a task.

A franchise operations manual. Thousands of restaurants serve the same dish at the same standard while the staff changes constantly, because the method is on paper and the paper stays when people leave. A skill is that manual for one task, and the assistant is the new staff member who actually reads it.

A trained hand. This is where the word comes from. A carpenter's skill lives in trained hands: years of practice compressed into movements that come out right without deliberation. An assistant arrives strong but untrained, like a powerful arm that has never held a chisel. The file is the training, written down and handed over whole.

A real example

Here is an actual skill from this library: cover-letter, for writing a cover letter for one specific job posting. The whole file is about a page of written English. Among its instructions:

Ask an assistant for a cover letter with this file loaded and the experience changes. First it asks for the posting, and which of the job's requirements you can honestly meet. Then it waits for you to draft, and points at any sentence a stranger could not verify. The letter that comes out sounds like you and contains nothing you could not defend in an interview, because the file ruled out the shortcuts the assistant would otherwise have taken.

Two more, from different corners of life

Skills are not only for job applications. Two more files from the same library show the range.

plan-a-household-move treats a move as a set of chains that each have to hold: the housing, the keys and access windows, the people, the possessions, the utilities, the records, the pets. Its steps include building an inventory of what to keep, sell, donate, or store; comparing movers on written scope and exclusions rather than the quoted price; and recording meter readings at both properties. Its rules are the kind you learn from a bad move: never put medication, critical documents, or irreplaceable items in the moving truck, and never assume a quote includes packing, stairs, or waiting time. Its definition of done reaches past the truck being unloaded: the essentials box got people through the first night, and the deposits, bills, and keys are all settled.

ask-for-a-raise prepares a conversation instead of a document. The steps: document what your role has actually become, research pay with sources labeled by geography and level, choose a specific request with a fallback, and rehearse — including the questions about budget, timing, and who actually decides. The rules protect you from the tempting versions: never invent a competing offer, and weigh the risk of retaliation before escalating. Its done section asks for evidence: a written brief, a rehearsed ask, and the outcome recorded with a dated next step.

A shelf of real skills

To make the range concrete, here is a sampler from the catalog, grouped by the part of life it serves. Every name links to the page with the full file.

Money and home

Getting hired

Working life

Writing, media, and design

School

Building software and using data

The advanced shelf

Every one of these is the same shape as the cover-letter file: a trigger, steps, rules, and a definition of done. The know-how inside is what changes.

Just a text file

A skill is a plain text file. You can open it and read every line before you use it, the way you would read a recipe before cooking from it. There is nothing to install and no account to create. If a rule does not fit your situation, you edit the file. Because it is ordinary written language, the same file works in any assistant. That is the whole idea: written-down know-how, in a form an AI assistant can follow. The rest of this page is about what is inside the file and what becomes possible once you have many of them.

Part 2: the file, and how to use one

This part opens the file up. It assumes nothing beyond part 1.

What is inside

Every skill in this library is one file, named SKILL.md. Strip away the details and the shape is always the same:

# name-of-the-skill
Use when: the words you would naturally say when this task comes up.

Steps:
1. First thing, concretely.
2. Second thing.
3. ...

Rules:
- The constraint that must hold even when it is inconvenient.
- What the assistant never does, even if asked casually.

Done:
- A condition a stranger could check.
- The thing that must exist at the end: a file, a page, a record.

Each part exists because of a specific way tasks go wrong without it.

The trigger. The "use when" line is phrased as the words a person would actually say, because that is how the skill gets found. An assistant can hold many skills at once; when you say "help me with a cover letter", it matches your words against the trigger lines and loads the one that fits. A trigger that reads "assists with employment-related correspondence" matches nothing anyone says.

The steps. Ordered and concrete, and the first ones are usually about looking before doing: get the posting, read the existing file, ask what the person needs. Most botched tasks are botched in the first minute, when the assistant starts producing before it understands the situation.

The rules. These are the lines that begin with "never" and "do not". They exist for a predictable moment: partway through the work, cutting a corner starts to look attractive — inventing a plausible detail, skipping a check, sending something without reading it back. An instruction you typed into the chat two hours ago has scrolled out of sight by then. A rule in the loaded file is still in force.

Done. Without a definition of done, a task ends when the output looks finished, which is a judgment about appearance. With one, it ends when stated conditions hold: the letter is under 250 words, every claim is true, the file is saved and named for the company. Done conditions are written so that a stranger could check them.

How to load one

There is no installation. Using a skill means getting its text in front of the assistant at the start of the task, and any of these works:

Then describe the real task in your own words and keep the skill loaded until its definition of done is satisfied. The skill supplies the process. The facts of your situation, and the decisions along the way, still come from you.

How a skill differs from a prompt

A prompt asks for a result: "write my cover letter, and make it professional." Everything beyond that one line, the assistant fills in by guessing. A skill records the process used to produce and check the result. The practical differences follow from its being a file. A prompt is typed fresh each time and disappears with the chat. A skill can be read before use, corrected after a failure, kept with a project, handed to another person, and loaded into a different assistant next year.

Most advice about writing better prompts amounts to packing more of the process into the request. A skill is where that packing ends up once you stop retyping it.

When a skill is worth writing down

Not every task needs one. A question with a factual answer, or a rough draft you intend to rework entirely, needs no procedure. A skill pays for itself when the task repeats, when the result has a standard someone will hold it to, or when the ways it can go wrong are known and expensive. A cover letter qualifies on all three counts: people write many of them, a hiring manager judges the result, and the known failure is a generic letter full of invented claims.

The working rule, from this site's guide to configuring an agent: the moment you catch yourself explaining the same thing to an assistant for the second time, stop and write it into a skill. A correction that lives in a file does not have to be made again.

Skills improve by editing

The first version of a skill is rarely right, and it gets better the same way a recipe card does: something goes wrong, the missing warning gets found, a line gets added. When a run produces a bad result with a skill loaded, the useful question is which line was missing or wrong. Maybe the steps never said to confirm the company name, so the letter went out with last week's company in it; now the file says to check it twice. The next run starts from the corrected version. Over months, this is the difference between an assistant that keeps making an error and one that made it once.

Easier ones and harder ones

Skills differ in how much judgment they expect from the person running them, and this library grades every skill on a three-step scale:

Part 3: writing your own, and what comes after

This part is for the reader who wants to make skills rather than only use them.

Writing a skill

Start from a task you have done well at least once. A skill is a record of a method that worked; it is not a place to speculate about how a task might be done. Then:

Most of this can be checked mechanically. Every file in this library passes an automated review before it is published, which rejects, among other things: a description that never says when to use the skill, a procedure without ordered steps, a file that names no concrete artifact or observable result, a file with no boundary line (no "never", no permission rule, no scope limit), a done section with fewer than two evidence-based checks, instructions written as roleplay, and any file longer than 500 lines.

Skills that use other skills

A skill can end by pointing at another one. The last line of the cover-letter skill says: if this letter is going out with a resume, run the tailor-resume skill on that resume against the same posting first, so the two documents use the same vocabulary. That single line chains two procedures into a longer one, and chains like it are how a library of small skills covers large jobs. The project briefs on this site approach the same fact from the other side: each brief describes a piece of work sized from a week to a month or more, and names the skills needed to complete it.

Where skills sit in a full setup

A skill answers one kind of question: how to do something. An assistant you work with daily accumulates other kinds of knowledge too, and the brain guide on this site sorts all of it with one test. Is it taste, tone, or a standing rule that applies to everything? That is identity, stated once where the assistant always reads it. Is it a fact or a past decision? That is memory, stored with a date, because facts go stale. Is it how to do something? That is a skill. Must it happen every time with no judgment involved? That is a reflex, pushed into automation where the tools allow it. The sorting matters because misfiled knowledge stops working: a procedure stored as a memory gets recalled as trivia instead of executed as steps.

A skill alone, and a skill in a system

Everything above treats the skill as a lone file, and that is a design choice. A file that refers to nothing outside itself loads into any agent, travels between projects, and survives a change of tools. The cost is that the file cannot say who should run the work, what upstream work feeds it, or where its output goes.

The sister project smbwiki makes the opposite choice. It models 125 types of small business as one graph in which each skill is a shared node, and each business binds the skill to its own situation: which role owns it, which records go in and out, which number judges the result. Connecting skills this way makes new facts visible. From the text of a skill you cannot tell whether it is universal or niche; in the graph you can count. Accounts payable runs in 108 of the 125 business types, while 173 of smbwiki's 227 skills run in exactly one. The essay what a graph does to a skill works through the rest of what changes, including what the shared structure costs in upkeep.

The mistakes to avoid

Skill files fail in recurring ways, most of them visible on a first read:

Where to look next