Agent instructions are code, and they rot

One of my skills existed in two versions. Nobody had chosen between them. My oldest repository had eleven of twenty-two.

Neither of those was a decision. They were what happens when you keep files in sync by copying them.

If you work with coding agents, you probably have a folder of instructions somewhere: how this project runs its tests, what the review checklist is, how a feature gets broken into tickets. Different tools call them different things. What matters is that they are durable prose that changes how the agent behaves, and that you want the good ones in every project you work on.

So you copy them. A new repository gets set up, you copy the folder from the last one you set up, and you carry on. It works, right up until you have three repositories and a year of edits.

I edited one skill in one repository, in the middle of doing something else, because it was wrong for what I needed at that moment. That edit was correct. It also never went anywhere.

Months later there were two versions of the same file in two repositories, both plausible, both in use, and no record of which one had won. Not a merge conflict, not a broken build. Two answers to the same question, and no way to tell which was the current one, because neither had ever been proposed to anything.

The second one is worse, and it is invisible until you count.

My process was copy from the last repository you set up. That sounds fine. Follow it forward: every new project starts from the most recent state, so improvements propagate downstream and never upstream. The oldest repository is the one that receives nothing, forever.

It had eleven of twenty-two. It was not broken. Nothing errored. Its agent was simply working from an eleven-month-old understanding of how I work, and had been for months, and I had not noticed because there is no signal for a file that never arrived.

Read those two again without the word "agent" in them. Uncoordinated divergent edits with no authority. A distribution model where the oldest consumer starves. These are the exact failure modes that version control and shared libraries were built to prevent. We solved this. It has been solved for decades.

I walked back into it anyway, and I think I know why: the files are prose, so they do not feel like code. Nobody reviews a markdown file that tells an agent how to write a commit message. Nobody asks which version is canonical. It reads like documentation, so it gets the treatment documentation gets, which is none.

But it is not documentation. Documentation describes behaviour after the fact. These files cause behaviour. Something that changes what your tools do to your codebase is code, whatever it is written in, and it needs the things code gets: one source, a history, and a reason recorded for every change.

So: put them all in one place. That is where I started, and it is only about eighty percent right.

Two of my skills genuinely cannot live in a shared package. One reports what is currently running and what to pick up next. The other closes out a working session. Both of them have to know things that are only true in one project: which services are deployed and where, whether the repository is the thing that runs or just the thing that gets copied to the machine that runs, where the real status of the project is actually written down.

Those two are different in every repository, and their divergence is correct. If I had centralised them I would have had to write a shared file full of conditionals about machines it cannot see, which is how a good abstraction becomes a bad one.

If it has to know something about the project in order to be useful, it lives in the project. Everything else lives in one place.

Nineteen of my twenty-two passed that test and moved into a single package with a changelog. The other two stayed where they were, and now they are supposed to be different, which is a much better state than being accidentally different.

The rule is easy to state and it is the whole job. Every file makes you ask the same question: is this identical everywhere because it truly is universal, or is it identical everywhere because nobody has yet noticed it should not be? The first is a library. The second is a copy waiting to drift.

Most of these skills started as mattpocock/skills, vendored and then adapted. The counting problem is mine; the starting point was his.

← Back