Definition: AGENTS.md is a plain Markdown file left inside a project so that any AI agent opening it starts with the same standing brief, your conventions, the checks that matter and the parts to leave alone, which makes it the portable cousin of a system prompt and the plainest form of context engineering a team can do.
TL;DR: AGENTS.md is one Markdown file at the root of a project, with no required fields and no schema, that AI tools read before they touch anything. A group of tool makers agreed on the filename in 2025 so teams stopped keeping one rules file per assistant. Taskade assembles the same brief for you from your workspace. Build one free →
You already write these. When a new freelancer joins a project you send a short note before they start: here is how we name things, here is the one check to run before handing work back, please do not touch the client folder. Nobody calls that a configuration file. AGENTS.md is that same note, saved inside the project itself, addressed to software instead of a person.
Why AGENTS.md Matters in 2026
An AI agent starts every session knowing nothing about your project except what somebody wrote down. The model underneath it is stateless, so the agent harness has to rebuild the whole briefing from scratch on every request. A file sitting in the project is the cheapest durable place to put that briefing, because it travels with the work and every tool that opens the folder reads the same copy.
The convention arrived because the duplication got silly. Assistants had each shipped their own private filename for the same idea, so a team using three of them kept three drifting copies of one set of house rules. Agreeing on AGENTS.md collapsed that into a single file that any tool can pick up. What it did not do is write the brief for you. A vague file produces a vague agent, and the difference between a helpful agent and a confidently wrong one is usually a paragraph somebody never wrote.
How AGENTS.md Works
There is no parser, no schema and no required section. The agent finds the file, reads it as text, and folds it into the brief it carries for the rest of the session. That is the entire mechanism, which is exactly why it spread: anyone who can write a note can write one.
- The agent looks before it acts. Opening a project is the first thing an agent harness does, and checking for the brief happens before the first tool call.
- The nearest file wins. One at the root covers everything. A second one deeper in a folder overrides it for that folder, so a shared rule can be narrowed without rewriting the whole thing.
- The text joins the standing brief. It rides alongside the system prompt on every request, which means it also takes up room in the context window. Long is not the same as good.
- The agent works with the rules loaded. Every pass of the agent loop now happens against your conventions instead of the average of everything the model saw in training.
- Anything unwritten gets guessed. An agent that was never told which check to run will pick a plausible one. That is not a hallucination, it is a gap in the brief, and it is the failure the file exists to prevent.
- You edit it like any other document. It is a file, so it is reviewed, versioned and argued over the same way the rest of the project is. Nothing hidden, nothing vendor-specific.
A useful one is short and specific. This skeleton is the whole format:
# AGENTS.md
## What this project is
One or two sentences. What it does, who it is for.
## How to run it
The exact commands, in order. Nothing implied.
## Conventions
- Naming, formatting, folder layout
- The house style every newcomer gets wrong
## Before you hand work back
- The check that has to pass
- The file that has to be updated
## Do not touch
- Anything generated automatically
- Anything holding real customer data
Five headings, a page of text, no ceremony. Teams that get value from it treat it as a living note rather than a policy document: every time an agent gets something wrong in a way that was predictable, one line goes in the file, and it never gets it wrong that way again.
AGENTS.md vs a README vs a System Prompt
These three overlap enough that people assume one replaces the others. They do not. A README explains a project to a person who chose to read it, a system prompt defines one particular agent wherever it goes, and AGENTS.md instructs whichever agent shows up in this particular project.
| Trait | README | AGENTS.md | System prompt |
|---|---|---|---|
| Written for | People joining the project | Any AI agent that opens it | One specific agent |
| Lives in | The project folder | The project folder | The tool or product |
| Who can edit it | Anyone on the team | Anyone on the team | Whoever set the agent up |
| Travels with the work | Yes | Yes | No |
| Job of the text | Explain and persuade | Instruct and constrain | Define the agent itself |
| Typical content | What it is, why it exists | Commands, conventions, boundaries | Role, tone, standing rules |
| Read when | Somebody decides to | Every session, automatically | Every single request |
The practical split: put anything that is true of the project in AGENTS.md, and anything that is true of the agent in its system prompt. Reusable know-how that neither owns, a procedure an agent should be able to load on demand, belongs in agent skills instead. Facts the agent should remember across sessions belong in agent memory.
Connection to Taskade
You do not hand-write a briefing file in Taskade, because the workspace already is one. When you set up a custom agent you describe its role, its rules and its boundaries in plain language, and that description becomes the standing brief it carries into every conversation. Point it at the projects, documents and records it should know and that becomes its knowledge: the Memory half of Workspace DNA, where Memory feeds Intelligence and Intelligence triggers Execution. From there each agent already carries built-in tools and can reach 100+ bidirectional integrations, pulling events in from the apps your team uses and pushing updates back out through an automation. The model is picked for you: the Auto setting routes each job to one of 15+ frontier models from OpenAI, Anthropic, Google and open-weight providers. An actual AGENTS.md still matters at one edge. If you build an app through Taskade Genesis and export it to GitHub, the file in that repository is what outside coding agents will read, which is the same discipline vibe coding rewards everywhere else.
What You Would Build in Taskade
Every team has a rules document that went stale about four months ago. Decisions get made in a thread, the process quietly changes, and nobody edits the page, so new people and new agents both work from a version that stopped being true. That is the problem AGENTS.md solves for one project, and you can solve it for the whole team in Taskade.
Picture a house rules desk: a project where every convention is a row, with an owner, a date and a short reason it exists. An agent watches the places decisions actually get made, drafts an update whenever a rule changes, flags any two rules that now contradict each other, and posts a weekly summary of what moved. People read it as a checklist. Your AI agents read it as their brief, so both sides of the team run on one source instead of two. You can look at it as a board, a table or a calendar, whichever of the 7 project views you think in.
Describe yours and build it free →
Related Concepts
- Agent Harness: the software that reads the file and assembles the brief
- System Prompt: the standing instructions an agent carries everywhere
- Context Engineering: deciding what an agent sees on each request
- Agent Skills: packaged know-how an agent loads when it needs it
- Agent Memory: what an agent keeps between sessions
- Context Window: the space every brief has to fit inside
- Vibe Coding: building software by describing it
- The Agent Loop: the cycle your rules end up governing
- AI Agents in Taskade: agents that arrive briefed
Frequently Asked Questions About AGENTS.md
What is an AGENTS.md file?
AGENTS.md is a plain Markdown file kept inside a project that AI agents read before they start work. It holds the project's conventions, the commands that matter and the things not to touch, so any agent that opens the folder begins with the same brief instead of guessing.
Where do I put AGENTS.md?
At the root of the project, so everything under it is covered. You can add more in subfolders when one area needs different rules, and the nearest file wins for the work happening there. Keep the root one general and let the deeper ones handle exceptions.
What should go in an AGENTS.md file?
Five things cover most cases: what the project is, how to run it, the conventions people get wrong, the check to run before handing work back, and anything that must not be touched. Write the specifics you would tell a new freelancer. Skip anything the agent can see for itself.
Is AGENTS.md the same as a README?
No. A README explains a project to a person who chose to open it, and it can be discursive. AGENTS.md instructs any AI agent that opens the project, is read automatically at the start of every session, and works best as short, literal rules rather than prose.
Do I still need AGENTS.md if my agent has a system prompt?
They cover different ground. A system prompt defines the agent and travels with it into every project. AGENTS.md defines the project and applies to whichever agent shows up. Teams that use both put agent behavior in one and project facts in the other, which stops either file from bloating.
How long should an AGENTS.md file be?
Roughly a page. Everything in it is resent on every request and competes for room in the context window, so length has a real cost. Add a line each time an agent makes a mistake you could have predicted, and delete anything that has never changed an outcome.
Do I need an AGENTS.md file to use Taskade agents?
No. Every Taskade AI Agent is briefed from your workspace: the role you describe when you create it, plus the projects and documents you point it at. Taskade EVE assembles that context inside Taskade Genesis, so there is no file to maintain by hand.
Can two different AI tools share one AGENTS.md?
That is the point of the shared filename. Any tool that follows the convention reads the same file, so one brief covers every assistant your team uses instead of one copy each. Tools that also support their own older filename generally keep reading it, so adding AGENTS.md breaks nothing.