Yesterday I wrote about three ways to keep a rule on a codebase an agent writes. Generate the code from a schema, so the mistake cannot be written. Put the rule in the linter, so it cannot be committed. Or write it in a document and hope it gets read.
Those all describe what the code should look like. I also have rules about how the work gets done, and those had nowhere good to live until this week.
There were four places to put an instruction for an agent, and each one fails in its own way.
A project file the agent always reads. Every agent tool has one. It is loaded on every request, which means every word in it costs something every single time, so it stays short and it stays general. A twelve-step procedure does not belong in a file that is read a thousand times a day.
A document in the repository. Costs nothing until somebody opens it. The catch is that the agent has to decide to go and look, and an agent that does not know a document exists will never look for it.
A saved command you type. Reliable, and it puts the burden on you. You have to remember, at the right moment, that the procedure exists. Procedures get skipped at exactly the moment nobody is thinking about them.
A tool the agent can call. A tool gives an agent a new ability. It does not tell the agent how you want that ability used. Being able to commit and knowing how you want commits handed over are separate problems.
So a long procedure had a choice between being expensive, being invisible, or waiting on somebody's memory.
A skill is a Markdown file with two fields at the top, a name and a description. The description sits in the agent's context all the time and costs about a line. The rest of the file only loads when the work matches that description, so the instructions turn up at the moment they apply instead of when someone remembers to go looking. The format is an open standard published in December, and tools from several vendors read the same file.
The top of a SKILL.md file
---name: cicd-manifestdescription: Hand work to the commit agent. Use whenever you have finished a change and need it committed, or you have reached a natural commit point. Covers what a manifest must contain, the pathspec rules for a shared working tree, and how to confirm the commit actually landed.---The description is doing two jobs. It is the advertisement, so it has to name the moments the file applies to, and it is the whole cost, so a repository can hold thirty of these and pay thirty lines. Write a vague description and the file never loads. Write an accurate one and it loads at the right time without anyone asking for it.
Several agents work on this codebase at once, each in its own session, all editing the same working directory. One of them does every commit, and everybody else sends it a request naming the files to stage and what was checked.
That request has to be exact, and the reasons are all things I learned by getting them wrong. Name a folder instead of the files inside it and you can stage deletions you never intended. Move a folder and forget that a move is a delete as well as an add, and the same work ends up in two places. Trust a reply saying it is done instead of checking the log, and the occasional lost request goes unnoticed.
None of that is hard. It is just a dozen small facts that took months to accumulate, and they were spread across a dozen notes, reassembled from fragments every time. They are one file now, and it arrives on its own when an agent is about to hand off a commit.
This is the part to be clear about before adopting one. A skill is a prompt. It puts the right instructions in front of the agent at the right moment and it raises the odds. It cannot stop anything.
So the question for any rule is whether breaking it is survivable.
If a rule must hold every time, it needs something that fails. A type, a test, a check in the build. Those do not care whether anyone read the instructions, and that is the entire reason to prefer them.
If a rule is about how to go about something, a skill is the right home, because there is nothing for a check to inspect. Nobody can write a test for how a request should be worded.
The way I sort them is to ask whether the rule has a file behind it. Rules about the shape of the code do, so they go in the linter or the build. Rules about how work is handed over do not, because until the work is handed over there is nothing to look at, and by then it has happened.
I am one person running several agents that write and ship code to production, with no colleague to read a diff. Everything that can be turned into a check that fails has to be, because that is the only kind of rule that survives me not paying attention.
A skill does not get me that. What it gets me is one specific tax gone. The procedure used to be reassembled from scraps on every handoff, slightly differently each time. Now it arrives whole, at the moment it applies, without me remembering to send it.
That is worth the twenty minutes it took to write, and it is not a substitute for a check that fails.
Remote, Pacific time, full-time or contract. Get in touch.