Writing a skill for an AI agent: when you need one and how it is built

After a couple of months of working with an AI agent, a pattern shows up: you keep typing the same instructions over and over. "This project uses Bun", "the file lives here", "draft first, do not publish".

That is not an instruction. That is an undocumented procedure. And if you retype it every time, you have become the cache.

A skill solves exactly that problem: you write the repeating procedure into a file, and the agent opens it itself when it is relevant.

What a skill is

Technically a skill is a markdown file. A little metadata at the top, then the instruction text.

---
name: notion-blog-writer
description: Write a blog article and save it to Notion as a draft.
  Used when the user says "write an article".
---

# Process

## 1. Understand the brief
...

The core idea is simple: this text does not sit in context permanently. The agent loads it only when needed. That is why a dozen skills do not choke each other.

That is also what separates a skill from ordinary project documentation. A document sits there and waits for someone to read it. A skill invokes itself at the right moment.

The most important line is description

When writing a skill, people pour all their effort into the instruction body and dash off the description. It should be the other way round.

The reason: the agent decides which skill to open based on the description alone. The instruction body is not visible to it yet. So with a poor description, even flawless instructions inside will never run.

A bad description:

description: Helper for working with the blog

A good one:

description: Write a blog article and save it to Notion as a draft.
  Triggers on "write an article", "new post", "put this on the blog".
  Writes the article in three languages: uz/ru/en.

The difference is that the second one contains trigger phrases. You write down, literally, the words a user might arrive with. This is the single change with the largest effect.

Break the instructions into steps

The most reliable shape for a skill body is numbered steps. Not prose, a list.

My blog skill is laid out like this: check the queue, understand the brief, write the Uzbek draft, get approval, translate, build the payload, save, report.

Steps give you two things. First, the order becomes explicit and the agent does not skip a stage. Second, and more important, they create checkpoints. I wrote "do not move to publishing until approved" into the skill, and that one sentence has prevented an accidental publish more than once.

Always write down the traps

The most valuable part of a skill is not the instructions but the list of traps — the mistakes you have already eaten.

My blog skill carries this note: Notion has two separate date columns, one that shows on the site and drives sorting, another that triggers auto-publishing. If they drift apart, the article goes out with the wrong date.

That actually happened a few months ago: when I changed the publishing schedule I moved only one column, and several articles sat on the site with a date in the future.

Now the trap is written in the file. Which means I will not eat it a second time, and that knowledge lives in the system rather than in my head.

A practical rule: every time something goes wrong while working with the agent, ask yourself — "will this recur?". If yes, add one line to the skill after fixing it.

How a skill saves context

The technical value of a skill is often misunderstood. People think of it as a way to give the agent more information. It actually does the opposite — it lets you give less.

The reason is that context is a limited resource. If you write every instruction into project documentation and load it into every conversation, ten procedures occupy space in all ten conversations — even when nine of them are irrelevant.

A skill is two-stage instead: the agent first sees only a list of short descriptions, and opens the full text precisely when it is needed.

That has a practical consequence: you need not be afraid of writing a long skill. My blog skill runs to seven steps, several code examples and a list of traps. If that text were loaded into every conversation I would be forced to trim it — and the most useful part, the details, is exactly what would go.

Not one big skill, but several small ones

The second structural question: one large skill or several small ones.

I prefer small ones, and the reason follows from the point above. If you write one enormous "working with the project" skill, it will open for all sorts of reasons and load in full every time. While deploying, you do not need your content-writing rules.

Draw the boundary like this: one skill, one completable task. Write an article. Cut a release. Prepare a report.

If the word "and" appears more than twice in a skill's description, it probably wants to be two skills.

When you do not need a skill

This part usually gets skipped, but it matters.

You do not need a skill when:

• The task is one-off. A plain prompt is enough for something you do once.
• The instruction is short. Wrapping a single sentence in a skill is a pointless layer.
• The knowledge is already in the code. The agent can read code; restating your project structure is wasted work.
• The instruction changes often. Freeze something weekly-changing into a file and the file quickly becomes a lie.

The best candidate is a stable, repeating procedure that has traps. A deploy order, a release checklist, a report format, a content pipeline.

How to test a skill

After writing a skill you must test it, because the most common failure is that it never fires at all.

The test is simple: start a fresh conversation and use the natural phrase a user would actually type. If the skill does not open, the problem is almost always the description — missing trigger phrases.

The second test is deviation. Give a request that drifts slightly from the instructions and see whether the skill adapts or seizes up. A good skill is not a rigid script; it sets direction.

Conclusion

A skill is memory you handed to the agent. Writing one is an investment, and it pays off under one condition: the procedure genuinely repeats.

The easiest way to start is this — next time you write a long instruction to an agent, ask yourself: "will I write this again?". If the answer is yes, move that prompt into a file, put a good description on top, and break it into steps.

The articles on my blog are written exactly this way: I name the topic, and everything else — structure, three languages, setting the dates, avoiding the traps — is written in a file and runs by itself.