AGENTS.md and AI Rules in Zed Editor: Complete 2026 Setup Guide

Zed is a code editor whose built-in AI agent reads AGENTS.md — along with eight other compatible filenames — as always-on project instructions, checking a fixed priority list and using the first file that matches.

That single sentence covers the mechanism, but the details matter more than usual here, because Zed changed how this works in version 1.4.0. If you configured Zed’s AI rules before that release, some of what you set up no longer exists in the form you left it. This guide covers the current system as documented by Zed: exactly which files it reads, in what order, where personal instructions live on disk, what replaced the old Rules Library, and how the whole approach compares to Claude Code, Cursor, and Windsurf.

The Short Answer

Zed’s AI agent supports AGENTS.md natively, and treats it as the primary instruction format. It also reads several other filenames for compatibility with other tools’ conventions — including CLAUDE.md, .cursorrules, and .github/copilot-instructions.md — but only the first matching file in a fixed priority order is actually used per project.

Separately, Zed has a feature called Skills for reusable, on-demand instructions (replacing what used to be a “Rules Library”), and a feature called Instructions for always-on personal and project context. AGENTS.md belongs to Instructions, not Skills. Conflating the two is the most common setup mistake.

How Zed Chooses Which File to Read

For project-level instructions, Zed checks the project root for the following filenames, in this exact order, and stops at the first one it finds:

.rules
.cursorrules
.windsurfrules
.clinerules
.github/copilot-instructions.md
AGENT.md
AGENTS.md
CLAUDE.md
GEMINI.md

This is a “first match wins” list, not a merge. If your project happens to have a leftover .cursorrules file from an earlier Cursor experiment sitting next to a carefully written AGENTS.md, Zed will load the .cursorrules file and ignore AGENTS.md entirely — silently. This is the single most common misconfiguration teams hit when migrating to Zed: they write a clean AGENTS.md, see no behavior change, and don’t realize an old .rules-family file is still winning the priority check.

Practical takeaway: before writing a new AGENTS.md for a Zed project, run a quick check for every file earlier in that list:

ls -la .rules .cursorrules .windsurfrules .clinerules .github/copilot-instructions.md AGENT.md 2>/dev/null

If any of those exist and you want AGENTS.md to be the one Zed actually reads, delete or rename the higher-priority file rather than trying to edit both.

Two Layers: Personal Instructions vs. Project Instructions

Zed separates instructions into two scopes, and they combine rather than replace each other.

Personal instructions (global, every project)

Zed reads a personal AGENTS.md from a fixed path outside any repository:

• macOS / Linux: ~/.config/zed/AGENTS.md
• Windows: %APPDATA%\Zed\AGENTS.md

This file applies to every project you open in Zed’s agent, regardless of what language or framework that project uses. It’s the right place for things that are true about you, not the codebase: your preferred commit message style, how verbose you want explanations, or a standing instruction like “always ask before running destructive shell commands.”

Project instructions (per-repository)

The priority-ordered list above (.rules through GEMINI.md) is checked per project. Whichever file matches first is loaded as that project’s instructions.

When personal and project instructions conflict, project instructions win. This is documented explicitly by Zed: project-level guidance overrides your personal defaults for that repository, which matches how most teams actually want it to behave — a repo’s conventions should take precedence over one developer’s personal habits.

Step-by-Step Setup

1. Create a project-level AGENTS.md

In the root of your project (same level as package.json, pyproject.toml, etc.), create a file named AGENTS.md:

# AGENTS.md

## Project
Next.js 15 app, TypeScript strict mode, Tailwind CSS, Drizzle ORM + PostgreSQL.
Package manager: pnpm.

## Conventions
- Server Components by default. Add "use client" only when required
  (event handlers, browser APIs, hooks) and explain why in a comment.
- Database queries live in /src/db/queries/. Never query the database
  directly from a component.
- Use the cn() utility from @/lib/utils for conditional Tailwind classes.

## Testing
Run `pnpm test` after any code change. All tests must pass before
a task is considered complete.

## Never
- Use the Pages Router.
- Install a new dependency without asking first.

Before saving, confirm no .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, or AGENT.md file already exists in the project root — any of those would take priority over AGENTS.md per the list above.

2. Create a personal AGENTS.md (optional but recommended)

Open or create the file at ~/.config/zed/AGENTS.md (macOS/Linux) or %APPDATA%\Zed\AGENTS.md (Windows):

# Personal Instructions

- Prefer concise explanations. Don't restate my question back to me.
- When generating git commit messages, use Conventional Commits format.
- Always show me the diff before running a database migration or
  a command that deletes files.

3. Verify Zed is reading the file

Open the Agent Panel — via the ✨ icon in the status bar, or by running agent::NewThread from the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Linux/Windows) — and start a new thread. Ask the agent an open-ended question your instructions should influence, for example: “What package manager should I use to install a new dependency here?” If the answer matches your AGENTS.md, it’s being read correctly.

4. Check instruction-related settings (optional)

Some agent behaviors adjacent to instructions — like Git commit message generation — have their own setting rather than living in AGENTS.md. Open the Settings Editor (Cmd+, on macOS, Ctrl+, on Linux/Windows), or run the agent::OpenSettings action from the Command Palette, and look for agent.commit_message_instructions in settings.json if you want commit messages to follow a specific format independent of your general project instructions:

{
  "agent": {
    "commit_message_instructions": "Use Conventional Commits: <type>(<scope>): <description>."
  }
}

What Happened to the Rules Library

If you used Zed’s AI agent before version 1.4.0, you may remember a “Rules Library” — a dedicated panel for writing and managing reusable prompt snippets you could @-mention in a thread.

As of Zed v1.4.0, the Rules Library no longer exists. It was replaced by two separate concepts:

• Skills — reusable, on-demand instruction packages the agent can invoke by name or pick up automatically when a task matches. A skill is a folder containing a SKILL.md file, stored globally at ~/.agents/skills/ or per-project at <worktree>/.agents/skills/.
• Instructions — always-on context, which is what this guide is about: AGENTS.md and its compatible-filename siblings.

If you upgraded from an older Zed version, your existing Rules migrated automatically:

• Rules that weren’t your default became global Skills under ~/.agents/skills/, each saved with disable-model-invocation: true (so they load only when you explicitly invoke them, not autonomously).
• Your default Rules were appended to your global AGENTS.md file.
• Old Rules Library content is not deleted from disk, so downgrading Zed leaves it intact.

A minimal SKILL.md looks like this:

---
name: release-checklist
description: Steps to run before tagging a production release.
disable-model-invocation: true
---

## Instructions

1. Confirm CHANGELOG.md is updated.
2. Run the full test suite with `pnpm test`.
3. Confirm no console.log statements remain in /src.
4. Tag the release: `git tag vX.Y.Z && git push --tags`.

The distinction matters for setup: if you’re trying to get always-on project context (the AGENTS.md role), use Instructions, not Skills. Skills are opt-in per task; they won’t silently shape every response the way an AGENTS.md file does.

Instruction File Support Across Zed’s Agent Surfaces

Zed has three different places AI can run — the built-in Zed Agent, External Agents (via the Agent Client Protocol), and Terminal Threads — and they don’t all read instruction files the same way.

The practical implication: External Agents and Terminal Threads in Zed may read their own native instruction files directly, independent of Zed’s instruction loader. Don’t assume that because Zed’s built-in agent picks up AGENTS.md, a third-party CLI agent launched from inside Zed will too — check that tool’s own documentation.

Comparison: Zed vs. Claude Code vs. Cursor vs. Windsurf

Zed’s AGENTS.md support stands out for one specific reason: it’s a first-class citizen of the cross-tool AGENTS.md standard, not a bolted-on compatibility shim. Where Cursor and Windsurf treat AGENTS.md as an experimental fallback behind their own proprietary formats, Zed lists it as one of its two primary instruction filenames (alongside the legacy .rules compatibility path) — which matters if your team already standardized on AGENTS.md for use with Codex, Aider, Gemini CLI, or other tools that adopted the same convention.

Common Mistakes to Avoid

Assuming AGENTS.md always wins. It doesn’t. Any of .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, or AGENT.md sitting in the same project root will be loaded instead, because they’re earlier in the priority list. Audit your project root before debugging why instructions “aren’t working.”

Confusing Skills with Instructions. Putting always-on project rules inside a SKILL.md file means they only apply when the agent decides to invoke that skill (or when a specific task matches its description) — not on every message. If you want a rule respected in every interaction, it belongs in AGENTS.md, not a skill.

Forgetting the two-tier system exists. A rule set purely in your personal ~/.config/zed/AGENTS.md won’t be visible to teammates, since it’s outside the repository. Team conventions belong in the project file; only genuinely personal preferences belong in the personal one.

Expecting External Agents to inherit Zed’s instruction loading. If you’re running an External Agent (via ACP) or a Terminal Thread inside Zed, don’t assume it reads AGENTS.md the same way the built-in Zed Agent does — check whether that specific tool has native support.

Frequently Asked Questions

Q1. Does Zed support AGENTS.md?

Yes. Zed’s built-in AI agent lists AGENTS.md as one of its primary instruction files, both for personal (global) instructions and for project-level instructions, alongside a set of legacy filenames kept for compatibility with other tools.

Q2. Where do I put a project-level AGENTS.md file in Zed?

At the root of your project, the same level as package.json or similar. Confirm no higher-priority file (.rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, or AGENT.md) exists in the same directory, since Zed uses the first matching file and ignores the rest.

Q3. Does CLAUDE.md still work in Zed, or do I need to rename it to AGENTS.md?

CLAUDE.md still works — Zed’s agent loads it as a compatible project instruction file. But it sits after AGENTS.md in the priority list, so if both files exist in the same project, AGENTS.md is the one Zed actually reads.

Q4. What happened to Zed’s Rules Library?

It was removed starting in Zed v1.4.0 and replaced by two separate features: Skills (reusable, on-demand instruction packages invoked by name or auto-matched to a task) and Instructions (always-on personal and project context via AGENTS.md and compatible files). Existing Rules migrated automatically — non-default rules became global Skills, and default rules were appended to the global AGENTS.md file.

Q5. Can I use .cursorrules and AGENTS.md in the same Zed project?

You can have both files present, but Zed will only load one. .cursorrules is earlier in the priority list than AGENTS.md, so if both exist, Zed reads .cursorrules and ignores AGENTS.md entirely — there is no merging.

Q6. Where is Zed’s personal/global AGENTS.md file located?

~/.config/zed/AGENTS.md on macOS and Linux, or %APPDATA%\Zed\AGENTS.md on Windows. This file applies to every project opened with Zed’s agent, and project-level instructions override it when the two conflict.

Q7. Do External Agents and Terminal Threads in Zed read AGENTS.md too?

Not necessarily. Zed’s own instruction loader is specific to the built-in Zed Agent. External Agents (via the Agent Client Protocol) and Terminal Threads may have their own native instruction-reading behavior — for example, the Claude Code CLI reads CLAUDE.md natively regardless of what Zed’s loader does. Check the specific tool’s documentation rather than assuming inheritance.

Keep Secrets Out of Your Zed Config

Both AGENTS.md and Zed’s settings.json are meant to be committed to version control, which makes them the wrong place for anything sensitive. It’s easy to paste a database URL or API key into a project instruction file while explaining how to connect to a service — and then commit it along with everything else.

The safer pattern: reference environment variable names in your instructions (“read the database URL from DATABASE_URL”), never the values, and keep the actual secrets in a password manager rather than a .env file that might get committed by accident. 1Password can inject secrets into your shell environment at runtime and integrates with CLI workflows, so your Zed config files — and the AI agent reading them — never see a real credential in the first place.