What an AI Skill Is and How to Write One

Most people use an AI assistant the same way every time. They open a new conversation, explain what they want, paste in the material, correct the first draft, and explain the same corrections they explained last week. The work gets done, but the explaining never ends.

A skill fixes that. It’s a written set of instructions for one recurring task, saved where the assistant can read it whenever that task comes up. Different tools call it different things. Some call it a skill, some a custom GPT, some a project or an agent. The idea underneath is the same: you write down how a job should be done, once, and the assistant follows it from then on.

I have several of these for my own work. The one I use most builds a weekly report from my activity notes. Before I wrote it, every Friday started with ten minutes of reminding the assistant what the report looks like. Now it starts with one sentence.

When a task deserves a skill

Not every task does. Writing a skill takes an hour or two, and revising it takes more. It pays off when a few things are true.

• The task repeats. Weekly, monthly, or every time a certain kind of request comes in.
• The output has a known shape. A report, a proposal section, a summary, a set of meeting notes.
• You keep correcting the same things. If you’ve typed “shorter” or “use our format” more than twice, that correction belongs in a file.
• Someone else might need to do it. A skill is also a way to hand a job to a coworker, because it’s written down.

A one-off question doesn’t need a skill. Neither does a task that changes completely every time. Save the effort for the jobs that come back.

The parts of a good skill

A skill doesn’t need to be long. Mine run one to three pages. What matters is that it answers the questions a capable new employee would ask before starting.

Purpose. One or two sentences on what the task is and who the output is for. “Build my weekly territory report for my manager, who reads it on a phone between meetings” tells the assistant more than a page of style rules.

Inputs. What the assistant should expect to receive, and what to do if something is missing. This is where a lot of bad output starts. If the skill doesn’t say “ask for the date range if I don’t give one,” the assistant will guess.

Steps. The work in the order it should happen. Number them only if the order matters.

Output format. Headings, length, tone, file type. Be specific. “Under 400 words, three sections, no tables” is better than “concise.”

Quality checks. What the assistant should verify before it calls the job done. This is the part people skip, and it’s the part that saves the most time.

Examples. One good example of finished output, and if you have it, one example of a mistake to avoid. Examples do more than descriptions.

Here’s what a short quality check section looks like in one of mine:

Before you finish:
- Every number in the report appears in my notes. If it doesn't, leave it out and tell me.
- Every account name is spelled the way it appears in the account list.
- No section is longer than the summary at the top.
- If a week has no activity for an account, say so plainly. Don't fill the gap.

Write it from real work

The best way to write a skill is to do the task once with the assistant and pay attention to everything you had to explain. Every correction, every “no, like this,” every piece of background you pasted in. That transcript is the first draft of your skill.

Then strip it down. Keep the instructions that changed the result. Drop the ones that were just you thinking out loud. Write it in plain sentences, the way you’d explain it to a person, because that’s what works best.

Test it and keep revising

A new skill is never finished on the first try. Run it on three or four real examples, including an awkward one: a week with almost no activity, a request with missing information, a source document that contradicts itself. Read what comes back as if a coworker had handed it to you.

When the output is wrong, ask why. Usually the skill was vague, silent on the situation, or contradicted something else the assistant had been told. Fix the file, not just the draft. If you only fix the draft, you’ll fix it again next week.

I keep a short change note at the bottom of each skill so I can see what I changed and when. When something stops working, that note usually tells me why.

Where to be careful

A skill can carry sensitive material without anyone noticing. If you paste a real client list, pricing, or personal details into the examples, every conversation that uses the skill carries them too. Use made-up examples or strip identifying details.

Skills also go stale. If your report format changes or your product line changes, the skill keeps doing the old thing confidently. Give each skill an owner, and put a review date in the file.

And keep a person accountable for the output. A skill makes the work faster and more consistent. It doesn’t make it correct. Someone still reads the report before it goes out, and that someone is still you.