I think onboarding a coding agent should be work you do once. If I have already explained how a project works, I want the next agent to pick up that explanation instead of making me write it again. Connecting a tool gives the agent access to it, but I still need a way to tell it how we use that tool in this project.
This weekend I added an onboarding Pack to a shared Sirro library. The starting point was simple: open a new chat, ask Claude to use the Sirro onboarding Pack, then ask it questions about Sirro. Instead of explaining the product through another long message, I could give the agent a named piece of work to read.
That made me think about what I actually want to keep between sessions. The code is part of it. The explanation of how to work with that code is worth keeping too, especially when someone else joins the project.
The explanation belongs with the work
When I build software for clients, there are decisions I end up explaining repeatedly. A piece of code can be perfectly readable without telling the next person why I chose it or what I expect them to leave alone. An agent can inspect the repo and still miss the reason behind a decision.
I want to save that explanation while it is still clear. If a conversation finally gets the agent working the way I need, the useful instructions should be easy to pull into the next conversation. Having to search an old chat and reconstruct them defeats much of the reason for saving the work in the first place.
For Sirro, I started with its own onboarding. The request I gave someone to try was:
Use the Sirro onboarding Pack from our team. How does Sirro work?
I like that the developer can start with a question. They should be able to ask how to use the library through the agent they are already working with. They shouldn't have to become an expert in my dashboard before they can retrieve something useful.
The same idea could apply to onboarding a consultant to a project. You have already done the work of explaining how the team builds. Give that explanation a name and keep it somewhere the next person and their agent can use. You can improve it as the project changes, rather than maintaining a slightly different introduction in every chat.
Keep the useful introduction small
I wouldn't put the whole project history into an onboarding Pack. I want enough to start working correctly and know where to look next. Loading months of conversation into a new session would bring back much of the noise I was trying to leave behind.
A useful introduction should answer the questions people actually ask when they join. If I have to correct the same misunderstanding every time, that correction belongs in the introduction. If an explanation only mattered during one debugging session, I would leave it with that work until there is a reason to reuse it.
There is a maintenance cost here. Saving an introduction doesn't keep it true forever. When the project changes, someone has to update it. I would rather maintain one shared explanation deliberately than let old instructions survive unnoticed in several different tools.
I also wouldn't assume that retrieving a Pack means the agent understood it. I would ask it a concrete question about the project and inspect the answer before handing it a bigger task. A named document gives us something to check against when it gets the answer wrong.
This is the part of agent memory I want to get right: the time I spend explaining my work should improve the next session. I should be able to bring in another developer, start a new chat, and build on the explanation we already worked out. The onboarding itself becomes reusable work.
Top comments (1)
The maintenance paragraph is the part I'd expand. A saved introduction fails quietly: nothing breaks when a line goes out of date, the agent just follows it.
Your last point suggests a fix. If you already ask a concrete question to check the agent understood the Pack, those questions could be kept next to it with the expected answers, and run again whenever the Pack or the project changes. A wrong answer then points at a stale line, not at the agent.
How do you decide when a correction moves from one debugging session into the shared introduction? After the second time you have to repeat it, or earlier?