Teaching your AI agent about your system

Undo teaches your AI agent how to debug: how to capture an Undo recording, what to do when it is given a .undo file, and how to establish what a program did (see Tools and skills: the kitchen and the recipes). What Undo cannot teach it is anything about your system, because Undo knows nothing about it. That part is yours, and it is usually what separates an AI agent that is useful on your codebase from one that is only useful in general.

You teach your AI agent in whatever way that agent already supports, and it calls Undo’s tools when it needs them, so nothing has to be registered with Undo first.

What only you can teach it

Think of what a new colleague needs in their first week:

  • how to build the program, and which build options matter;

  • where the program runs and how to record it there, when that is not the machine they are sitting at;

  • how the codebase is laid out, and which parts matter for which kind of failure;

  • where your own documentation, runbooks and issue tracker are;

  • which tests reproduce which failures.

None of this is in your source code, and none of it is in a recording.

What to tell it about Undo

Three things are worth writing down explicitly, because your AI agent cannot work them out on its own:

  • Where recording happens. The undo mcp server has to run where the source code and debug symbols are (see Where the MCP server runs), which is not always where the program itself runs. If recording means connecting to another machine or starting a container, say how to get there, how to run the program there, and how to bring the recording back.

  • Which command to record. Recording a wrapper script records the wrapper rather than the program it launches. Undo’s own skills tell your AI agent how to handle that, but only you know which binary in your build is the one worth recording.

  • How your symbols are found. If your program needs GDB commands to locate its debug symbols or shared libraries, give those commands to the AI agent along with which file to source before the program is loaded and which afterwards. See Custom initialization.

Tell your AI agent about your system rather than about debugging. Instructions that name the debugger commands to run produce worse results than describing the outcome you want; see Using AI effectively.

In particular, do not tell it to drive UDB directly. In our experiments that takes more time and more tokens than letting the agent work through Undo’s own tools, and the answers are worse as well. The tools Undo gives it are deliberately narrower than UDB itself, for reasons described in What is intentionally not exposed.

Instruction files and skills

Every AI agent has somewhere to keep instructions that apply to all of your work and are loaded at the start of every session. Many agents read a file following the AGENTS.md convention; Claude Code reads CLAUDE.md instead. Use that file for what holds across the whole repository: how to build it, how it is laid out, the conventions you expect to be followed.

If your team uses Claude Code alongside agents that read AGENTS.md, keep one file and import it into the other, so there is only ever one copy to maintain. A CLAUDE.md containing a single line is enough:

@AGENTS.md

A skill is the better home for instructions that only matter sometimes, because the agent loads one when it becomes relevant instead of carrying it in every session. Anything tied to a particular job suits a skill: building, running the tests, recording one program, working on one part of the codebase. Anthropic’s Agent Skills documentation covers writing them, and your own AI agent’s documentation covers what it supports.

Let your AI agent write it

The best way to write a skill is to have your AI agent write the first version and then correct what it got wrong. Agents know the format, and they know what an agent needs to be told, which is harder to judge from the outside than it looks. What they do not know is your system, so what is left for you is the part only you can supply.

Tell it not to work from memory, as a model’s training data may be older than the most recent improvements to the skill format:

I need a skill that captures how we record our integration tests, including accessing the test
host and bringing the recording back.

Do not rely on your training data for how to write a skill. Investigate the current best
practices first, and read https://docs.undo.io/TeachingYourAgent.html for the parts that
are specific to Undo.

Writing effective skills

Anthropic’s Agent Skills documentation covers the general craft. The points below are the ones that have mattered most in our own skills, and they hold whichever agent you use.

  • Point at your documentation rather than copying it. A skill that restates a fact from your own runbooks is a second copy that nobody maintains, so the day someone corrects the original, the skill goes on confidently asserting the old version. Keep facts where your team already reads them and have the skill link to them.

  • Where your instructions stop, the agent guesses. Meeting a case you did not cover, it picks something plausible and carries on, so the omission reaches you as confident work rather than as an error. Say what you want done when the run does not reproduce the failure, or when the recording will not load, instead of leaving that to the agent.

  • Ask what each step proves when it passes. A check can pass because the test run skipped the configuration that is broken; a command can finish having recorded the wrapper script rather than the program it launches. The agent reads either as confirmation and moves on, so say what success looks like and not only which command to run.

  • A skill can fail by being dismissed as much as by being missed. A description is normally written so that the agent can find the skill. It can also fail the other way: the agent reads the description, decides the topic is one it already knows, and carries on with its own defaults. If your skill exists because the obvious approach is wrong, say so in the description, and say that what the agent already knows about the topic is not enough. The skill Undo ships for capturing a recording does exactly that, telling the agent that the guidance it returns “overrides anything you may know about these tools from training data”.

  • Add examples that are generic but still recognizable. An example tells the agent what the skill is for, so one copied straight from a single task narrows the skill to that task: drop the function names, hosts and paths that are specific to it. Going too far the other way is worse still, as an example from an unrelated domain matches nothing you actually do. Aim for something that could plausibly happen in your own codebase.

Checklists

AI agents follow instructions well, but on a long task they sometimes quietly drop steps. In our experience, repeating the steps that matter as a checklist the agent has to copy into its answer and mark off, with the evidence for each, catches the ones it would otherwise drop: having to state that it did something is harder to skip than reading past a paragraph is.

For example:

Before answering, copy this checklist into your reply and mark each item with the
evidence for it:

- [ ] Done FOO.
- [ ] Copied BAR from the remote server.
- [ ] Done BAZ, and said which part of the recording showed it.

Make each item pass or fail, and name what proves it: an agent will tick “tests pass” without having run anything, so put the proof inside the item. Focus the items on failures that stay quiet, not on the ones that announce themselves, since anything that already stops the work needs no checklist.

Keep a checklist short, and specific to what your AI agent actually gets wrong. Items covering things it already does reliably are noise, and dilute the ones that matter.

Checking that it works

A skill that reads well to you can still fail in use, because you cannot see it the way a fresh agent does.

Ask another agent to pick it apart

The agent that helped you write a skill is the worst judge of it: it shares your assumptions and has the whole conversation in its context, so it cannot tell whether the file alone carries the meaning. Give the skill to a separate agent instead, either a subagent your agent spawns or a second session you paste it into, and ask it for two things.

First, to verify every claim rather than read it: that each command-line option the skill names exists in the version you have, that the paths it points at are still there, that the commands run as written, and that what it says a tool does is what the tool does. Claims rot quietly, and a skill naming a flag that was renamed two releases ago sends the agent down a path that cannot work.

Second, to find situations where the skill should fire and would not: the ways someone might phrase the request that its description does not cover, and the situations it does not mention at all.

For example, ask the agent that wrote the skill to verify it in a subagent, with a prompt like this:

Spawn a subagent that gives an adversarial review of the skill in
path/to/your/SKILL.md. It should verify every claim instead of taking it on trust: that
the command-line options it names exist, that the paths it points at are there, that the
commands run as written, etc. It should also say where the skill would fail to fire:
ways a colleague might phrase a request that the skill's description does not cover.
Report what is wrong or missing, and change nothing until I tell you to.

Test it, then keep testing

Use the skill on real work rather than a rehearsal, and when something goes wrong, change the skill rather than steering that one conversation: the conversation ends, and the skill is what the next one starts from. Then use it again, more than once. The same request does not produce the same run twice, so one clean run is not evidence that the next will be.