Coding agents are good inside one repo. The moment a task crosses a service boundary, they get lost — here's why, and the three skills I open-sourced to help.
If you've used an AI coding agent on a single, tidy repository, you've probably had a good time. If you've pointed one at a real microservices architecture — dozens of repos, services calling services, events flying around, ten years of accumulated decisions — you've probably watched it flail. Not because the model is bad at code, but because the information it needs doesn't live in any file it can read.
In my earlier notes on how agents work, I ended on the idea that an agent is only as good as what you feed it. Cross-service work is where that bites hardest. This post is about the specific ways it bites, and the three Claude Code skills I ended up building and open-sourcing to deal with it.
Working on my team's microservices, I kept hitting the same three walls:
The answer is in another repo. A frontend engineer sends you a network call and asks for a backend change. The route handler might be in this service — or behind the gateway in a different one, calling a third for the actual data. A human with tenure just knows where things live. An agent scoped to one repo doesn't, and can't grep its way to code it can't see.
The map exists only in people's heads. Who calls whom, which service owns which data, what events flow where — in most teams this architecture knowledge is tribal. There's no file to put in the agent's context, because nobody ever wrote it down. So the agent reconstructs its own guess from whatever it happens to read, and the guess is confidently wrong.
Legacy code looks exactly like real code. This one hurt the most. Old endpoints that still exist but shouldn't be used, two flows that do almost the same thing for historical reasons, feature flags nobody remembers, columns nobody dares drop. A tenured engineer navigates this on instinct. To an agent, deprecated code is indistinguishable from load-bearing code — it's all just text — so it happily builds new features on foundations the team abandoned years ago.
The common thread: agents don't fail on microservices because the code is hard. They fail because the context — the system map, the ownership, the "don't touch that" folklore — was never written down in a form anything could read.
A skill, in the Claude Code sense, is a file of instructions the agent reads when a matching task appears — a runbook written for a model instead of a human. Each of the three in the repo attacks one of the walls above.
/be-api-trace — from a network call to a backend change planYou paste a browser DevTools network call — method, URL, request, response. The skill parses the API contract out of it, searches the current repo for the route handler (and tells you if it lives in a different service), maps what the frontend renders from the response, traces response fields back to database tables, and produces a scoped change plan: the migration, the service changes, a before/after contract diff. It even drafts the one-liner to send back to the frontend engineer.
The point isn't automation for its own sake — it's that "FE asks for a BE change" is a task whose first hour is usually pure archaeology, and the archaeology is mechanical enough to hand off.
/ms-spec — make the tribal map explicitThis is the one closest to my heart. It discovers services from the repo, docker-compose, or gateway config; builds the system map — who calls whom, what events flow where, who owns what data; and then does the two things I most wished existed: it scans for domain pollution (business logic sitting in a service it doesn't belong to) and legacy code (deprecated endpoints, dual implementations, orphaned flags and columns).
Then — and this part matters — it interrogates you. It asks targeted questions, one category at a time, until every gap is either filled or explicitly marked [UNKNOWN]. The output is an architecture doc plus one spec file per service, each ending in a "Context for AI Agents" section. Drop the relevant file into a session and the agent starts with the map instead of a guess — including which flows are legacy, which is the fix for the wall that hurt the most.
Honest admission: the docs are useful to humans too. Half the value of writing context for agents is discovering your team never wrote it for people either.
/update-all — the boring oneDiscovers every git repo under a parent folder, figures out whether each uses master or main, checks out the default branch, pulls, and reports anything that needs attention. Utterly unglamorous. But cross-service work starts with "make sure all thirty repos are current," and a stale repo quietly poisons everything an agent concludes downstream. Boring tools that remove a whole class of confusion are worth their weight.
Write for the reader you actually have. An agent reading a spec doesn't need elegant prose; it needs unambiguous ownership statements, explicit "this is deprecated" markers, and honest [UNKNOWN]s rather than confident blanks. Oddly, writing for that reader made me a clearer writer for humans too.
Marking what's legacy beats describing what's current. Agents can read current code themselves. What they cannot infer is which parts of it the team has walked away from. If you document only one thing, document that.
Keep the context scoped. One spec file per service, loaded per task — not one giant architecture dump in every session. The same principle as everywhere else in this space: small context, deliberately chosen, beats big context passively accumulated.
The repo is public at github.com/lsscecilia/skills-for-microservices — if you try the skills on your own architecture, I'd genuinely love to hear what breaks.
All examples described in general terms. The skills are generic and open source — they contain nothing from any particular system.