Every morning the agent starts from zero. It has no memory of yesterday’s session, no idea which folder holds the data, no sense that one script is safe to run and another costs money. For the first few months I compensated by typing the same context into every conversation. The results were uneven, and the failures had a pattern: the agent did something reasonable that I had told a previous instance of it never to do.

The fix was boring. I started writing the rules down in files the agent reads before it starts. Claude Code calls them skills: a Markdown file with a short description of when it applies, and a body that loads into the conversation when a task matches. I now have about a dozen. This post is about what goes in them, what I got wrong, and why I think of them as specs for a colleague who forgets everything overnight.

What a skill file is for

The temptation is to write a tutorial. That is the wrong genre. The agent already knows what Zotero is and how a Hugo site builds. What it does not know is anything about mine: which folder, which server, which flags, which of my preferences are hard rules and which are taste.

So the files are mostly tables of facts and short imperative rules. The one for this website, which is public in the site’s repository, has sections for the dev server and git, the migration steps for an old post, the frontmatter format, the rules for the hidden section of the site, and a list of design preferences. A sample of the kind of line that earns its place:

Each of those is a mistake the agent made once. The skill is where the mistake went so it would not be made twice.

The three sections that matter most

After rewriting these files several times, three sections have proven to carry most of the value.

Where things live. Paths, server names, which Python environment, which script, which account. The agent spends a surprising share of its effort rediscovering this, and it sometimes rediscovers it wrong. A table of locations at the top of the file removes the search. The literature skill, for example, lists the reading paths in order of preference: the Zotero MCP tools first, the local read-only API second, a read-only query on the SQLite database third. It also says which of these works while the app is closed, because that is the thing the agent otherwise finds out by failing.

Hard rules, with the why. A rule without a reason gets rationalized away the first time it is inconvenient. “No paid API call without approval” was not enough. The rule that holds says: before any paid call of any size, state the batch name, the run count, the estimated cost per provider, the spend so far and the balances needed, then wait for an explicit yes in the conversation. One approval covers one named batch. A meeting note, an earlier approval, or headroom under a cap is not approval. The reason is written next to it: balances have run out mid-batch before, and a run that dies halfway is money spent on nothing. The agent follows a rule with a story behind it far more reliably than a bare prohibition.

What has not been verified. This is the section I did not expect to need. When I write a skill, some of it is tested and some of it is what I believe to be true. The agent cannot tell the difference, so it treats everything as fact. Now each skill ends with a “not verified when this skill was written” list: a deploy that was never tested, a script that was only checked with --help, a README that is known to be stale. The agent reads it and hedges accordingly. More than once it has flagged a step with “the skill says this is unverified” and asked before proceeding, which is exactly right.

Rules the agent wrote itself

The best entries did not come from me. They came from the agent’s own post-mortems. The literature skill has a paragraph about a sync failure that silently blocked every upload to the Zotero cloud for nine months. The cause was that items written directly to the database had been given keys using characters outside the allowed set. Nobody noticed until an unrelated sync error named one of the keys. The agent diagnosed it, wrote the query that finds such keys, wrote the fix, and then wrote the whole episode into the skill with the date. The next agent that touches the database reads it before writing a single row.

I have come to think this is the real loop: not prompt, run, correct, but prompt, run, correct, and then edit the file. If the correction stays in the chat it is gone tomorrow. If it goes in the skill it is there for every session after.

What I got wrong

Too much in one file. Early versions were long and the agent’s context filled with material it did not need for the task at hand. The fix was to split: a short skill body with the rules and the reading order, and a separate reference file with the field IDs, collection keys and SQL recipes, which the skill tells the agent to read only before a write. The agent loads what it needs.

Status in the skill. I kept putting “current state of the project” into the file, which meant it was out of date within a week and the agent acted on stale facts. Now the skill says explicitly where status lives, in a dated note or a decision log, and that it should be read there, never from the skill. The skill holds stable facts only.

Conventions I never wrote down. The agent’s writing kept drifting into phrasing I would never use, and I kept correcting it by hand. Once the style rules were in a file the drift mostly stopped. The rules are plain: no em-dashes, no “delve” or “leverage”, no emojis, quote sources verbatim, never print the contact address as text. The agent cannot follow a preference it has not been told.

The research case

I cannot write about my doctoral research here, so I will describe the shape of the skill without the content. It covers a study that involves paid API calls, a small web application with a database, a set of de-identified documents, and a team. The skill has a table of where every piece lives, a numbered list of standing rules, and the exact commands with the exact flags that work, including which ones write to production and must not be run without a word from me in the current conversation.

The standing rules are the heart of it. Several concern money, as above. Several concern people: nothing goes to the team without my say-so, each time; certain people are never contacted by the agent at all; certain mappings are never displayed. One concerns privacy: identifiable originals exist in one secured folder and the agent works only from the de-identified copies.

None of these are things an agent would infer. All of them are things it now does without being told, because they are in the file.

Why it works

A skill file is a spec written for a careful colleague who starts from nothing every morning. That constraint turns out to be a good discipline for the human too. Writing “never run this script without asking” forced me to decide which scripts those were. Writing the “not verified” list forced me to admit what I had not tested. Writing the reasons next to the rules made some of the rules look thin, and I dropped them.

The agent is a reader of my process documentation. It is the most literal reader I have ever had, and the first one that reads all of it every time.