Blog / / 4 min read
Why every theme I sell ships with an AGENTS.md
AI coding tools produce generic output when they have to guess. I stopped letting them guess. Here is what goes into the AGENTS.md file that ships with every Lexington theme, and why it changed how customers customize them.
A year ago, the most common support question I got was some version of: “I asked Cursor to add a page and it looks nothing like the rest of the theme.”
The AI wasn’t broken. It just had no idea what it was looking at.
When a coding agent opens a project cold, it guesses. It guesses which folder pages live in, it guesses the frontmatter your content collections need, it guesses that bg-blue-500 is probably fine because it’s Tailwind and Tailwind has a blue. Every guess pulls the project a little further away from the design you paid for.
So I stopped letting it guess. Every Lexington theme now ships with an AGENTS.md at the root of the repository, and it changed everything about how people customize these themes.
What AGENTS.md actually is
It’s a plain Markdown file. No tooling, no install, no configuration. It’s the project brief, written in the file most coding agents read first: Cursor reads it as project context, Claude Code and Codex pick it up automatically from the root, and anything else can be pointed at it since it’s just Markdown.
Each theme’s AGENTS.md covers:
- Tech stack. The exact Astro, Tailwind, and integration versions, and where each is configured. No guessing whether this is Tailwind v3 or v4 syntax.
- Folder map. What lives where, including the theme-specific details agents would otherwise guess wrong.
- Content collections. Every collection with its required frontmatter, image field conventions, and which existing file to copy as a starting template.
- Routing conventions. How pages, dynamic routes, and layouts connect.
- Gotchas. The things that trip tools up, called out explicitly.
That last one matters more than it sounds. Every codebase has two or three things that are obvious to the person who built it and invisible to everyone else, humans and AI alike. Writing them down once beats explaining them in every prompt.
What it looks like in practice
The file does the heavy lifting, so prompts stay short. These all work on any Lexington theme, first try:
- “Add a new blog post about X.” The agent knows the collection folder, the required frontmatter, and which existing post to use as a template.
- “Create a careers page that matches the rest of the site.” The agent knows the layout, the component conventions, and the import alias.
- “Change the brand color.” The agent knows the tokens live in one CSS file, not scattered through fifty components.
Without the brief, each of those prompts needs a paragraph of context. With it, they’re one line.
The part most people skip
AGENTS.md is only useful while it’s true.
If you rename a collection or restructure your pages, tell your agent to update AGENTS.md in the same change. It takes one sentence in your prompt, and every future session inherits the corrected brief. A stale brief is worse than no brief, because the agent trusts it.
This is the habit I’d push on anyone using AI on any codebase, theme or not: treat the context file as part of the code. It changes when the code changes.
Why I ship it instead of selling it
Someone asked me why this isn’t a paid add-on. Honest answer: because the theme without it is a worse product in 2026.
Most customers customize their theme with an AI tool at some point. If the tool fights the theme, that’s a bad experience with my product, even when the tool is the one guessing. Shipping the brief means the first AI edit a customer makes actually looks like the theme they bought.
AGENTS.md is one of three context files in every theme. The other two, a design skill that keeps generated pages on-brand and a set of scoped Cursor rules, deserve their own posts, and I’ll write those next.
If you want to see a full brief before buying anything, every theme repo on GitHub includes it. It’s the first file I’d read too.
And if you want to build this for your own codebase, not just my themes, I wrote the whole system up as a short guide: Making Your Codebase AI-Ready. The brief, the design skill, the rules, and the habit that keeps them true, with fill-in templates. Reads in one sitting.
/Michael Andreuzza