Try this if
- The words skill, rules file or board don't mean anything to you yet.
- Your AI agent keeps forgetting what you told it last time, or reopening a choice you'd already made.
- Skip it if you already keep your project's rules, open work and decisions in files the agent reads.
- What comes back is the shape of each file and when your agent reads it.
Your first session with an AI agent, an AI that can read and change the files in your project and run commands rather than only answer in a chat, is the easy part. You describe what you want, it builds it, you use it, and it works. A few sessions in, the trouble starts. It forgets what you told it last time. It redoes something it already finished. It makes a choice you'd already ruled out, and it makes it well, so you don't notice until it's shipped.
None of that is the model being bad. It's two facts meeting. The agent starts each session blank, and if you run a project without reading the code, because you can't or because reading it would cost more than the project is worth, nothing in the project remembers the argument you already had, and you pay for it again every time it comes back.
The memory and the judgment have to live somewhere else. They live in a small set of plain text files inside the project, and the agent reads them before it does anything. The shape of those files was learned by getting it wrong. One project kept all its decisions in a single file, and following one pointer into it came to cost about 170 times the thing being looked up. The fix was one small file per item with a lean index on top, and the board and the decisions log below both follow that shape.
A skill is a saved prompt with a name
Start with the piece you can see on this site. Every recipe here is a skill, and several of them install one of the pieces below. A skill is a prompt that has been written once, saved into a file in the project or your user folder and given a short name. In the chat, you type a slash and the name, say /mine, followed by whatever the prompt needs, and the agent reads the saved prompt and does what it says. Instead of explaining, every time, how you want a plan reviewed or a source read, you type the name and the explanation is already there.
The file is plain text in a folder the tool knows about. The tool is the program you run the agent inside, Claude Code or one of its equivalents, and when a session opens it looks in that folder and learns every name in it. The file holds the prompt with a name and a short description above it. Anything you find yourself saying to an agent for the third time is a candidate to become one.
A rules file is what the agent reads first
Every tool that runs an agent looks for one particular file in your project when a session opens, and if it finds it, it hands the whole thing to the agent before your first message. Claude Code looks for a file called CLAUDE.md. Other tools look for their own names, and AGENTS.md is the name that's becoming common to most of them. That file is the rules file, and it's the closest thing the agent has to a memory.
It's a plain text file, and what goes in it is what you'd tell a capable new hire on their first morning.
- What this project is and what it's for.
- The words it uses and what they mean.
- Where things live, so the agent doesn't go looking.
- The commands that build the work and check it.
Then comes the part that grows for the life of the project, a list of what agents have got wrong here before, with the failure written next to each rule so the next agent knows why the rule is there.
It's short on purpose, because every line in it is read at the start of every session. Beside it sits a folder of smaller rule files, each one tied to one part of the project. A rule about putting the site live, the deploy, is read only when the agent is working on that, and the rest of the time it costs nothing. That's how the always-read file stays short while the rules keep growing.
If you use more than one tool, don't write the rules twice. Put them in AGENTS.md, and make CLAUDE.md a single line that says to read AGENTS.md. Any other tool's file is the same single line. Whichever tool opens the project, the agent inside it gets the same rules, written once.
A board is one row per piece of open work
The board is a single plain text file holding one table, with one row for each piece of work that isn't finished. Each row has a lane, a word that says whether the item is being worked on now, is next, is waiting on something or is parked, and a number that orders the rows within a lane. Sort the rows by that number and you're looking at the plan for the project. There isn't another one anywhere, and there's nothing to install, because a text file can hold a table.
The agent reads the board when a session opens, to know what to pick up, and moves rows when a session closes. You read it to see where things stand, and you add a row when you want something done. A row is one line. Everything needed to act on it, its current state, its next step and its open questions, lives in a card of its own, one small file per row in a folder beside the board, and the row links to the card. The board stays thin so that reading it costs almost nothing, and the card can be as long as the work needs.
A decisions log is why things are the way they are
Every significant call gets a record, one small file, and the record says what was chosen, what the alternative was, why and what would reopen it. You make the call, in the chat, and the agent writes it down. Each record gets a short code that never changes, such as D-041, so any other file can point at it and the pointer never breaks even if the decision is later reworded.
A rule is an instruction. The agent obeys it without knowing the history. A decision is a record. The agent reads it only when it is about to touch the thing that decision governs, so that it doesn't reopen an argument that was already had. A decision produces a rule when the choice isn't visible from the work itself. If you decided against a database, nothing in the code says so, and a rule has to.
An index file sits beside the folder, a list of every decision with a line each, and at its top sits a short list of the ones that still bind. That short list is the only part the agent reads automatically.
A retro is how one session reaches the next
When a session closes, the agent writes a retro, a short dated note in a folder of them. It says what got done, what broke and the first thing to do next time. When the next session opens, it reads that note along with the rules file and the board, and the opening and closing routines that read and write it are a recipe of their own. It's the one record written for the next session to read, which is why skipping it costs more than writing it.
It's also your window. You don't read the code, but you read the note, and the note is written so that a person who wasn't there can tell what was done and what to check.
A check is a rule that can go red
The last piece is a set of small programs that run at a fixed moment and stop the work when something is wrong. One runs before a site is built and refuses to build it if a page cites a source that doesn't exist. One runs when work is about to leave the machine and refuses to let it go when a page asks for an image that isn't there. Going red means the step stops and the reason is printed. A rule that ends in a check is worth more than a rule that ends in advice, because advice fires on the agent's attention and a check fires whether the agent is paying attention or not.
Which files load, and which wait
The files fall into two kinds, and the test for which is which is whether the agent can know it needs a file before reading it, which Write AGENTS.md rules that survive the session explains. A rule about the deploy can wait, because the task of putting the site live announces itself. A rule about punctuation can't, because no task ever announces that it needs one.
So some files are read every session, no matter what. Those are the rules file, the board, the newest retro and the short list of binding decisions. They stay small because every line in them is read at the start of every session.
Other files are read on demand, a decision, a rule tied to one folder or a work item's own card. They can be as long as they need to be, but each one has to be its own file, so that a session reads exactly the one it needs.
The board is a table because the thing reading it is a machine and a machine wants one row per item. A decision is a document because it has to carry a reason, and a row can't.
Names follow the same logic. A date leads the filename when the order matters, as it does for retros. The short code leads it when the thing will be pointed at, as it does for decisions, because a title can change and a reference can't.
How to check the work that comes out of these files without reading the code is its own piece, Judge your AI agent's work by using it, not by reading the code.
What you get and what you don't
You get a project that remembers what it decided and what it's working on, however many sessions it takes. You don't get protection from a wrong rule. The agent obeys a bad line in the rules file as faithfully as a good one, so the files are only as right as what you put in them.
Start with the rules file. Make it one line long today, the first thing your agent got wrong, and let it grow from there.