Zed AI Rules and Skills: Configure the Zed Agent

Zed AI rules come in two layers. A .rules file at your worktree root gives the agent always-on project instructions — conventions it should follow in every thread. Skills, stored as SKILL.md folders under ~/.agents/skills, are reusable capabilities the agent loads on demand when a task matches their description. Since Zed v1.4, skills replaced the old Rules Library as the home for everything that isn't a project-level rule.

If you're setting up Zed's agent for the first time — or you opened the Rules Library after updating and found a migration notice instead of your prompts — this guide walks through both layers: writing a Zed .rules file, moving Rules Library entries to ~/.agents/skills, controlling when skills fire with disable-model-invocation, and sharing the same rules and skills with Cursor, Claude Code, and the rest of your toolchain.

Zed AI rules after v1.4: rules and skills, explained

Zed's agent lives in the Zed agent panel — the sidebar where you run threads against your codebase. Everything you configure feeds that panel, and it splits cleanly into two mechanisms:

The split matters because of context economics. Rules are injected into every conversation, so every line costs tokens on every request — they should stay short and non-negotiable. Skills use progressive disclosure: the agent only sees each skill's name and description up front, and reads the full instructions when a task actually calls for them. Long checklists, deploy runbooks, and framework-specific guidance belong in skills, not rules.

This is the same architecture the broader ecosystem has converged on. If you want the conceptual background, see what agent skills are and why they exist.

Project .rules files: setup and conventions

A Zed .rules file is plain markdown at the root of your worktree. No frontmatter, no special syntax:

# Project rules

## Stack
- Next.js 15 App Router, TypeScript strict mode
- Drizzle ORM against Postgres; never write raw SQL in route handlers

## Conventions
- Named exports only; no default exports outside app/ routes
- Zod-validate every request body at the route boundary
- Tests colocated as *.test.ts, run with vitest

## Boundaries
- Never edit files under src/generated/
- Ask before adding a new dependency

Zed reads the file automatically and includes it in every agent thread for that project. A few conventions worth following:

1. Keep it under ~60 lines. Rules ride along on every request. If a section only matters for certain tasks (migrations, release steps, scaffolding), it should be a skill instead.
2. Write instructions, not documentation. "Zod-validate every request body" beats three paragraphs explaining your validation philosophy.
3. One file at the root. Zed reads the worktree root only — it doesn't merge nested rules files from subdirectories the way some tools do, so per-package guidance in a monorepo also fits better as skills.

Fallback file names Zed recognizes

If there's no .rules file, Zed falls back to the first match among the rules files other tools use — including AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules, .clinerules, and .github/copilot-instructions.md. Only one file is used, so if your repo already carries an AGENTS.md for other agents, Zed will pick it up without any Zed-specific setup. That fallback chain is exactly why teams standardizing on one rules source across tools tend to have an easy time adding Zed: the file is probably already in the repo.

If both .rules and a fallback exist, .rules wins. Keep a single source of truth rather than letting two files drift.

The Rules Library to skills migration (~/.agents/skills)

Before v1.4, Zed shipped a Rules Library: a user-level collection of reusable prompts you could attach to threads, with some marked as defaults for every conversation. It worked, but it was Zed-only, unversioned, and invisible to your repo.

v1.4 retired the Zed Rules Library in favor of agent skills — the same SKILL.md format used by Claude Code and a growing list of other tools. Zed agent skills live on disk where you can inspect, version, and share them:

~/.agents/skills/
  api-conventions/
    SKILL.md
  release-checklist/
    SKILL.md
    scripts/
      verify-tags.sh
  writing-migrations/
    SKILL.md
    templates/
      migration.example.ts

Each skill is a folder with a SKILL.md at its root. The frontmatter carries a name and a description; the body carries the instructions. The description is load-bearing — it's what the model reads when deciding whether the skill is relevant:

---
name: writing-migrations
description: Use when creating or editing Drizzle database migrations. Covers naming, safety checks, and the generate/migrate workflow.
---

# Writing migrations

1. Never edit an applied migration; generate a new one.
2. Run pnpm db:generate after schema changes and review the SQL by hand.
3. Every destructive change needs an explicit backfill plan in the PR description.

Migrating from the Rules Library is mechanical:

1. Export or copy each library entry into its own folder under ~/.agents/skills/<skill-name>/SKILL.md.
2. Write a real description for each one. Library prompts never needed descriptions because you attached them manually; skills are selected by description, so a vague one means the skill never fires.
3. Move "default" library rules into your project's .rules file if they were genuinely always-on, or leave them as skills if they were task-specific. Most default prompts turn out to be task-specific.
4. Delete duplicates. If a library entry restated project conventions that already live in .rules, drop it.

Skills can bundle more than markdown — scripts, templates, and reference docs sit alongside SKILL.md in the folder, and the agent can read them when the skill is active. The SKILL.md format guide covers frontmatter fields, folder structure, and description-writing in depth.

disable-model-invocation and other control flags

By default, the agent decides when a skill applies: it scans skill descriptions and pulls in whichever matches the task. Sometimes you want a skill available but never auto-selected — a destructive release procedure, say, or a scaffold generator that should only run when you explicitly ask. That's what disable-model-invocation is for:

---
name: release-checklist
description: Step-by-step production release procedure, including tagging and rollback.
disable-model-invocation: true
---

With the flag set, the model won't load the skill on its own; it only runs when you invoke it explicitly in the thread. Use it for anything where an eager agent auto-applying the procedure would be worse than the agent not knowing it exists.

The practical frontmatter surface is small:

Two habits keep skills firing correctly. First, front-load trigger words in the description: name the files, frameworks, and verbs a matching task would contain. Second, keep skills narrow — one skill per procedure beats one mega-skill with ten sections, because a narrow description matches precisely and a broad one matches nothing. If a skill keeps loading when it shouldn't, tighten its description before reaching for the flag; the flag is for skills that are dangerous to auto-run, not for descriptions that are merely too broad.

Sharing skills between Zed and your other tools

The quiet win of the v1.4 change is that Zed skills aren't Zed skills — they're agent skills. The same SKILL.md folder format works across tools, which means the rules and procedures your team maintains don't have to be rewritten per editor.

This is where a registry earns its keep. On localskills.sh, every published skill is a package with a SKILL.md at its root — optionally with scripts, templates, and docs alongside it, up to 100 MB and 500 files per version. Skills are versioned with rollback, and one install can fan out to several tools at once:

npm install -g @localskills/cli
localskills login
localskills install acme/api-conventions --target claude cursor windsurf

The CLI writes each tool's native format from the one published package — .claude/skills/ for Claude Code, .cursor/rules/ (.mdc) for Cursor, .windsurf/rules/ for Windsurf, and so on. And because the package root is a standard SKILL.md folder, it's the same shape Zed loads from ~/.agents/skills — one canonical skill, every agent reading it. For teams, organizations add folders, roles, and access restrictions on top, and GitHub sync can mirror the whole skill library to a repo where edits flow back as new versions.

The alternative — hand-copying prompts between the Zed Rules Library's successor, .cursorrules files, and CLAUDE.md — is exactly the drift problem that cross-tool rules management exists to solve.

A complete Zed AI rules setup walkthrough

Here's the end-to-end setup for a project, from zero:

1. Create the project rules file. At your worktree root:

cat > .rules <<'EOF'
# Project rules
- TypeScript strict; named exports only
- Tests with vitest, colocated as *.test.ts
- Never edit src/generated/
EOF

2. Check for conflicting fallbacks. If the repo already has an AGENTS.md or .cursorrules, either delete the redundant one or make .rules the canonical copy and keep the others generated from it.

3. Create your first skill:

mkdir -p ~/.agents/skills/api-conventions
cat > ~/.agents/skills/api-conventions/SKILL.md <<'EOF'
---
name: api-conventions
description: Use when creating or modifying API route handlers. Covers response shapes, validation, and auth checks.
---

# API conventions

- Validate request bodies with zod at the route boundary
- Return { data } on success, { error } with a proper status on failure
- Call requireAuth() before any write operation
EOF

4. Lock down anything destructive. Add disable-model-invocation: true to skills that should only run on explicit request.

5. Open the Zed agent panel and test. Start a thread with a task that should trigger the skill — "add a POST handler for /api/projects" — and confirm the agent follows the conventions. If it doesn't, sharpen the skill's description; vague descriptions are the number-one reason skills don't load.

6. Publish the skill so the rest of your toolchain gets it too:

localskills publish

From there, teammates install it into Cursor, Claude Code, Windsurf, or their own ~/.agents/skills from one versioned source instead of pasting markdown around.

FAQ: Zed rules and skills

Where does Zed look for rules files?

At the worktree root, in order: .rules first, then fallbacks including AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules, .clinerules, and .github/copilot-instructions.md. The first match is used; nested directories aren't scanned.

What happened to the Zed Rules Library?

Zed v1.4 retired it in favor of agent skills stored under ~/.agents/skills. Each former library entry becomes a folder with a SKILL.md, gaining a description-driven loading model and compatibility with other tools that read the same format.

Do Zed skills work with Claude Code skills?

They share the SKILL.md format — frontmatter with name and description, markdown instructions, optional bundled files. A skill written for one can be used by the other; the main difference is the on-disk location (~/.agents/skills vs. .claude/skills/). A registry like localskills.sh handles placing one published skill into each tool's expected path.

How do I stop a skill from loading automatically?

Set disable-model-invocation: true in the skill's frontmatter. The skill stays installed and invocable by you, but the model will never pull it into a thread on its own.

Should something go in .rules or in a skill?

Ask whether it applies to every single task. Stack choices, style rules, and hard boundaries belong in .rules. Anything conditional — "when writing migrations…", "when touching the API…" — belongs in a skill, where it costs nothing until a matching task shows up.

---

One skill library, every tool — Zed included. Create a free account on localskills.sh and publish your first skill in a couple of minutes.

npm install -g @localskills/cli
localskills login
localskills publish