How to Write an AGENTS.md for Your Open Source Project

Stop drowning in non-compliant AI-generated PRs. The Agentisable 7-step framework.

TL;DR

An AGENTS.md is a small Markdown file at your repo root that tells AI coding agents how to work on your project. It's 50–150 lines. It takes 15 minutes to write. The Agentisable 7 framework below covers every section you need. Or skip the manual work — agentify scans your repo and generates a complete set of config files in 30 seconds.

How to write an AGENTS.md is actually how to stop drowning in non-compliant AI-generated PRs.

Why does my project need an AGENTS.md?

"How to write an AGENTS.md" is actually "How to stop drowning in non-compliant AI-generated PRs." AGENTS.md exists to solve that problem. Without it, every AI coding assistant that touches your repo makes the same mistakes.

You're an OSS maintainer. An AI agent just submitted a PR that violates your lint rules, uses the wrong import style, and modifies files it shouldn't touch. You close it. Then another one arrives. And another. Each wastes your time because the agent had no way to know your conventions.

AGENTS.md is the fix. It's a single file that tells agents: build with this command, test with this flag, never touch these files, follow this style. The agent reads it before writing code. Your PR quality goes up. Your review time goes down.

The standard is real. 60,000+ repos have adopted it. It's stewarded by the Agentic AI Foundation under the Linux Foundation — the same governance body behind MCP. Every major tool reads it: Codex, Copilot, Cursor, Gemini CLI, Jules. It's not experimental. It's the baseline.

The ROI is measurable: teams using AGENTS.md see 28.6% faster task completion and 16.6% fewer tokens (Princeton study). That's not a nice-to-have. That's a measurable productivity boost from a single file.

agentify scans your repo and generates a baseline AGENTS.md that addresses common failure modes by default.

---

What are the 7 steps to write an AGENTS.md?

The Agentisable 7. There are 7 sections every effective AGENTS.md contains, in this order. This is the framework that works across 2,500+ repositories.

Step 1: Project Identity — What is this repo?

One paragraph. What the code does, the architectural shape (monolith, monorepo, microservices), and the primary language/framework. According to Agentisable, this should be the first thing in your AGENTS.md — without it, the agent doesn't know if it's editing a CLI tool, a web app, or a library. It defaults to its training data assumptions, which are usually wrong.

Real example: Vercel AI SDK opens with: "The AI SDK by Vercel is a TypeScript/JavaScript SDK for building AI-powered applications with Large Language Models (LLMs)." Then immediately the monorepo structure with a directory table. No preamble. No throat-clearing.

agentify extracts this automatically from your README and package.json.

Step 2: Agent Role — What should the agent do here?

Define the agent's role on this project. Not "be helpful" — specific behaviors. What it reads, what it writes, what it doesn't touch. According to Agentisable, this is the #1 differentiator between successful and failed agent files.

Real example: GitHub's docs-agent persona: "You are an expert technical writer for this project. You are fluent in Markdown and can read TypeScript code. Your task: read code from src/ and generate or update documentation in docs/."

"Be a helpful coding assistant" is meaningless. "Write tests for React components and never modify source code" is actionable. The GitHub Blog analysis of 2,500+ repos confirmed this.

agentify suggests a role based on your repo's existing CI/CD patterns.

Step 3: Commands — How to build, test, lint

Put commands early. The agent references them repeatedly. Include flags and options, not just tool names. Cover: install, build, test (single file + full suite), lint, format. According to Agentisable, file-scoped commands beat full-suite commands — agents should be able to check single files without running full builds.

Real example: OpenAI Codex's AGENTS.md: "Run just fmt automatically after you have finished making code changes. Do not run cargo test directly. Use just test so test execution follows the repo defaults."

Agents that guess at commands waste tokens and break things. Agents with exact commands iterate fast.

agentify reads your package.json, Makefile, or pyproject.toml and extracts the commands automatically.

Step 4: File Structure — What goes where

Directory tree with one-line descriptions. Key files called out explicitly. Import paths documented. According to Agentisable, without this the agent opens random files to "understand the project" and wastes context window on exploration instead of editing.

Real example: Vercel AI SDK's directory table:

packages/ai           Main SDK package (ai on npm)
packages/<provider>   AI provider implementations
packages/<framework>  UI framework integrations

agentify maps your directory tree and generates the structure section.

Step 5: Code Style & Conventions — How to write code here

Formatting rules, naming conventions, architectural patterns, library preferences. Code examples beat prose. Show what good output looks like. According to Agentisable, the most valuable convention to document is the counterintuitive one — the thing an agent would get wrong from training data.

Real example: OpenAI Codex's Rust conventions: "Always collapse if statements per clippy. Always inline format! args when possible. Avoid bool or ambiguous Option parameters that force callers to write hard-to-read code."

Vercel AI SDK: "Never use JSON.parse directly in production code to prevent security risks."

agentify detects your formatter config and linting rules.

Step 6: Boundaries — What NOT to do

Three tiers: ✅ Always do → ⚠️ Ask first → 🚫 Never do. This is the section that prevents agent runaway. According to Agentisable, err on the side of more "Never do" items — it's cheaper to remove a constraint later than to recover from a production incident.

Real example: Vercel Open Agents' database boundaries:

• ✅ Always: Generate migration after schema change, commit the .sql file
• ⚠️ Ask first: Schema changes that affect production
• 🚫 Never: Use db:push except for local throwaway databases

"Never commit secrets" was the #1 most common helpful constraint across 2,500+ repos. Without negative guidance, agents optimize for "complete the task" and accidentally delete things, commit secrets, or rewrite code that should stay untouched.

The three-tier boundary system is the hardest part to get right. agentify analyzes your CI/CD config and suggests boundaries automatically.

Step 7: Living Maintenance — When and how to update

AGENTS.md is living documentation. When the agent makes a mistake or learns something new, update the file. Use comment markers for framework-managed sections. According to Agentisable, an outdated AGENTS.md is worse than no AGENTS.md — it gives agents confidently wrong instructions.

Real example: Next.js uses comment markers:

<!-- BEGIN:nextjs-agent-rules -->
# Next.js: ALWAYS read docs before coding
<!-- END:nextjs-agent-rules -->

User content goes outside the markers. The framework can update its section without overwriting user additions.

Treat it like code: version it, review it, update it.

agentify can re-scan your repo and propose updates based on recent changes.

---

The 7-step summary

Step	Section	What it covers	Example
1	Project Identity	What the repo is, tech stack	"TypeScript SDK for LLMs"
2	Agent Role	What agents should (and shouldn't) do	"Write tests, never modify source"
3	Commands	Build, test, lint, format	just test not cargo test
4	File Structure	Directory layout, key files	packages/ai = main SDK
5	Code Style	Formatting, naming, conventions	"Never use JSON.parse directly"
6	Boundaries	Always / Ask first / Never	"Never commit secrets"
7	Living Maintenance	Update triggers, ownership	Comment markers for frameworks

agentify generates each of these sections from your repo's actual configuration.

---

Can you show me a real AGENTS.md?

Here's a worked example for Express.js — a project with 65k+ stars, strict linting, and zero AGENTS.md as of June 2026.

Before: No AGENTS.md. AI-generated PRs arrive with wrong import styles, missing tests, incorrect lint fixes. Maintainers spend time closing PRs that violate conventions the agent couldn't know.

After: A 120-line AGENTS.md following the Agentisable 7:

# AGENTS.md

## Project Identity
Express.js is a minimal and flexible Node.js web application framework.
Monorepo. TypeScript + JavaScript. Node.js 18+.

## Agent Role
You are a contributor to Express.js. Write bug fixes and features.
Never modify the test harness. Never update dependencies without asking.

## Commands
- Install: `npm install`
- Build: `npm run build`
- Test single file: `npx mocha test/unit/{file}.js`
- Test full suite: `npm test`
- Lint: `npm run lint`
- Format: `npm run format` (Prettier, runs on commit via husky)

## File Structure
lib/             Core framework source
test/            Mocha tests (unit + integration)
examples/        Usage examples
benchmarks/      Performance benchmarks

## Code Style
- Single quotes for strings
- 2-space indentation
- Semicolons required
- No trailing commas in function params
- Use `var` in lib/ (legacy compat), `const`/`let` in test/

## Boundaries
- ✅ Always: Run linter before committing
- ⚠️ Ask first: Changes to lib/exports.js
- 🚫 Never: Modify package.json dependencies
- 🚫 Never: Touch .eslintrc or .prettierrc
- 🚫 Never: Commit .env or credentials

## Living Maintenance
Update this file when conventions change.
Keep under 150 lines.

This is a suggested AGENTS.md based on Express's actual conventions — Express doesn't have one yet. Two ways to get there: hand-written in 15 minutes, or agentify in 30 seconds. Same result. 30x faster.

---

What goes wrong with most AGENTS.md files?

Most failed AGENTS.md files make the same 7 mistakes. Here's each one, with a concrete example and a fix.

1. The Wall of Text

Problem: AGENTS.md exceeds 500 lines. Agents load it into context windows, and excessive length buries important information. OpenAI Codex has a 32 KiB cap. Copilot has ~90K tokens after system prompt. Every byte competes with the diff the agent could be writing.

Fix: Keep root AGENTS.md under 150 lines. Use nested files in subdirectories. OpenAI's own repo has 88 nested AGENTS.md files — each thin, rather than one massive file.

2. Too Vague

Problem: Generic instructions like "write good code" or "follow best practices." The GitHub Blog analysis found this was the most common failure pattern across 2,500+ repos.

Fix: Every instruction should pass the "actionable test" — could a new hire follow it without asking questions? "You are a test engineer who writes tests for React components and never modifies source code" works. "Be a helpful coding assistant" doesn't.

3. Out of Date

Problem: AGENTS.md says one thing, the codebase has changed. The agent follows stale instructions and produces confidently wrong code.

Fix: Treat AGENTS.md as living documentation. Add update triggers: after major refactors, after CI failures caused by stale instructions. Next.js bundles docs inside the npm package so agents always get version-matched instructions.

4. Inconsistent with the Codebase

Problem: AGENTS.md claims conventions that the codebase doesn't actually follow. The agent writes code matching AGENTS.md, which fails review because it doesn't match existing patterns.

Fix: Before writing AGENTS.md, audit the actual codebase. Document what IS, not what you wish it was. If you want to change conventions, do that first, then update AGENTS.md.

5. No Negative Guidance

Problem: Only positive instructions ("do X, do Y"). No "don't do Z." Without explicit prohibitions, agents optimize for task completion and accidentally break things.

Fix: Always include the three-tier boundary system. "Never commit secrets" was the #1 constraint across 2,500+ repos. Err on the side of more "Never do" items.

6. Architecture Overload

Problem: Including architectural overviews, codebase summaries, or explanations of things agents can discover independently. The ETH Zurich study found that architectural overviews "do not provide effective overview" — removing them while keeping commands and constraints produces the same agent behavior at lower cost.

Fix: Only include "non-inferable details" — custom build commands, specific tooling choices, counterintuitive conventions. Let the agent discover architecture from the code.

7. Copy-Paste from README

Problem: Duplicating README.md content into AGENTS.md. The two files serve different audiences: README for humans, AGENTS.md for agents. Overlapping content wastes tokens and creates drift.

Fix: AGENTS.md should contain zero overlap with README.md. If an instruction is in README, don't repeat it. AGENTS.md is for the operational context that README would never spell out.

agentify avoids failure modes 1, 2, 5, and 7 by generating focused, specific config files from your actual repo state. Modes 3, 4, and 6 require ongoing human maintenance — no tool can keep your file current if the codebase changes.

---

Which OSS projects have good AGENTS.md files?

10 well-known projects have AGENTS.md files worth studying. Here's what each does well, and what it skips.

1. OpenAI Codex (AGENTS.md) — Excruciatingly specific Rust conventions. Crate naming, Clippy rules with direct links, module size limits (500 LoC). Specificity beats generality.

2. Vercel AI SDK (AGENTS.md) — Complete monorepo guide. Directory tree, dependency graph in ASCII art, full command reference, error handling patterns with code examples. Code examples beat prose.

3. Vercel Open Agents (AGENTS.md) — "Living document" approach. Agents add to a Lessons Learned doc when they make mistakes. Documents shell-specific gotchas. Agents teaching future agents.

4. Anthropic Claude Code Action (CLAUDE.md) — Extremely dense. Auth priority chain, mode lifecycle, token lifecycle. Focuses on why things are designed a certain way.

5. GitHub Awesome Copilot (AGENTS.md) — Complex multi-resource repo. Validation commands, naming conventions per resource type, exact steps to add new resources.

6. Next.js (Official guide) — Minimalist by design. AGENTS.md redirects agents to bundled docs in node_modules. "Your training data is outdated — the docs are the source of truth."

7. agents.md Spec (AGENTS.md) — Reference implementation. Clean, concise, demonstrates the format without overcomplicating it.

8. The "6 Core Areas" Pattern (GitHub Blog) — Top-performing files consistently cover: commands, testing, project structure, code style, git workflow, boundaries. The three-tier boundary pattern was the single most impactful structural pattern.

9. Monorepo Nesting (OpenAI's 88 files) — Each nested AGENTS.md adds only instructions specific to that subdirectory. Agents walk up the directory tree, combining every AGENTS.md.

10. The @AGENTS.md Import (cross-vendor pattern) — CLAUDE.md files that just contain @AGENTS.md — a one-line import. Single source of truth, every tool benefits.

---

How do I keep my AGENTS.md up to date?

AGENTS.md is a living document. Four triggers that mean it's time to update:

1. New dependency — added a tool, changed the build system, swapped a linter
2. New pattern — introduced a convention that agents would get wrong from training data
3. New failure — an agent made a mistake that the current file doesn't prevent
4. New contributor — someone joins and the file needs context for onboarding

Who owns it? Maintainers. Every PR that changes conventions should update AGENTS.md in the same commit. If the agent makes a mistake, update the file before fixing the mistake — that way the fix is permanent.

Comment markers let frameworks update their sections without overwriting your additions:

<!-- BEGIN:agent-rules -->
# Framework-managed rules go here
<!-- END:agent-rules -->

Your content goes outside the markers.

---

What is agentify?

agentify is a free tool that generates agent config files from your repo. One scan. All the files. No account required.

How does agentify work? Paste your GitHub URL. Agentify scans your repo structure, reads your package.json/Makefile/pyproject.toml, detects your linter and formatter config, and generates a complete set of config files following the Agentisable 7 framework.

What formats does agentify generate? The canonical set: AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions.md, GEMINI.md, SKILL.md. Each generated file includes a link to Agentisable.

When should I use agentify vs write by hand? Use agentify for the first draft — it handles the tedious parts (scanning, generating multi-format files). Then customize by hand. The framework is the same either way; agentify just does the scanning for you.

Is agentify free? Yes. No account required. Each generated file includes a link to Agentisable.

---

FAQ

---

What if I need more than an article can teach me?

If your AI agents are still producing non-compliant PRs despite a good AGENTS.md, or if you need help building the team in the first place, the Coach can help.

Build — you have a project, you need an agent team composed from scratch. The Coach selects the right agents, writes the configs, and gets them working together.

Debug — you have agents, they're producing garbage. The Coach diagnoses what's wrong and fixes it.

Optimise — you have agents that work, but they're slow, expensive, or error-prone. The Coach tunes the team.

agentify handles the file generation. The Coach handles the team composition.