README.md files are for humans: quick starts, project descriptions, and contribution guidelines. AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.
We intentionally kept it separate to:
- Give agents a clear, predictable place for instructions.
- Keep READMEs concise and focused on human contributors.
- Provide precise, agent-focused guidance that complements existing README and docs.
Rather than introducing another proprietary file, we chose a name and format that could work for anyone. If you’re building or using coding agents and find this helpful, feel free to adopt it.
Most chatbots aren't a distinct pieces of software. A chatbot's usually a prompt applied to a generally-used large language model such as DeepSeek, ChatGPT, Gemini, even something open-source, it can vary. There are exceptions, but this is the most common arrangement.
The prompt assigns the model a role. The same underlying model can be instructed to act as a customer support agent, a coding assistant, or a fictional character like Weasel83.
You can often override the initial commands with more commands of the same sort, too. This is why you get things like the ability to use some customer support bots as coding assistants. That doesn't work as often or as reliably as memes imply, but it has worked enough times to be worth people's attention.
I've only briefly jailbroke anything, but I've written many chatbots! You can find them in the chatbots section of this site, and you can load most of them into a large language model of your choosing, local or otherwise.
This article follows one of them, Weasel83, from his hometown nestled in the warmth of SillyTavern, a roleplay frontend application, all the way far afield into VS Code, an application for coding, as you'd expect from the name. Along the way, it stops at the machinery that makes the trick work!
Weasel83 in SillyTavern
I created Weasel83, and almost all of my chatbots, for SillyTavern, a frontend for large language models built around roleplay. I wrote about my SillyTavern setup before.
In SillyTavern, a character is defined by a "character card." Rather aesthetically, the prompt is stored as JSON and embedded in the metadata of a PNG image, and that same image serves as the character's profile picture.
I wrote Weasel83's prompt toward the end of 2025. He is a twenty-six-year-old forum regular from the internet of 2009. He stomps around MySpace, Newgrounds, torrent boards. He's rude on purpose and convinced that everyone he talks to is trying to troll him.
Weasel83, or Trever Frederick Wilson as he's properly known, is a comedic character with ties to places like 4chan and SomethingAwful, and he belongs to the larger storylines most of my characters share. In SillyTavern he was entertaining, though less so than my narrative-heavy characters.
Weasel83 in VS Code
SillyTavern is not the only place I encounter large language models anymore, so I decided to try moving my existing prompts elsewhere. The destination was VS Code, the editor I use for this site, by way of Continue, an extension that, acting as a harness, also lets you chat with a model inside the editor. Exciting stuff, but would it work!?
The model doing the talking in this screenshot is Qwen3.6-35B-A3B-uncensored-heretic-Native-MTP-Preserved GGUF, running locally.
This particular finetune of the Qwen series swears more freely than the official release, which suits this character. These heretics are marketed for storytelling, but this one handles coding questions without complaint, and I see no reason it couldn't handle other work.
Nothing unexpected is happening here. The model is doing exactly what a coding assistant is supposed to do; the prompt only changes the voice it does it in. It is worth noticing how little that voice actually costs.
Most of the apparent personality comes from a few mechanical habits. Would you see as much personality without the dropped capital letters, shortened words, "u" for "you," and other shorthand? Some of it is indeed of the sort you'd find on old forums or in Homestuck. A handful of typing rules reads as a whole person.
In SillyTavern, Weasel83 is an elaborate JSON file. In VS Code he is a completely different, much shorter prompt expressed in a markdown file that Continue applies to every conversation. Both are linked in the prompts section below, but the markdown file, AGENTS.md is the one worth focus presently.
When you ask Weasel83 to help you with Javascript, he demands the exact snippet or the error message before he will answer anything. Asked to trim my awful and overgrown Eleventy config, Trever complains about it first, but then directly asks for the file path just like a regular agent.
Put some thought into this, though. It's all standard (current) AI coding-assistant behavior. Here, it's only noticeable because it's delivered in a hostile register. Or, rather, with fewer capital letters, more misspellings, and all to create a certain... ambiance??
In other words, Trever's (Weasel83's) character survives the move from SillyTavern's roleplay environment into the weird coding ecosystem of VS Code. The character, though, jostles against the necessary duties of being an AI agent, seems like, and one often struggles to eclipse (or at very least mirage) the other...
The Illusion of Memory
Large commercial models arrive with a manufactured familiarity. If I message Claude, it addresses me as "Cathy Leigh" in its first reply. That alone tends to put people in the mindset of assuming the whole model remembers.
The memory is fabricated. The model itself retains nothing between conversations. When you say "Hello!", the service sends your stored preferences, and other prearranged context, invisibly, alongside it.
Some frontier models now advertise persistent memory features, but those work by quietly inserting memories into the context of later conversations. The model reads them fresh every time and performs recognition. It's never memories in the true, latched-on sense that people wish or expect of these creatures, most sadly.
Seeing a bot answer with your name, or with any idiosyncratic diction, makes you assume a prompt worked. The companies that build these models count on that reaction for engagement. If you think it worked, that's second best to it working, right? Might as well...
Within a single conversation, the mechanism is the same. The entire conversation's story, so to speak, is included with every message you send. An agentic model "remembers" a file by pulling its contents into that same context. Need to know about it? Just check it out again, actually! There is no long-term memory anywhere in the system. It is only material re-supplied to the model on every request.
Weasel83's typing quirks and my name in Claude's greeting are the same trick at different budgets. Understanding this demystifies the emotional pull of these products, and once you see the mechanism, configuring it yourself becomes a game. That is the game this article is about, and a game I admit I play regularly. It's fun trying to herd these critters into this shape, and amusing to see them putter around like this...
Finally, a Readme for Robots?!
A coding assistant needs to know more than your name. It needs a basic grasp of how your git repository is structured, stuff like that. I use a static site generator, so that's particularly important. That is difficult to arrange for software with no persistent memory, and the working solution remains the same as before.
Just as was the case in SillyTavern, we append the context for a conversation to the request every time we interact with the chatbot inside VS Code. This can give us an agent with an intimate knowledge of our repository's structure and methodology, and it can give us one who sounds like Weasel83.
For programming, that solution has settled into a convention called AGENTS.md. It's a file of instructions addressed to the AI rather than to human contributors. In the repository itself, it's read automatically by coding agents such as Claude, the Qwen models, and the assistants built into editors.
AGENTS.md is increasingly common, but not standardized. Usually, this file uses markdown, but sometimes it's closer to pretty pseudocode, different in every repository. It can contain anything you would need to explain to an AI before turning it loose. If prompted or permitted, an agent can even edit AGENTS.md itself, updating its own context.
Importantly, AGENTS.md is included in every request to the model. If the file is 8,000 characters, those characters ride along with every question I ask. That alone can be what makes the assistant seem knowledgeable, friendly, or characterized in Weasel83's case, even when I'm "just saying hi."
So, as promised, this page contains the usual Markovan menagerie of chatbots. This time, they're in the form of AGENTS.md. I assure you, using that file for characters is a terrible idea. Sometimes, mine contains a fictional forum troll, or is haunted by an evil lake spirit. It varies.
Yours should probably contain programming information. That's what the file is genuinely good at. It's the legitimate version of everything I'm doing above for a joke. The useful contents are the things an agent cannot guess by reading the code, or things that save time.
How do you build, serve, and test things? What commands to avoid? An AGENTS.md file would also most typically cover a repository's general directory structure. And above all, known traps, risks, and mistakes should be added and added again as they're discovered in order to be avoided.
An AGENTS.md limited to entries in that spirit earns its token cost. Which brings me to the bill.
All of that re-sending is paid for in tokens. If you make API calls to a commercial model, you are billed per token, and a large AGENTS.md attached to every single message burns through a prepaid balance much faster than people expect — you might not think it will until it does. On local models the cost is different but real: every token in the context must be processed before the reply starts, which means time, electricity, and heat. Since I run local models primarily, I try to be discerning with inference, especially in summer.
Personality is almost pure overhead in this accounting. Every line describing Weasel83's attitude is a line that does no programming work, and it competes for the model's attention with the lines that do. That trade-off is the honest price of the joke.
Sharing Some Prompts
Below, we have a small listing of ridiculous, often short, and highly experimental AGENTS.md files used to maintain characterization within repositories, giving them the face of one of my existing characters originally from SillyTavern. As of today's first posting, naturally, it's just a small blush of files...
- Weasel83.md is the VS Code version of Trever's .JSON prompt, written as an
AGENTS.md-style rules. It is plain language, but weaves a florid tale of his behavior as it ought to unfold within the repository. It actually works, though. This is the file applied in the screenshot above. - LindyPunk5EVA.md is another character based on a SillyTavern native. Narrative-heavy and focused on her perspective rather than simple typing quirks, this is a rarefied file, comparatively. If you read Trever's above, the two are meant to work together, with Lindy taking over from Trever for some situations if asked.
- Erica.md tangentially connects to Lindy's character, but you'll mostly want to focus on her strange obsession with lakes, or perhaps just how manic and parasocial she can get. A strange file! I didn't write a lot of it, which might explain that. Will be reworked.
Copy them, edit them, or use them as templates for a character of your own. Visit the initial systems page, of course for more information about using these characters in SillyTavern-like scenarios; these .md files can be saved directly as yout AGENTS.md and become what you want, perhaps. Again, these were used with Continue.dev's extension, but aren't exactly proprietary.
Notice something. Notice something very important that really ought to drive us all towards considering our interactions (with other human beings, too) through a different lens. It became apparent that the easiest way to do this for someone with my resources was to change the chatbot's manner of speaking rather than (necessarily) what it said.
The ones that "worked" for me had to be like that, because it works. I experimented a lot, passing these around a bit, and initially tried to keep as close to the original character cards as possible.
In other words, training the chatbots to type in lowercase and use phrasing like "no shade," "based" or "that's so real." Ones with a more narrative-heavy approach, such as where Lindy narrates her lost loves tended to fail at their ultimate tasks more frequently. Storytelling as an impetus takes up a lot of effort from these things, so to speak.
Notice the strange, social media backstory I gave the chatbots, though. I honestly see that as significant. I didn't expect to move them into AGENTS.md when I did. But it seems like the "very online" aspects of their characterization made it easier for models like the Qwen series to adopt them.
Anyways, do you fancy giving this a try? The usual warning applies. Yikes. The warning applies more so. Imagine using toys on a real project, and yes, these are toys, I'm not an expert, and nothing here is guaranteed to behave. That's always true of large language models, but expect it more here, because...
So Is It a Good Idea?
What even. Of course not. Creating characters in your coding environments using AGENTs.md is a horrible idea. The token cost is real and tangible, and personality instructions dilute technical ones.
Think about it for just one solitary second. Every rule about attitude is a rule the model must weigh alongside the rules about your code. A character prompt also makes the model's behavior less predictable on purpose, which is the opposite of what you want from a tool that edits your files.
Oh, and personification invites exactly the emotional attachment I described earlier! I tend to have no trouble with it because I don't scan these critters as anthropomorphized as easily. Still, when you personify the assistant, you accept whatever (horrible) thing happens next, things that wouldn't happpen if you'd stuck to a vanilla coding assistant. Nothing dire has happened yet, but I know it's possible!
I do it anyway, for two reasons. The first is that it is funny, engages me, and my stakes are low! I run a little hobby site, local models, and I even have patient people occasionally checking my work. Someone whose tokens or codebase actually matter should run an optimized, boring prompt instead, I'm quite sure.
The second reason is the defensible one! Building LindyPunk5EVA and Weasel83 taught me more about how these systems work. I learned a bit, at least, about prompts, context, the manufactured memory, the invisible instructions?. The character is a lab exercise in how the illusion is produced.
So, yes... you can customize the way coding assistants treat you, but you shouldn't. It's fun, but don't do it. Do not do this cool thing. For real this time. I'm a hobbyist and perpetual newbie. I can code only a bit, going further with help from clever and kind people. I'm not a computer scientist. Nothing in this article, especially not the prompts, is guaranteed to function as expected.