How to Build an Agent Skill That Actually Fires

Most people install skills. Then they wonder why the agent never uses them. Then they call the skill by hand anyway, which is the exact thing the skill was supposed to remove. The problem is almost never the model.

A skill file you write yourself in 20 minutes will beat almost every skill you will ever download. I measured the 55 most popular skills on GitHub to check whether that was just my bias. It was not. Twenty-seven of them cannot tell your agent when to run, yet they load on every single message you send and charge you for it.

The five skills I wrote myself are the only ones I have never turned off, and they do the most work in my business.

What a skill actually is

A skill is worth building when it holds something your agent cannot work out on its own. Your way of doing a job. Your corrections. Your specific mess.

That is the whole test. If the agent could derive it, you are writing documentation, not a skill.

Everything below is five steps, and I built one alongside them: a skill that audits my other skills, reads every description, measures every file, and hands back a table. It is free and the link is at the end. Build your own as you read, on whatever job you keep re-explaining.

Step 1: Pick the job, then harvest your corrections

Pick what you want your agent to do for you, not what I wanted mine to do.

The shortcut is to think of things you have asked for more than once. If nothing comes to mind, ask the agent directly:

What are the things I ask you for repeatedly that you think we should turn into a skill?

Whatever comes back is the skill to build first.

Now the part that matters, and the part everyone skips because it looks like work. There are two honest places to get the content:

1. Do the job by hand once, and write down every correction you made along the way.
2. Point the agent at work you have already done, and let it read the corrections out of that.

Here is the sentence I actually type:

Go back through the last three times we did this. Write down every single thing I corrected you on. Do not summarise it. I want the actual corrections.

Those corrections are the most valuable thing in the file. Every one of them is a mistake you never have to catch again.

This step is about 80% of what makes a skill good. Skip it and you will rewrite the same note every week for the rest of your life.

Step 2: The description is the trigger, not a label

A skill that never fires is not a bad skill. It is an invisible one.

Here is the mechanic people miss. Your agent does not load all of your skills. There is not enough room. It loads the name and the description of each one and nothing else, reads those descriptions, and decides which to use.

So the description is not a label. It is the entire trigger.

Take one of my own skills before I fixed it:

You are Nova, an agent that handles YouTube content strategy end to end.

That says what the skill is. It never says when to reach for it, so the agent has nothing to match against. The fix is one clause:

Use this skill whenever we are working on a YouTube video.

That is it. That is the whole repair.

Of the 55 skills I measured, 49% describe what the skill is and never once say when to use it. It is the single most common defect in the ecosystem, and it is a one-line fix in every case.

One more thing, and it runs opposite to what you would expect. Models undertrigger. They skip skills they should have used. So push the description harder than feels comfortable, because the failure you will actually hit is a skill sitting there doing nothing.

If you do one thing from this article, open a skill you installed last week and read its description out loud. If you cannot tell when it should fire, neither can your agent.

Step 3: There is a size where a skill starts costing more than it returns

I will use my own file, because I am the worst offender in my own data.

Nova, my YouTube skill, was 19,000 tokens. The published guidance is to keep the body under 500 lines, roughly 5,000 tokens. So I was nearly four times over. Worse, the median across the 55 skills I audited was 1,665 tokens. I was running something twelve times heavier than what everyone else installs, and I built it that way on purpose.

That skill sent 6.19 million extra input tokens. Those did not come off a card. They came off my limits, which is the five hour window, and that is the part you actually feel.

A file does not get like that from one bad decision. It gets there from 40 small ones. Something breaks, so you add a rule. Deleting feels risky and adding feels safe, so you add a section.

The structure that stops it is simple. A skill holds two things and only two things:

• The steps. The procedure.
• The references. The material the steps need.

Once you see it that way the fix is obvious. Anything the skill needs only sometimes does not belong in the main file. It goes in a references folder, and the agent opens it when the job actually calls for it.

That is the largest token cut available to you, and almost nobody takes it. One skill out of 55 used a references folder. Two percent.

The sentence for it:

Read the skill and tell me which parts only get used some of the time. Move those into a references folder and leave a pointer.

Step 4: Write the fragile parts as scripts, not instructions

Some steps you do not want the model thinking about.

The distinction is this. If there are many right ways to do a step, write instructions and let the agent improvise. If there is exactly one right answer, write code.

A model does not run your instructions. It reads them and improvises through them, every single time. For a loose step that is fine. For arithmetic it is a coin flip. I asked for the same token count three times using instructions alone and got three different numbers.

So anything you cannot afford to have improvised goes in a script the agent runs step by step. The script never enters your context window, which makes it cheaper and more reliable at the same time. That combination is rare enough that when you find it, you take it.

One detail that will bite you: be explicit about whether the agent should run the file or read it. Leave it to a guess and it will sometimes paste your script into the conversation as reference material, and you have just paid tokens for the exact thing you were avoiding.

There is also a safety switch worth knowing. You can mark a skill so the model cannot invoke it and only you can. If a skill sends a message, deploys something, or spends money, that switch is not optional. My rule is that anything with consequences outside my machine waits for me.

Step 5: The version that works is the one you cut

Now that the file works, make it smaller. There is one test and it takes ten seconds.

Delete a paragraph. Run the skill again. If the output did not change, that paragraph was doing nothing and you have been paying for it on every run.

I have done this to my own file and it is humbling. Whole sections that read like careful instruction and change nothing, because the model already knew. Telling it to write a clear summary does not make the summary clearer. It just costs you.

Three things to hunt for:

• The same rule written in two places, so you fix one and the other stays broken.
• Material that piled up over months because adding felt safer than deleting.
• Text that sounds like instruction but changes no behaviour at all.

Then the move that makes a skill worth having. After every run where the output is not quite right, ask one question: is this a one-time fix, or should this be in the skill forever? If it is forever, it goes in the file. That is how the thing improves instead of standing still.

The sentence:

Look at the back and forth we just had. What should I add to the skill so we never have this conversation again?

I will be honest about the limit. This only compounds if you actually do it, and most weeks I forget. The skills that got good are the ones I remembered to update. It is not clever. It is just repeated.

Before you install anyone else's skill

There is one finding from those 55 skills that changed how I install anything.

A skill can ship code that runs. Installing one from a stranger means putting a stranger's executable next to your files and whatever keys you have lying around.

Here is how close I came. While researching this, I went to install a well known agent memory tool. Over 27,000 stars, MIT licensed, completely legitimate project, nothing wrong with it. But the obvious install command pulled a different package entirely, because somebody had squatted the name on the public registry.

The project was fine. The command almost everybody would type was not.

So, two minutes of work every time:

1. Take the install command from the repository itself. Never from a blog post, never from a video, never from memory.
2. Send the link to your agent and ask it to scan for anything malicious before you run it.

Whether the squatter owns the name or the repo itself is hostile, you would rather be safe.

What you actually get

A skill is not a prompt in a folder. It is four decisions:

• When it fires. The description.
• What goes in it. Steps and references, nothing else.
• What comes out of it. The deletion test.
• What happens to the fragile parts. A script instead of a guess.

But the reason I care is simpler than any of that. The job you just wrote into a file is a job you are never going to explain again. Not next week, not next month, not ever. No briefing, no reminding, no pasting the same context in for the fifth time. You call it by name and it runs.

That is what people mean when they say an agent feels like an employee. It is not the model getting smarter. It is that the things you used to repeat are now written down once, properly, somewhere it reads on its own.

Get five of those and your agent is doing real work every week. It costs nothing but the time.

The reason your agent feels inconsistent is usually not the model. It is that you handed it a pile of files nobody ever wrote properly, mine included.

Take the audit skill

The skill from this article is free and public: github.com/sharbelxyz/skill-audit.

Point it at your own skills folder and it will hand you the same table you watched me build: which descriptions never say when to fire, how many tokens each file costs you, and which ones are carrying material that belongs in a references folder.

Start with the description column. That is where half the ecosystem is broken, and it is the cheapest thing you will ever fix.