The problem: unfamiliar repos
With AI in the toolbox, my company has been nudging everyone away from sticking to a single role — backend engineers pick up frontend tasks, and the other way around.
But one early obstacle shows up again and again: how do you set up a repo you've never touched? Especially a legacy one, with tricky dependencies, where the way to run it lives only in a few people's heads.
That part usually eats time, because it means asking around first:
- which Node version does this use?
- what service dependencies does it need?
- when error A shows up, what am I supposed to do?
Make it a skill, not a doc
So the idea: why not write a skill per repo? Not ordinary setup documentation, but instructions written specifically to be executed by an AI agent. The user just tells the agent:
"Set up repo <X> on port <X>"
The flow, roughly:
- Take the knowledge from the engineer who knows the repo
- Write the step-by-step setup
- Add conditional instructions for the common cases
- Split troubleshooting into its own file
- Have the agent help produce the skill version
The format
```<repo-name>/├── docs/│ └── troubleshooting.md├── SKILL.md└── AGENTS.md```
AGENTS.md — the entrypoint each agent reads.SKILL.md — the step-by-step repo setup, including IF-ELSE instructions for specific conditions.docs/troubleshooting.md — the errors that show up often, their causes, and how to solve them.
Does it work?
In practice, the agent used the skill to set up one of our repos from zero to running on a local machine. What surprised me: even a lighter model could follow the instructions, as long as the skill was clear enough.
You can also instruct the agent to use a "user-select question" tool, so it offers the human a choice of actions instead of guessing. Example — when installing the repo:
- localhost only (
localhost:3000) - also set up a local proxy domain (
example.domain.local)
That makes installation flexible depending on what the user needs. Is this a best practice? Maybe not yet. As a small experiment, the results are promising.
The real win: setup context that used to live inside a few engineers' heads becomes a reusable instruction. Another engineer just asks the agent to run the setup, reviews the steps, accepts the commands that need running — and gets back to their actual task.
If engineers are going multi-role anyway, this hopefully makes stepping into a repo outside your daily area a little more seamless, with a lot less friction.