Tearing down GitHub's app modernization agent, and what an 'agent' actually is
These posts are live but still drafts — I'm figuring out how to write well with AI, and the tone and structure may shift as I go.
For a stretch of this year, part of my job was understanding agents. I spent time working on a migration agent, and the reference everyone pointed to was GitHub Copilot’s app modernization agent. In the decks and the launch talk, it sounds like heavy machinery: autonomous application modernization using multi-agent orchestration. Assessment coordinators. Planning coordinators. Executor agents with self-verification and retry logic. It went GA. A big deal was made, deservedly.
Then at some point I did the thing I probably should have done on day one: I opened the source. It’s public, sitting on GitHub for anyone to read.
It’s markdown.
The agent, the GA’d, keynote-grade, multi-agent orchestration system, is a folder of markdown files. I counted: 154 files in the repository, and 131 of them are markdown. Twelve are agents: .agent.md files, each one a written job description that tells the model who it is right now, what it’s responsible for, and who it hands work to next. Twenty-eight are skills: SKILL.md files sitting in folders of reference material, the deeper how-to knowledge an agent pulls in only when a task calls for it, like a specialist reaching for the right binder. The agents describe the org; the skills are its library; the harness (more on that in a minute) is what makes the folder run. The actual code comes to six small scripts, half of them telemetry. The words do the work.
I’ll admit my first reaction was a little deflating. That’s it? My second reaction has lasted longer: this is the most clarifying artifact about AI agents I’ve seen all year. Because if the agent is markdown, you’re forced to answer a question the industry keeps gesturing past.
What, exactly, is an agent?
Strip the marketing and every agent I’ve looked at (this one, the coding agents, the research agents) is the same three components wrapped around a model.
Instructions. The markdown. A role (“You are the main orchestrator for autonomous application modernization” is the literal first sentence of instructions in the main agent file), a workflow (assess → plan → execute), rules, guardrails, and templates for what to produce. The 28 skills are the same move at a finer grain: folders like analyzing-architecture with reference docs on API surfaces, data models, migration risks. This is tribal knowledge, written down. An onboarding wiki for an employee who reads at a million words a minute.
A harness. The actual software, and the part that gets the least credit while doing the most work. The harness is the loop: it feeds the model its instructions, executes the commands and file edits the model asks for, feeds the results back, retries what fails, runs the lifecycle hooks, and spawns the sub-agents. Here it’s GitHub Copilot CLI; Claude Code is another; there are dozens. And they are not interchangeable, which is the part people miss. Two harnesses can run the same model and feel like different products, because the magic lives in the unglamorous mechanics. Take context: a model can only hold so much conversation at once, and a two-hour modernization run produces far more output than fits, so the harness is constantly deciding what to compress, what to drop, and what must never fall out (the plan, your one non-negotiable constraint). Get that wrong and the agent confidently forgets its own instructions at hour two. Add how failures get presented so the model actually notices them, when it stops to ask you versus barreling ahead, and what it carries between sessions as memory. This is why Claude Code has the reputation it does. It isn’t running a secret smarter model; it’s running a better loop. There’s plenty more down in this layer (permissions, hooks, memory systems) that deserves its own essay. So I went and wrote it: a line-by-line look at the smallest working harness there is, which turns out to be a while-loop, two plug sockets, and a page of English. You don’t see any of it in this repo, because the harness is the thing you installed. The repo is cargo. The harness is the truck.
Tools. The hands: what the model is allowed to touch. File access, a terminal, and an .mcp.json declaring the external connections. An agent without tools is a well-read consultant with no keyboard: full of opinions, incapable of action.
And underneath, a model, rented by the token. The orchestrator’s frontmatter states it plainly: model: 'Claude Opus 4.8'. The intelligence is not in the folder. The folder is steering.
Here’s the mental model that finally made agents legible to me. The AppMod repo describes a three-level company: an orchestrator who delegates to coordinators (assessment, planning, execution), who delegate to a bench of executors: the Java-upgrade specialist, the Azure-migration specialist, the security specialist, the rearchitecture crew.
I call this the Paper Org Chart, because it is exactly that: an org chart written on paper, describing a company where nobody works. Every “employee” is the same model reading a different job description. The assessment coordinator and the security specialist are one intern with outstanding reading comprehension, sprinting between desks and swapping name tags. The intern attends the planning meeting as the planner, then attends the execution standup as six executors in parallel, and at no point does anyone find this strange.
Here’s the real chart, with the real file names, doing a real job. Ask it to modernize an aging Java service and the folder runs like this. modernize.agent.md, the orchestrator, reads your request and routes it to the assessment coordinator, who studies the codebase and writes up findings, pulling skills like analyzing-architecture and dependency-map off the shelf while it works. The planning coordinator turns that assessment into a plan with concrete tasks. The execution coordinator hands each task to the right specialist: the Java-upgrade agent for the version bump, the security agent for the CVE fixes, each reaching for its own binders (implementing-code, quality-gates) as the work demands. And every handoff between them is a file one agent wrote and the next one reads.
And the joke lands backwards, because it works. The role descriptions constrain what the model attends to; the hierarchy sequences the work; the handoffs force summaries. The Paper Org Chart is not a diagram of the software. The Paper Org Chart is the software.
I want to head off the cynical reading (“so it’s all just prompts?”) because I don’t buy it, and I’ve been on the other side of the folder.
First, agents-as-markdown means agents are legible. You can read, in plain English, exactly what this thing intends to do to your codebase before you let it touch a file. Every rule, every workflow, every guardrail: inspectable, diffable, forkable. Compare that to any traditional enterprise tool you’ve ever deployed on faith and a sales deck.
Second, the craft is real. Writing instructions that reliably steer a model through assessing a fifteen-year-old Java monolith, not once, in a demo, but across thousands of alien codebases, is a genuinely hard design discipline. Every ambiguous sentence is a bug. Every unstated assumption is an incident. The words are load-bearing. I have more respect for the folder of markdown, not less, having tried to write some.
Third, and this is the part I keep turning over: if the agent is markdown, then writing agents is not gated on being a systems engineer. The scarce input isn’t code. It’s a clear, written description of how the work should be done: what to check first, what good output looks like, when to stop and ask. Most teams have never produced that document for their own processes. The expertise exists; it lives in three senior people’s heads and evaporates a little every reorg.
Two honest caveats, so I don’t oversell the folder. The markdown is steering, not propulsion: the harness is real software and the model is doing the heavy cognition, and “it’s just prompts” undersells both. And this snapshot is today’s: the product is evolving, and it will likely grow more UX and machinery around it. The folder is the embryo, not the final form.
But the lesson survives both caveats. The next time someone shows you an agent, in a keynote, in a deck, with an org chart of orchestrators and coordinators dissolving into a glowing brain, you now know what’s inside the box. Instructions somebody wrote. A loop somebody built. Tools somebody granted. A model somebody rents.
Which means the interesting question flips from what can agents do? to who is writing them? Somewhere in your company there’s a process only you really understand: the checks you run, the order you run them in, the failure you always catch that nobody else does. That knowledge, written down clearly, is most of an agent. The org chart is paper now.
You could write the first page of yours tonight, and if you do, I’d genuinely love to hear what ended up in the folder.