I Run Nearly 100 AI Agent Skills. Most Of Them Are Trash

The ones that survived all do the same handful of things. I am still getting plenty of it wrong.

I noticed it on a Tuesday.

I was typing the same 400 words into a chat window for maybe the fifteenth time. Same context, same constraints, same “no, not that data source”, same “check the totals before you show me anything”. By the time the agent gave me something useful I had spent longer briefing it than the job would have taken me alone.

That was the moment prompt engineering stopped making sense to me.

A great prompt is a performance. It works once, everyone claps, it evaporates. Next week you rebuild it from memory, slightly worse, in more of a hurry.

So I started saving them. Then naming them. Then adding structure, rules, scripts, gates, state.

Today I have nearly 100. I use about 30 regularly. I keep making more. I keep rewriting the old ones. Every round they get a bit more meta: more gates, more memory, more state, more tests.

Two things before I go further.

I am new at this. So is everybody. Anyone presenting themselves as an authority on agentic development in 2026 is selling something. It is probably a course.

I am also making mistakes right now that I will find embarrassing by Christmas. I will point at a few on the way past.

Three eras, quickly

Scripts. You write code. It does exactly what you said, forever, until the world moves underneath it and it breaks loudly. Deterministic and brittle.

Prompts. You describe what you want. You get something in the neighborhood. Flexible and unrepeatable. You cannot hand a prompt to a colleague and expect your result, because half of it never left your head.

Skills. You write a contract. What this is for, when to reach for it, where the data lives, what has already gone wrong, what to do when it goes wrong again and what finished actually looks like.

A skill is the first thing in this space that is durable and adaptive at the same time. That combination is the entire point.

What one actually is

Strip away the platform differences and every agent skill I have written has the same skeleton.

A name.

A description packed with the phrases a human would really say.

A body in plain prose. Goal, inputs, sources, procedure, output shape, failure handling, refusal conditions.

Optionally, code. Scripts the agent runs instead of improvising.

That is it. Markdown and intent. The most valuable professional asset I own is a folder of text files, which I find funny and slightly alarming.

The format is not the interesting part. The interesting part is which ones are still alive after a year.

1. The description is a router, not documentation

Classic first-skill mistake. I made it 40 times.

I wrote lovely descriptions. “Analyses consumption trends and produces an executive summary.” Accurate, tidy, never fired once, because I have never said that sentence out loud in my life.

What I actually type is “why did that drop”, or “gimme the deep dive”, or “what happened last month”.

The description is not there to explain your skill to a human. It is there so a model can match a messy real sentence to the right tool at the exact moment you are tired and typing badly.

My live skills have descriptions stuffed with my own ugly phrasings, including the lazy ones and the half sentences.

They read worse. They work.

Write the description last, after you have run the thing manually ten times. Harvest the actual words you typed.

2. Encode the failures, not the happy path

This is the one that changed how I build.

I have a skill that pulls records out of an internal system. First version described the query. Clean, short, correct.

Then I ran it from a hotel and got a 403. The agent, being helpful, concluded I lacked permission and wrote me a polite paragraph about contacting my admin.

I did not lack permission. That system sits behind an IP allowlist and I was on hotel wifi.

Ouch.

So I opened the skill and added a section that says: if you see this exact error, it is the network path. Not the token, not the user’s access. Say “get on the VPN”. Do not send them off to request something they already have.

Now every mature skill I own has a section like that. In the good ones it is longer than the instructions. They read like maintenance logs.

This API returns an empty set instead of an error when the filter is wrong. This file is encrypted at rest so the normal reader will not open it, use the other path. This number always looks broken on the 1st, that is expected, here is why. If the pull returns zero rows, do not publish zeros. Restore last known good and label it clearly.

A skill is where you keep the scar tissue.

Everyone writes about capability. The value compounds in the failure knowledge. Capability arrives free with the next model. Scar tissue you have to earn one wasted afternoon at a time.

3. Push determinism down, keep judgment up

Early on I let agents do the arithmetic and the file writing inline. It mostly worked, which is worse than failing, because “mostly” stays invisible until somebody makes a decision on top of it.

The rule I landed on:

If a step has exactly one correct output, it belongs in code. If a step needs someone to read the situation, it belongs in prose.

So my heavier skills are now thin coordination layers over real scripts. Fetch, transform, validate, render, all code. What matters, what to flag, how to say it for this audience, that stays with the model.

Nice side effect: when something breaks you instantly know which half broke. Deterministic failures throw stack traces. Judgment failures produce confident nonsense. Completely different repairs.

The skill is the contract between the two halves.

4. Make it hand you a receipt

The most useful line I ever wrote into a skill was not an instruction. It was a required output.

Roughly: always report how many records matched out of how many expected, the date of the newest data point, which sources were unreachable and anything missing.

Before that, output looked finished whether or not it was. A report with three items missing looks exactly like a report with nothing missing. That is the specific trap that makes people quietly stop trusting agentic output forever.

Now every run ends with its own receipt. 25 of 25 matched. Data through last Friday. One source unreachable.

I read the receipt before I read the content. If the receipt is wrong the content does not matter.

Confidence in these systems does not come from them being right. It comes from them being legible when they are wrong.

5. Write down what it must refuse

Every skill that touches other people carries an explicit boundary.

Never send anything outbound without showing me the exact text and the exact recipients first. Never invent a record you could not retrieve. If a source is unavailable, say so and stop. Do not approximate.

That last one earns its place. An agent with a hole in its data has two options. Tell you about the hole, or smooth it over with something plausible. Left alone, models are agreeable. Agreeable means smoothing.

Skills that write their own memory

Here is the thing that took me longest to understand.

A context window is not memory. It is a desk. Everything on it gets swept off at the end of the session. The next one starts clean, with no idea what you decided last time.

Memory is a filing cabinet. Nobody builds the cabinet for you.

So my skills write files.

A plan file. For anything multi step, the skill writes a plan to disk early and updates it at milestones. It survives the conversation being compacted. It lets me audit the reasoning afterwards instead of trusting a summary. And when a run dies halfway, the next one picks up from a real artifact.

State carried between runs. I have a tracker that regenerates weekly. First version threw away every note I had added, every single week, because regeneration meant starting clean. Now the skill writes a small state file keyed by item id. The next run reads it back and re-attaches my notes to the rows that still exist. The agent forgets. The file does not.

Append only logs. Comments and decisions get added, never rewritten. History that can be edited is not history.

Last known good. When an upstream source returns nothing, the skill does not publish zeros. It restores the previous good snapshot and labels it as stale with a date. Publishing zeros is how you get a very calm meeting about a catastrophe that did not happen.

Deferred decisions, with reasons. When I skip something, the skill records what I skipped and why. Six weeks later I do not re-litigate it from scratch, which is otherwise exactly what I do.

None of this is glamorous. It is the difference between an agent that impresses you on Monday and one you still rely on in November.

The skills that manage the skills

This is where it got genuinely interesting and where I have wasted the most time.

Once you pass roughly 20 skills, the library itself becomes the problem. So I started building skills whose subject is other skills.

A skill that writes skills. Give it a rough workflow and it produces a properly shaped one: gates, refusal conditions, required self report, state handling. The point is not saving typing. It is that every new skill is born with the good habits already in it, instead of me remembering to add them on a good day.

A skill that finds candidates. It mines my own history for work I keep re-prompting and proposes turning the repeats into skills. It surfaced things I had manually re-explained eleven times without noticing. That is the Tuesday from the top of this article, automated, which is either elegant or a bit sad.

Orchestrators. One entry point that resolves scope, calls the specialist skills that are actually relevant, assembles the result, checks it and reports the gaps. The orchestrator’s real product is the gap list. Anyone can assemble a document. Telling me precisely which five things are missing and unverified is the part that saves me from walking into a room underprepared.

Gates. My favorite one runs a validation loop where each stage can fail the whole build. Static checks, then logic, then geometry, then a visual check, then performance. Nothing ships if a gate fails. Turns out “the agent checked its own work” only means something when checking has teeth.

Drift detection. Something that watches for upstream changes to shared skills and asks me, per item, whether to take the update. With the reason recorded either way.

Honest bit: meta skills are also where most of my mediocre ones live. I have built beautiful abstractions for things I ran twice. The rule I try to hold now is that a skill earns a meta layer after it has hurt me three times, not before.

What I am probably getting wrong

In no particular order, my current suspicions.

I have too many. Discovery is now its own problem. I have descriptions quietly competing for the same trigger phrases.

I over engineer early. I keep adding structure to things that needed a paragraph.

I barely test. Most of my skills have no test at all. The ones with real gates are the exception rather than the standard (i will go to developers hell for this).

I have no reliable way to notice when a skill silently degrades. It does not break. It just gets a bit worse. Then I find out from a person, which is the wrong sensor.

If you have solved that last one properly, I would genuinely like to hear about it.

Where I would start

Pick the task you have already done manually five times and resented every time.

1. Do it manually once more, saving every instruction you type.
2. Write the goal, the sources, the output shape.
3. Add the failure you already know about. There is always at least one.
4. Add a required self report.
5. Add one thing it must never do.
6. Move the boring deterministic parts into a script.
7. Write the description last, in your own ugly real words.

It will be worse than mine at first and better than any prompt you have ever written, because it is the only version that still exists next month.

Scripts told computers what to do. Prompts told models what we wanted. Skills tell agents how we work.

The third one is the one that compounds.

TL;DR

A prompt is a performance. A script is brittle. A skill is a contract that survives a changing world.

Five things the survivors do:

1. Description written as a router, in the ugly words you actually type, not as documentation.
2. Failures encoded, not just the happy path. The skill is where you keep the scar tissue.
3. Determinism pushed into code, judgment left in prose. You want to know which half broke.
4. A receipt on every run. Legible when wrong beats confidently finished.
5. An explicit refusal condition, because models smooth over gaps unless you forbid it.

Two things almost nobody writes about:

A context window is a desk, not a filing cabinet. Make skills write plan files, carry state between runs, append rather than overwrite and fall back to last known good instead of publishing zeros.

Past about 20 skills, build skills about skills. One that writes new ones with the good habits baked in. One that mines your history for what you keep re-prompting. Orchestrators whose real output is the gap list. Gates with teeth. But earn the meta layer after something has hurt you three times, not before.

And: I have nearly 100 and only about 30 earn their keep. I am figuring this out in public and I am certainly wrong about some of it.

Now go and do it. I did most of the work.

Open whatever you use. Claude, ChatGPT, Copilot, the thing your employer gave you.

Paste this article in. Then paste this underneath it.

You just read an article about what makes an agent skill survive.

Build me one. The task is: <the thing you keep redoing by hand>

Apply every rule from the article.

1. Write the description last, as a router. Use the ugly phrases I would
   really type, not a tidy summary. Ask me what I type if you do not know.
2. Ask me what has already gone wrong with this task. Write those failures
   into the skill with the exact error and the exact fix. Not the happy path.
3. Split it. Anything with one correct answer goes into a script. Anything
   needing judgment stays in prose. Tell me which is which and why.
4. Require a receipt on every run: what matched out of what was expected,
   how fresh the data is and what was unreachable.
5. Add one thing it must refuse to do. Add one thing it must never send
   without showing me the exact text first.
6. Make it write state to a file, so the next run knows what this run decided.
7. Add gates that can actually fail the build. Not "check your work".
   Named checks, each one able to stop delivery on its own.

Then, before you hand it over, tell me what is missing. At least three
specific things. "It looks good" is not an answer, it is a skipped check.

Ask me anything you need. Do not guess.

Answer its questions honestly, especially the one about what has already gone wrong. That is the part that makes the skill yours instead of generic.

It will get the first version wrong. Fix it and write the fix back into the skill.

That is the whole loop.