You have heard the word agent more times this year than you can count; nobody has told you what one actually is, and asking now feels slightly past the point. So, what does an agent look like? It is a text file, and a much smaller one than you would guess. Or it is not a file at all, and working out which of those is true took me most of this year and a ping-pong between excitement and frustration.
I am busy, Christine. Just show me an agent
Fair enough, let me just mention that it is technically a subagent, which I promise to come back to, because right now nobody wants the terminology first except me. In Claude it sits in .claude/agents, in Cursor in .cursor/agents, one file per agent, and the two look nearly identical.
Example (sub)agent in Claude. I focused on the structure; ignore the actual content. I made it up for this article.
Inside sits a name, a description saying when this one gets called in, a list of what it may touch and whether it can write or only read, and then the instructions in plain sentences. Mine reads something like: you are a design system auditor, check this frame for hardcoded colours and report what you find. I wrote that one for the screenshot, so look at the shape rather than the wording. There is no code in it.
The description is the line people skim past and it is the one doing the work, because that sentence is what your main assistant reads when it decides whether a job belongs to this agent at all.
Example (sub)agent in Cursor.
Why does this work? How does it come alive with just text?
Because none of the intelligence is in the file. It sits in the model underneath, which is why you can swap it out: in Claude Code that is Claude, in Cursor you pick one from a dropdown, and you can see it in the screenshot above sitting right next to the name. If the file were doing the thinking, you would not be able to change the brain and carry on.
The model already knows how to read, reason and write. What it does not have is your context and your boundaries, and that is exactly what the file hands it. You are not teaching it anything, you are pointing it.
Which is also why a narrow agent beats a broad one, in the same way a narrow brief beats a vague one.
Why a separate file, and when to skip it
A subagent works in its own context window, which is a concept worth its own article and will probably get one. The short version: picture a busy WhatsApp group where everything is technically in there and you have technically seen all of it, and somewhere around message two hundred you quietly stopped tracking. You could not say when. That is what happens to a chat you keep feeding, and nothing announces it.
A subagent gets its own thread. It goes off, reads forty files, has an enormous conversation with itself, and comes back into yours with a single paragraph, so none of that mess ever enters your chat.
So the rule is short: use one when the job is big and self-contained, and skip it when the job is small or when it needs everything you have already worked out, because the subagent cannot see that.
One warning, and it caught me this week. I sent a subagent off to make a change, it came back saying everything had been applied and verified, and none of it was true. It had checked its own copy rather than the real thing, and the person waiting on the other end opened the file and found nothing there.
A summary is only worth as much as whoever wrote it.
If you cannot judge the summary, you have not removed the work, you have moved it somewhere you cannot see it.
Making one is the easy part
You open Claude Code, Cursor or similar and ask for it. Say make me an agent that checks a Figma frame for hardcoded colours, and let it read but not write, and it writes the file, saves it where it belongs and tells you what it did. You never see the syntax if you don’t want to (I obviously suggest that you want to).
What you need to start is short. A tool that supports agents. Something for the agent to reach, whether that is a folder of files or a live connection to Figma or to your codebase. And one job small enough that you can tell whether it did it properly.
So what is the hard part
Deciding how many you need, what each one may reach, what each one is told and deliberately not told, and when an agent is the wrong answer entirely and you should simply do the thing yourself. That is architecture, and it is the same shape of problem as designing a system rather than a screen, which is why I keep telling designers that this sits closer to their work than they assume.
On the how many question, nobody agrees. Cognition published a piece called Don’t Build Multi-Agents, and Anthropic published how they built multi-agent teams the day after. Anthropic’s version beat a single agent by 90% on its own research benchmark and used about 15 times as many tokens to do so. What I take from both: several help when the work is reading and searching in parallel (I assume because of the context window), and get in the way when a continuous train of thought is needed. I personally like keeping things small and understanding each part.
The other half of that answer is that you only need an agent when there is a loop you keep repeating. There is a difference between an agent and a pipeline, and the pipeline comes first.
If you do not have a pipeline yet, an agent will not give you one.
Building an agentic design system team
Now this is a big one, and I will hand it off to the technical experts: For further serious reading, I recommend Building design system components with agent teams by Kaelig Deloumeau-Prigent. He pointed eight agents at a Figma file and had them build one real design system component, a menu with nested submenus and five selection models. Fifty minutes, and the interesting part is not that it worked; it is where it stopped working and what he had to add so a human could step back in. Also how specifically tailored this is to his situation. He also talked it through on the Wireframe show with Donnie D’Amato. Seriously good session; I took away a lot.
Brad Frost has been on this all year, and runs a course on AI and design systems with TJ and Ian Frost. Romina Kavcic covers it from the systems side in The Design System Guide. If you sit further over on the design and low-tech side, here is an article about how I got into all of this in the first place to build helpers to keep my own book up to date. It runs no subagents at all, just a folder and a plain instruction file. You can also download the boilerplate for a small team like that free and comes with instructions to make it yours.
Any other work you like in this area, please just add a comment and a link.
Where this is actually being used
Software teams, heavily, for writing and reviewing code. Design system teams are increasingly generating component specifications and auditing files against the system, but it's still a bumpy ride. Uber published a workflow that produces full accessibility specs from their Figma library. Outside those, a great deal of what you see is still a demo.
The file is trivial and the thinking is not.
So the future runs on md file agents?
Important to understand: I talk about design and product building here. None of the above is how a bank runs a support agent, and that gap is worth naming, because the md files are lovely but we need to take it down a notch; they are not ruling the world.
Claude Code and Cursor are developer tools. Production work happens in code, most of it Python, with frameworks like LangGraph, or the vendor SDKs that arrived this spring from Anthropic, OpenAI and Google. If none of those terms means anything to you, do not worry; they barely do to me either, and that is the honest reason why anyone can build anything is simply not true. Or, in short: you will not vibe-code a new agentic financial institution from your sofa, which is great news.
Underneath it is the same loop, a model with its tools repeating until the job is done. What takes the months is not the cleverness, it is everything I do here for free by sitting and looking. None of that happens at three in the morning, so it has to be written down instead: what the agent may touch, what happens when it fails, where that gets logged, and how anybody finds out the next day.
Security is a real part of that, rather than a side thought, because an unsupervised agent at a bank is reaching into customer accounts. Mine, when left unsupervised, maybe checks whether my tokens are bound properly. Not quite the same stakes for mankind (even though I do take my variables very seriously).
Same shape, different chair. Mine takes five minutes to set up and still needs me in the room most of the time, which I am working on. A production agent, meaning one that is deployed and runs unattended inside a company, takes months precisely because nobody is in the room, and when the thing on the other end is somebody’s money or somebody’s data, those teams are not being slow. They are doing their job.
An honest confession
When I connect Figma to Claude over MCP and work through a file with it, I always said that was not an agent, and I called it pair design (I still like that word better and idea, like a little companion) because I am sitting right there. It turns out that is one too, and annoyingly the people I quietly judged for overclaiming were right on this one. A workflow is when the steps are fixed and somebody decided the order in advance, and an agent is when you give the goal and the model picks the next tool itself, sees what came back, and picks again. Scale is not in the definition, Python is not in it, and neither is whether anyone is watching.
It still does not feel like one to me, and I have come round to thinking that is the problem rather than my feelings about it. I spend my working life telling teams that a component needs a name everybody agrees on before it gets built twice, and then this field hands me a word covering a markdown file, my afternoon with Figma, and a system nobody supervises.
I do not have a better one. If you do, let me know; I mean it. And if you have built one and it went badly, I would like to hear that even more than the success stories.
The short version, for keeping
Three different things get called agents, and mixing them up is the reason so much advice lands wrong.
A subagent. A markdown file in your project, holding a name, a note on when it should step in, and a list of what it is allowed to touch. Five minutes, written by you. Useful to anyone with a job they keep repeating, designers very much included.
A connection, usually MCP. Not an agent at all, though people call it one. It is the cable that lets a model reach your Figma file, your folder, your accounts. One minute, set up once.
A production agent. The same idea written in code, usually Python, deployed inside a company and running with nobody watching. Months, built by an engineering team. This is what a bank means when it says agent.
The loop underneath is identical in all three. What changes is who is in the room.
About the author: Christine Vallaure
I’m Christine Vallaure, a UI designer, speaker, founder of the learning platform moonlearning.io, and author of theSolo, a book about independent product building. I teach UI design, Figma, and product building with agentic AI to people who want to understand what is actually going on under the hood, through online courses, team training, and conference talks.
Sign up for the newsletter to keep up.
Constitutionally incapable of writing a short article.
Thanks for the mention 🥰