Cómo migrar de Windsurf a Zed sin perder el contexto (2026)

Las habilidades (skills) se transfieren tal cual. Esta es la buena noticia, y es mejor que en la mayoría de los pares de herramientas. Windsurf guarda las habilidades del espacio de trabajo en .windsurf/skills/ y las globales en ~/.codeium/windsurf/skills/, pero su documentación añade: "Para compatibilidad entre agentes, Devin Desktop también descubre habilidades en .agents/skills/ y ~/.agents/skills/." Zed carga habilidades de exactamente dos ubicaciones: ~/.agents/skills/ para las globales y <worktree>/.agents/skills/ para las locales del proyecto. Si tus habilidades ya residen en .agents/skills/, ambas herramientas leen los mismos archivos sin necesidad de conversión.

Ambos también utilizan la divulgación progresiva con los mismos dos campos. Windsurf: "por defecto, solo se muestran al modelo el nombre y la descripción de la habilidad. El contenido completo de SKILL.md y los archivos de soporte se cargan solo cuando Cascade decide invocar la habilidad (o cuando la mencionas con @)". Zed: "Ve un catálogo de cada habilidad instalada (nombre y descripción) en su prompt del sistema, y llama a la herramienta skill cuando una tarea coincide con la descripción de una habilidad". Mismo mecanismo, mismos campos de frontmatter name y description, misma bandera disable-model-invocation en ambos lados.

Los archivos de reglas se transfieren como bytes y cambian de significado. Las reglas del espacio de trabajo de Windsurf residen a razón de una por archivo en .devin/rules/*.md (preferido) o .windsurf/rules/*.md (alternativo), y su documentación confirma que "también se sigue leyendo el archivo único heredado .windsurfrules en la raíz del espacio de trabajo". El archivo AGENTS.md de la raíz es "procesado por el mismo motor de reglas: nivel de raíz = siempre activo (always-on), subdirectorio = auto-glob para ese directorio".

La carga de instrucciones de proyecto de Zed funciona de manera diferente. Su documentación establece: "Los archivos de instrucciones del proyecto se aplican al proyecto actual. Zed utiliza el primer archivo que coincida en esta lista:"

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

Cuenta las posiciones. .windsurfrules está en tercer lugar. AGENTS.md está en séptimo lugar. La primera coincidencia gana y solo se utiliza un archivo. Un repositorio que todavía conserve un .windsurfrules de 2025 hará que Zed lea ese archivo e ignore el AGENTS.md que escribiste esta mañana, sin advertencias, sin errores y sin ninguna entrada en ningún registro que se te ocurra revisar.

Los modos de activación no se transfieren. Windsurf documenta cuatro, cada uno declarado en un campo de frontmatter trigger, y su tabla detalla el costo de contexto de cada uno: always_on ("El contenido completo de la regla se incluye en el prompt del sistema en cada mensaje"), model_decision ("Solo se muestra la descripción en el prompt del sistema. Cascade lee el archivo de reglas completo cuando decide que la descripción es relevante"), glob ("La regla se aplica cuando Cascade lee o edita un archivo que coincide con el patrón de globs") y manual ("La regla no está en el prompt del sistema. La activas escribiendo @nombre-de-regla").

Esos cuatro modos son la superficie de control que los usuarios de Windsurf más ajustan, y perder esa distinción es la causa más común de la queja que documentamos en Windsurf forgetting your project rules, excepto que aquí las reglas siguen en el disco y el modo en el que fueron declaradas ya no existe.

Zed tiene dos superficies en lugar de cuatro. Las instrucciones son "contexto siempre activo (always-on) para el agente de Zed". Las habilidades son invocadas por el agente desde un catálogo, o manualmente mediante un comando de barra diagonal o una mención @skill. El frontmatter de habilidades de Zed documenta tres campos: name, description y disable-model-invocation, y la página señala: "Planeamos incluir otros campos promovidos por la especificación de Agent Skills en un futuro cercano". Por lo tanto, una regla de Windsurf delimitada por un patrón glob no tiene hoy en día ningún campo en el lado de Zed para soportar esa delimitación; tiene que ser reexpresada como una descripción con la que el agente coincida.

Las instrucciones delimitadas por directorio pierden su alcance. En Windsurf, un AGENTS.md en un subdirectorio se convierte en "una regla glob con un patrón autogenerado de <directory>/**", por lo que un monorrepósito puede albergar un archivo de instrucciones por área de forma gratuita. La página de instrucciones de Zed describe un único archivo de instrucciones de proyecto seleccionado de esa lista clasificada y no describe el descubrimiento de archivos de instrucciones en subdirectorios. Cuatro archivos AGENTS.md en cuatro niveles llegan a Zed sin ningún rol documentado para tres de ellos.

Las memorias autogeneradas se quedan donde están. La propia guía de Windsurf es tajante al respecto: las memorias autogeneradas están "asociadas con el espacio de trabajo en el que se crearon y se almacenan localmente en ~/.codeium/windsurf/memories/", "no se confirman (commit) en tu repositorio" y "las memorias autogeneradas viven solo en tu máquina". La recomendación de Windsurf es promover cualquier cosa de la que dependas a una regla o a AGENTS.md antes de ir a cualquier parte. La documentación de Zed describe las instrucciones y habilidades como sus superficies de persistencia para el contexto del agente; no describe un almacén de memoria autogenerado, por lo que no hay nada en el lado de Zed donde puedan aterrizar esos archivos. Si has estado dependiendo de ellos, promuévelos primero; el comportamiento delimitado por el espacio de trabajo detrás de ese consejo es el tema de stopping Windsurf's Cascade from losing context.

Una nota sobre las marcas mientras lees los documentos de origen: la documentación de Windsurf ahora lleva el nombre de Devin Desktop en todas partes, y su página de memorias todavía describe a Cascade en tiempo presente y apunta a un comando "Devin: Open Cascade Migration Wizard", a pesar de que el registro de cambios de Devin Desktop eliminó Cascade el 8 de septiembre de 2026. Si estás siguiendo esa página, espera que describa un agente que tu compilación ya no tiene. Cubrimos la mitad de esa transición correspondiente a la carpeta de reglas por separado en merging Windsurf and Devin rule folders; esta guía trata sobre migrar a Zed, no sobre reorganizarse dentro de Windsurf.

Paso 1: Elige el único archivo de instrucciones del proyecto y luego elimina los señuelos

Antes de escribir algo nuevo, haz una lista de cada archivo en la raíz de tu repositorio que aparezca en la lista clasificada de Zed. En un repositorio con historial de Windsurf, es de esperar al menos un .windsurfrules, posiblemente .rules, posiblemente un .cursorrules de una herramienta anterior y un AGENTS.md.

Decide cuál es el autoritativo. AGENTS.md es la respuesta más razonable: es el archivo que Windsurf también procesa, es el que reconocen otras herramientas y está en el séptimo lugar de la lista de Zed, lo que significa que todo lo que esté por encima de él debe desaparecer. Elimina o cambia el nombre de los archivos con mayor prioridad. Cambiar el nombre es más seguro: mueve .windsurfrules a docs/legacy-windsurf-rules.md para que el contenido siga siendo legible pero invisible para el cargador.

Luego consolida. Windsurf te daba un archivo por regla con un límite de 12,000 caracteres cada uno; Zed te da un solo archivo en total. Fusiona los cuerpos de tus archivos .devin/rules/*.md en AGENTS.md, manteniendo el encabezado de cada regla para que puedas seguir distinguiéndolas. Si una regla era always_on en Windsurf, pertenece aquí. Si no lo era, guárdala para el siguiente paso.

Verifica por contradicción en lugar de por lectura. Agrega una línea a AGENTS.md que sea deliberadamente inusual (una convención de nomenclatura que no uses de otra manera) y pídele al agente que la aplique. Si el agente la ignora, un archivo de mayor prioridad sigue ganando. Esta es la misma comprobación que recomendamos en why agents ignore your instruction files, y es más rápida que auditar el árbol.

Paso 2: Convierte los tres modos condicionales en habilidades (skills) y vigila el presupuesto del catálogo

Todo lo que no fuera always_on se convierte en una habilidad. La propia nota de migración de Zed dice lo mismo para su función Rules retirada: "las reglas reutilizables bajo demanda se convierten en habilidades (Skills)", mientras que "las reglas predeterminadas y siempre activas (always-on) se convierten en un AGENTS.md personal".

La traducción depende del modo del que hayas partido. Una regla manual se mapea limpiamente: se convierte en una habilidad, y escribir /nombre-de-habilidad o @nombre-de-habilidad la invoca, igual que lo hacía @nombre-de-regla. Una regla model_decision también se mapea limpiamente, porque ambas herramientas deciden a partir de la descripción; puedes reutilizar el texto de la descripción tal cual. Una regla glob es la que necesita reescribirse: el patrón tiene que convertirse en una frase. **/*.test.ts se convierte en una descripción que dice que la habilidad se aplica al escribir o modificar archivos de prueba, y la guía de Zed es explícita sobre cómo redactarlo: "Incluye tipos de tareas específicos y frases de activación".

Tres restricciones en el lado de Zed no tienen equivalente en Windsurf, y las tres fallan silenciosamente.

El catálogo tiene un presupuesto: "El tamaño total de todos los nombres y descripciones de habilidades está limitado a 50KB. Las habilidades que no quepan se descartan del catálogo con una advertencia en la interfaz de usuario". Las descripciones deben mantenerse "por debajo de los 1024 bytes". Un equipo que porte docenas de descripciones detalladas de reglas de Windsurf puede superar este límite.

La estructura debe ser plana: "Las habilidades deben ser hijas directas de la raíz de habilidades. No se descubren carpetas anidadas como ~/.agents/skills/grupo/mi-habilidad/". Si organizaste tus habilidades de Windsurf en subcarpetas, aplánalas.

Y las habilidades locales del proyecto necesitan confianza: "Las habilidades locales del proyecto solo se cargan desde árboles de trabajo (worktrees) de confianza. Las habilidades de un proyecto recién clonado o que no es de confianza se excluyen del catálogo y de los comandos de barra diagonal hasta que otorgues confianza". En un clon nuevo, las habilidades de tu proyecto simplemente no estarán presentes hasta que la otorgues, lo cual es un valor predeterminado de seguridad sensato pero que genera confusión durante la primera hora.

Dos diferencias menores que vale la pena conocer. Zed resuelve las colisiones de nombres en la dirección opuesta a lo que esperaría un hábito de dar prioridad a lo global: "Si una habilidad global y una local del proyecto comparten el mismo nombre, la habilidad local del proyecto tiene prioridad". Y las instrucciones del proyecto ganan a las personales: "Las instrucciones del proyecto anulan el AGENTS.md personal cuando entran en conflicto", lo cual es lo contrario de las herramientas que clasifican las configuraciones personales con la prioridad más alta.

La migración anterior mueve archivos. No resuelve el problema de fondo, que es que el razonamiento detrás de esas reglas nunca estuvo en los archivos para empezar.

Tu AGENTS.md dice que uses un cliente HTTP específico. No dice que el otro fue probado y abandonado debido a un comportamiento de reintento que nadie quería. Cuando una regla se descarta durante la consolidación (y consolidar doce archivos en uno garantiza que se descarten algunas cosas), la regla desaparece junto con la razón por la que existía, y el siguiente ingeniero vuelve a debatirla desde cero.

MemoryLake alberga esa segunda categoría: las decisiones, las alternativas rechazadas, las restricciones que son verdaderas independientemente de qué editor esté abierto. Se sitúa fuera de ambas herramientas, por lo que una migración como esta mueve la configuración y deja intacto el razonamiento. Comienza aquí.

Paso 1: Crea una clave API

Crea un espacio de trabajo para el proyecto y genera una clave API. Limita su alcance al proyecto en lugar de al editor, para que la capa sobreviva tanto al próximo cambio de herramienta como a este.

Paso 2: Sube tus primeras memorias

Haz esto antes de consolidar, no después. Revisa tus archivos .devin/rules/*.md uno por uno y registra por qué existe cada regla; no la regla en sí, que irá a AGENTS.md, sino la decisión detrás de ella. Agrega cualquier cosa que tus memorias automáticas de Windsurf hayan capturado y de la que realmente dependas; esos archivos están en una sola máquina y no están confirmados en ningún lado.

Paso 3: Conecta tu IA y agentes

Conecta el agente de Zed, y conecta también Windsurf si estás ejecutando ambos durante la transición. Ambos leen el mismo conjunto de decisiones, lo que significa que una regla que aún no hayas portado seguirá teniendo su razonamiento disponible en el editor al que ya te has cambiado.

El problema de la anulación silenciosa se vuelve visible de inmediato. Revisas la lista clasificada, eliminas los señuelos y listo, en lugar de descubrir tres meses después que un .windsurfrules obsoleto ha estado gobernando silenciosamente cada sesión.

La consolidación deja de tener pérdidas. Que doce archivos de reglas se reduzcan a un AGENTS.md con una sección por regla está bien cuando el razonamiento vive en otra parte. Es una pérdida real cuando el archivo era el único registro, y es la diferencia entre un cambio limpio y el patrón descrito en Zed forgetting your project context, donde el editor está configurado correctamente pero el conocimiento simplemente no está allí.

Ejecutar ambos editores durante una transición evita que se produzcan desviaciones. Los equipos rara vez cambian en una sola tarde; alguien se queda en Windsurf durante un sprint. Con una capa compartida, ambas mitades del equipo trabajan a partir del mismo conjunto de decisiones, aunque sus archivos de instrucciones difieran.

Audita la lista clasificada en cada repositorio, no solo en el que probaste. .cursorrules y .clinerules también tienen prioridad sobre AGENTS.md, y un monorrepósito que haya pasado por tres herramientas puede contener todos ellos.

Escribe las descripciones de las habilidades como condiciones de activación, no como resúmenes. La guía de Zed es que "Usar al manejar PDFs, extraer texto o completar formularios" supera a "Ayuda con PDFs". Dado que las descripciones ahora hacen el trabajo que solían hacer tus patrones glob, esta es la frase de mayor impacto en cada habilidad.

Mantén el catálogo ligero de forma deliberada. Cada descripción compite por los mismos 50KB, y una habilidad descartada solo aparece como una advertencia en la interfaz de usuario. Habilidades más escasas y precisas superan a las exhaustivas.

Recuerda que el cargador de Zed no gobierna a otros agentes. Su página de instrucciones lo dice directamente: "Los agentes externos y los hilos de terminal pueden leer sus propios archivos de instrucciones nativos directamente. No asumas que el cargador de instrucciones de Zed controla esos agentes". Si ejecutas Claude o Codex a través de Zed como agentes externos, leerán sus propios archivos, un límite que trazamos en giving Zed's external agents the context they don't inherit.

Espera un detalle de caché al editar habilidades: "Los cambios en el name o la description de una habilidad invalidan la caché de prompts del modelo para la sesión actual". Edita los cuerpos libremente a mitad de la sesión; agrupa tus reescrituras de descripciones en lotes.

Windsurf y Zed coinciden en más aspectos que la mayoría de los pares de herramientas. Comparten una ruta de habilidades, un formato de habilidades y un modelo de divulgación progresiva, razón por la cual la mitad de esta migración correspondiente a las habilidades es casi gratuita.

Discrepan en una cosa que le cuesta días a la gente: Windsurf descubre muchos archivos de reglas y decide por archivo si los inyecta, mientras que Zed lee la primera coincidencia de una lista fija de nueve entradas. Si realizas una sola acción de esta guía, que sea eliminar cada archivo que tenga prioridad sobre AGENTS.md en la raíz de tu repositorio; y si realizas una segunda, que sea escribir por qué existen tus reglas antes de fusionar doce archivos en uno.