Zed 1.4.2: Agent Skills Replace the Rules Library

Zed shipped version 1.4.2 on May 27 and quietly retired its rules library. In its place: a structured skills system built around SKILL.md files that live in your repo, version-control like any other code, and travel with your dotfiles. It is a small line in the changelog and a meaningful shift in how Zed manages agent context.

Rules Are Out. Skills Are In.

The old @rule system worked, but it was fragile. Rules lived in Zed’s config as loose text blobs — useful until you switched machines, changed teams, or wanted to share a workflow. There was no structure, no packaging, no way to bundle scripts alongside instructions.

The new skills system fixes that. A skill is a folder with a SKILL.md file at its root. The folder name matches the skill name. The format supports scripts/ for runnable automation, references/ for supplementary documentation, and assets/ for templates the agent can drop into your project. Skills are self-contained, version-controllable, and shareable. Put them in your dotfiles. Commit them to the repo. The abstraction holds.

In the agent panel, @rule is replaced with @skill. Existing config carries over without a manual rewrite. Zed also ships a built-in create-skill skill — invoke it with /create-skill and the agent scaffolds the folder structure and frontmatter for you.

A minimal SKILL.md looks like this:

---
name: unit-tests
description: Use this skill when writing unit tests for TypeScript projects using Vitest.
---

## Instructions

1. Use Vitest as the test runner, not Jest
2. Place test files next to source files with a .test.ts extension
3. Mock external dependencies with vi.mock()
4. Run `npm run test:coverage` before finishing

The description field determines when the agent activates this skill autonomously. Write it like a trigger condition, not a summary. “Use this skill when writing unit tests” beats “Unit test helper” every time. For more advanced control, add a when_to_use field with detailed activation rules, or set disable-model-invocation: true to prevent auto-activation entirely.

Global AGENTS.md: Set Your Preferences Once

Previously, AGENTS.md was project-local — you dropped it in each repo root and maintained it per project. Zed 1.4.2 adds a global AGENTS.md placed alongside settings.json at ~/.config/zed/AGENTS.md. Those instructions get injected into every project’s system prompt automatically.

You can now codify your personal defaults — preferred test runner, commit message format, style conventions, “never delete files without asking” — and have them apply everywhere without remembering to copy-paste. Set it once and move on.

AGENTS.md is the cross-tool standard. Codex, Cursor, Copilot, Gemini CLI, Aider, and Windsurf all read it natively. According to the AGENTS.md 2026 guide, it is now governed by the Linux Foundation’s Agentic AI Foundation. With 1.4.2, Zed becomes the first editor to support both project-level and global AGENTS.md in a single native implementation. Claude Code still uses CLAUDE.md — the practical workaround remains ln -s AGENTS.md CLAUDE.md.

MCP Gets Image Output and Real OAuth Support

Two MCP improvements landed in 1.4.2 that anyone running complex agent workflows will eventually hit.

First, MCP tools can now return image data. This sounds minor until your diagram-generation server or screenshot-capture tool was silently dropping output because Zed could not render it. Tool key format is mcp:<server>:<tool> — for example, mcp:github:create_issue.

Second, OAuth client pre-registration is now first-class. Set client_id and client_secret in your context_servers config. The previous approach — running npx mcp-remote as an auth shim — still works but is no longer necessary for most servers. Zed also fixed OAuth failures from servers returning malformed metadata URLs and registration failures with non-standard OAuth implementations.

Skills as Dotfiles: Why It Matters More Than Cursor Quickpins

Cursor has its own concept of pinned skills — reusable instruction sets you can attach to agent prompts. The experience is smooth. But Cursor’s skills live in the IDE’s config, which means they do not travel with your code, do not show up in your git history, and cannot be shared without manual export.

Zed’s SKILL.md approach is file-system native. Skills live in a directory, sit in your dotfiles repo, and can be diffed, reviewed, and audited like any other code. If your team wants to standardize on a set of skills, you commit a skills/ directory to the monorepo. No config sync required. This is not Zed being precious about file format orthodoxy — it is the right call for teams that take reproducibility seriously.

The Builder.io 2026 review of Zed’s AI features noted that Zed’s composable, file-system-first design is what attracts developers who outgrow the VS Code extension model. The skills system is another step in that direction.

What to Do Right Now

Update Zed to 1.4.2 or later. Then:

• Replace @rule with @skill in your agent chat habits
• Run /create-skill to scaffold your first skill — start with one workflow you repeat weekly
• Create ~/.config/zed/AGENTS.md with your personal preferences
• If using MCP servers with OAuth, switch from the npx mcp-remote shim to native OAuth config

Full release notes are at zed.dev/releases/stable. The skills documentation and folder structure reference are at zed.dev/docs/ai/skills. If you are also running Claude Code or another terminal agent inside Zed, the Terminal Threads post covers how those workflows interact with the new panel layout.