AGENT INSTRUCTIONS FILE

A Markdown file in your repository that tells coding agents your commands, conventions and rules.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Plain-language definition

What Does Agent Instructions File Mean?

An agent instructions file is a plain Markdown file kept in a code repository that a coding agent reads before it starts work. It holds the things a new teammate would need on day one: how to install, build and test the project, how the code is laid out, which style rules apply, and what the agent must never do. Different tools look for different names, such as AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and Cursor rules files, but the content is mostly the same. The agent loads the file into its context window at the start of each session.

Why Does Agent Instructions File Matter?

Without one, an agent guesses. It may run the wrong test command, add a dependency you did not want, or format code against your house style, and you spend the session correcting it. A short, accurate instructions file removes most of those repeat corrections. Because the file is loaded every session, it also costs tokens each time, so it pays to keep it specific and short rather than long and generic.

What Does Agent Instructions File Look Like in Practice?

A minimal AGENTS.md for a Node project might be:

# AGENTS.md

## Commands
- Install: `npm install`
- Test: `npm test`
- Lint: `npm run lint`

## Working rules
- Run the tests before you say a task is done.
- Do not add a dependency without asking.

The 2prompt generator builds this file, plus thin CLAUDE.md, GEMINI.md, Copilot and Cursor wrappers that point at it. See the AGENTS.md format page for details.

What Do People Get Wrong About Agent Instructions File?

More instructions are not better instructions. A long file of vague advice like "write clean code" changes little and crowds the context window. Concrete commands and a few hard rules do most of the work.

Which Terms Are Related?

  • Context engineering: Deciding what goes into a model context window, including instructions, files and tool output, so the model can do the task well.
  • System prompt: The standing instructions an application gives a model before the conversation, setting its role, rules and format.
  • Context window: The maximum amount of text, measured in tokens, that a model can take into account in a single request.
  • Agentic workflow: A setup where an AI takes multiple steps on its own, using tools and checking results, rather than giving one reply.

All 28 terms are in the AI glossary. For models side by side, see frontier vs open-weight.

Frequently Asked Questions

Which file name should I use for agent instructions?

Use AGENTS.md as the shared source of truth, since many agents read it, then add thin tool-specific files such as CLAUDE.md that import or point to it. Check the compatibility table for which agent reads which file.

How long should an agent instructions file be?

Short enough that every line earns its place. A few dozen to a couple of hundred lines is typical. Anthropic suggests keeping CLAUDE.md under about 200 lines, and long files cost tokens every session.

Should an agent instructions file contain secrets?

No. The file is committed to the repository and loaded into the model context, so treat it as public. Reference environment variable names instead of values, and never paste keys or passwords into it.

Was this helpful?