How to Migrate From Windsurf to Zed Without Losing Context (2026)

Skills transfer as-is. This is the good news, and it is better than most tool pairs. Windsurf keeps workspace skills in .windsurf/skills/ and global skills in ~/.codeium/windsurf/skills/, but its documentation adds: "For cross-agent compatibility, Devin Desktop also discovers skills in .agents/skills/ and ~/.agents/skills/." Zed loads skills from exactly two locations — ~/.agents/skills/ for global and <worktree>/.agents/skills/ for project-local. If your skills already live in .agents/skills/, both tools read the same files with no conversion.

Both also use progressive disclosure with the same two fields. Windsurf: "only the skill's name and description are shown to the model by default. The full SKILL.md content and supporting files are loaded only when Cascade decides to invoke the skill (or when you @mention it)." Zed: "It sees a catalog of every installed skill (name and description) in its system prompt, and calls the skill tool when a task matches a skill's description." Same mechanism, same name and description frontmatter, same disable-model-invocation flag on both sides.

Rule files transfer as bytes and change meaning. Windsurf's workspace rules live one-per-file in .devin/rules/*.md (preferred) or .windsurf/rules/*.md (fallback), and its documentation confirms that "the legacy single-file .windsurfrules at the workspace root is also still read." Root AGENTS.md is "processed by the same Rules engine — root-level = always-on, subdirectory = auto-glob for that directory."

Zed's project instruction loading works differently. Its documentation states: "Project instruction files apply to the current project. Zed uses the first matching file in this list:"

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

Count the positions. .windsurfrules is third. AGENTS.md is seventh. First match wins, and only one file is used. A repo that still carries a .windsurfrules from 2025 will have Zed reading that file and ignoring the AGENTS.md you wrote this morning — no warning, no error, no entry in any log you would think to check.

Activation modes do not transfer. Windsurf documents four, each declared in a trigger frontmatter field, and its table gives the context cost of each: always_on ("Full rule content is included in the system prompt on every message"), model_decision ("Only the description is shown in the system prompt. Cascade reads the full rule file when it decides the description is relevant"), glob ("Rule is applied when Cascade reads or edits a file matching the globs pattern"), and manual ("Rule is not in the system prompt. You activate it by typing @rule-name").

Those four modes are the control surface Windsurf users tune most, and losing the distinction is the most common cause of the complaint we documented in Windsurf forgetting your project rules — except here the rules are still on disk and the mode they were declared in no longer exists.

Zed has two surfaces instead of four. Instructions are "always-on context for the Zed Agent." Skills are invoked by the agent from a catalog, or manually by slash command or @skill mention. Zed's skill frontmatter documents three fields — name, description, and disable-model-invocation — and the page notes: "We plan to include other fields promoted by the Agent Skills specification in the near future." So a Windsurf rule scoped by a glob pattern has no field on the Zed side to carry that scoping today; it has to be re-expressed as a description the agent matches against.

Directory-scoped instructions lose their scoping. In Windsurf, an AGENTS.md in a subdirectory becomes "a glob rule with an auto-generated pattern of <directory>/**," so a monorepo can carry one instruction file per area for free. Zed's instructions page describes a single project instruction file selected from that ranked list and does not describe discovery of instruction files in subdirectories. Four AGENTS.md files at four levels arrive in Zed with no documented role for three of them.

Auto-generated memories stay where they are. Windsurf's own guidance is blunt about them: autogenerated memories are "associated with the workspace they were created in and are stored locally in ~/.codeium/windsurf/memories/," they "are not committed to your repository," and "auto-generated memories live only on your machine." Windsurf's recommendation is to promote anything you rely on into a rule or AGENTS.md before you go anywhere. Zed's documentation describes instructions and skills as its persistence surfaces for agent context; it does not describe an auto-generated memory store, so there is nothing on the Zed side for those files to land in. If you have been relying on them, promote them first — the workspace-scoped behaviour behind that advice is the subject of stopping Windsurf's Cascade from losing context.

One note on branding while you read the source docs: Windsurf's documentation now carries Devin Desktop naming throughout, and its memories page still describes Cascade in the present tense and points at a "Devin: Open Cascade Migration Wizard" command, even though the Devin Desktop changelog removed Cascade on September 8, 2026. If you are following that page, expect it to describe an agent your build no longer has. We covered the rule-folder half of that transition separately in merging Windsurf and Devin rule folders; this guide is about leaving for Zed, not reorganizing inside Windsurf.

Step 1: Pick the one project instruction file, then remove the decoys

Before writing anything new, list every file in your repository root that appears on Zed's ranked list. In a repo with Windsurf history, expect at least .windsurfrules, possibly .rules, possibly a .cursorrules from an earlier tool, and an AGENTS.md.

Decide which one is authoritative. AGENTS.md is the reasonable answer — it is the file Windsurf also processes, it is the one other tools recognize, and it is seventh in Zed's list, which means everything above it must go. Delete or rename the higher-ranked files. Renaming is safer: move .windsurfrules to docs/legacy-windsurf-rules.md so the content is still readable while being invisible to the loader.

Then consolidate. Windsurf gave you one file per rule with a 12,000-character limit each; Zed gives you one file total. Merge your .devin/rules/*.md bodies into AGENTS.md, keeping each rule's heading so you can still tell them apart. If a rule was always_on in Windsurf, it belongs here. If it was not, hold it for the next step.

Verify by contradiction rather than by reading. Add a line to AGENTS.md that is deliberately unusual — a naming convention you do not otherwise use — and ask the agent to apply it. If the agent ignores it, a higher-ranked file is still winning. This is the same check we recommend in why agents ignore your instruction files, and it is faster than auditing the tree.

Step 2: Turn the three conditional modes into skills, and watch the catalog budget

Everything that was not always_on becomes a skill. Zed's own migration note says as much for its retired Rules feature: "reusable, on-demand Rules become Skills," while "default, always-on Rules become personal AGENTS.md."

The translation depends on which mode you started from. A manual rule maps cleanly — it becomes a skill, and typing /skill-name or @skill-name invokes it, same as @rule-name did. A model_decision rule also maps cleanly, because both tools decide from the description; you can reuse the description text verbatim. A glob rule is the one that needs rewriting: the pattern has to become a sentence. **/*.test.ts turns into a description saying the skill applies when writing or modifying test files, and Zed's guidance is explicit about how to phrase it — "Include specific task types and trigger phrases."

Three constraints on the Zed side have no Windsurf equivalent, and all three fail quietly.

The catalog has a budget: "The total size of all skill names and descriptions is capped at 50KB. Skills that don't fit are dropped from the catalog with a warning in the UI." Descriptions should stay "under 1024 bytes." A team porting dozens of verbose Windsurf rule descriptions can exceed this.

The layout must be flat: "Skills must be direct children of the skills root. Nested folders like ~/.agents/skills/group/my-skill/ are not discovered." If you organized your Windsurf skills into subfolders, flatten them.

And project-local skills need trust: "Project-local skills only load from trusted worktrees. Skills from a freshly cloned or untrusted project are excluded from the catalog and slash commands until you grant trust." On a fresh clone your project skills are simply absent until you grant it — which is a sensible safety default and a confusing first hour.

Two smaller differences worth knowing. Zed resolves name collisions in the opposite direction from what a global-first habit expects: "If a global and a project-local skill share the same name, the project-local skill takes precedence." And project instructions win over personal ones — "Project instructions override personal AGENTS.md when they conflict" — which is the reverse of the tools that rank personal settings highest.

The migration above moves files. It does not solve the underlying problem, which is that the reasoning behind those rules was never in the files to begin with.

Your AGENTS.md says to use one HTTP client. It does not say that the other one was tried and abandoned because of a retry behavior nobody wanted. When a rule gets dropped during consolidation — and consolidating twelve files into one guarantees some dropping — the rule disappears along with the reason it existed, and the next engineer re-litigates it from scratch.

MemoryLake holds that second category: the rulings, the rejected alternatives, the constraints that are true regardless of which editor is open. It sits outside both tools, so a migration like this one moves configuration and leaves the reasoning intact. Get started here.

Step 1: Create an API key

Create a workspace for the project and generate an API key. Scope it to the project rather than the editor, so the layer survives the next tool change as well as this one.

Step 2: Upload your first memories

Do this before you consolidate, not after. Go through your .devin/rules/*.md files one at a time and record why each rule exists — not the rule itself, which is going into AGENTS.md, but the decision behind it. Add anything your Windsurf auto-memories captured that you actually rely on; those files are on one machine and are not committed anywhere.

Step 3: Connect your AI & agents

Connect Zed's agent, and connect Windsurf too if you are running both during the transition. Both read the same decision set, which means a rule you have not ported yet still has its reasoning available in the editor you have already switched to.

The silent-override problem becomes visible once. You check the ranked list, remove the decoys, and you are done — instead of discovering three months later that a stale .windsurfrules has been quietly governing every session.

Consolidation stops being lossy. Twelve rule files collapsing into one section-per-rule AGENTS.md is fine when the reasoning lives elsewhere. It is a real loss when the file was the only record — and it is the difference between a clean switch and the pattern described in Zed forgetting your project context, where the editor is configured correctly and the knowledge simply is not there.

Running both editors during a transition stops producing drift. Teams rarely switch in one afternoon; someone stays on Windsurf for a sprint. With one shared layer, both halves of the team are working from the same set of decisions even though their instruction files differ.

Audit the ranked list on every repository, not just the one you tested. .cursorrules and .clinerules also outrank AGENTS.md, and a monorepo that passed through three tools may carry all of them.

Write skill descriptions as trigger conditions, not summaries. Zed's guidance is that "Use when handling PDFs, extracting text, or filling forms" beats "Helps with PDFs." Since descriptions are now doing the work your glob patterns used to do, this is the highest-leverage sentence in each skill.

Keep the catalog lean deliberately. Every description competes for the same 50KB, and a dropped skill only surfaces as a warning in the UI. Fewer, sharper skills beat comprehensive ones.

Remember that Zed's loader does not govern other agents. Its instructions page says so directly: "External Agents and Terminal Threads may read their own native instruction files directly. Do not assume Zed's instruction loader controls those agents." If you run Claude or Codex through Zed as external agents, they read their own files — a boundary we mapped in giving Zed's external agents the context they don't inherit.

Expect a cache detail on skill edits: "Changes to a skill's name or description invalidate the model's prompt cache for the current session." Edit bodies freely mid-session; batch your description rewrites.

Windsurf and Zed agree on more than most tool pairs. They share a skills path, a skill format, and a progressive-disclosure model, which is why the skills half of this migration is nearly free.

They disagree on one thing that costs people days: Windsurf discovers many rule files and decides per file whether to inject them, while Zed reads the first match from a fixed nine-entry list. If you take one action from this guide, make it removing every file that outranks AGENTS.md in your repository root — and if you take a second, make it writing down why your rules exist before you merge twelve files into one.