Por qué un archivo de skill correcto puede ser invisible
Una skill solo influye en el agente si su nombre y descripción entran en el catálogo que ve el modelo. La documentación de Zed menciona cuatro condiciones que dejan fuera un archivo, además de una que lo deja entrar con una advertencia.
El catálogo tiene un presupuesto de bytes. Esto es lo que nadie se espera:
"Presupuesto de catálogo de 50KB. El tamaño total de todos los nombres y descripciones de las skills está limitado a 50KB. Las skills que no quepan se descartan del catálogo con una advertencia en la interfaz de usuario. Mantén las descripciones concisas."
Ten en cuenta qué se está midiendo: nombres y descripciones, no los cuerpos. Por lo tanto, una skill puede ser descartada debido a lo detalladas que sean las descripciones de tus otras skills. Agregar una skill puede expulsar a otra en la que has confiado durante meses, y la única señal es una advertencia en la interfaz de usuario que quizás no hayas visto.
No se admite la anidación. Zed es inequívoco:
"Solo diseño plano. Las skills deben ser hijas directas de la raíz de skills. No se descubren carpetas anidadas como ~/.agents/skills/group/my-skill/."Si has estado organizando las skills en carpetas —y el instinto de agrupar por dominio es bueno— esas skills no solo pierden prioridad, sino que directamente no se encuentran.
Los worktrees que no son de confianza no aportan nada. Esto sorprende a la gente el primer día de un nuevo repositorio:
"Las skills locales del proyecto solo se cargan desde worktrees de confianza. Las skills de un proyecto recién clonado o que no es de confianza se excluyen del catálogo y de los comandos slash hasta que otorgues confianza."
Clona un repositorio que incluya skills, ábrelo y verás que ninguna de ellas existe todavía. Ni en el catálogo, ni como comandos slash.
Un campo de frontmatter puede excluir una skill. Zed documenta esto como una característica, y lo es: "Agrega disable-model-invocation: true al frontmatter de una skill para evitar que el agente la seleccione de forma autónoma". Totalmente razonable, y fácil de olvidar que lo configuraste hace seis semanas.
Y un caso casi fallido que vale la pena conocer. Sobre las descripciones: "Manténla por debajo de 1024 bytes; las skills con descripciones más largas se siguen cargando, pero con una advertencia". Por lo tanto, una descripción demasiado larga no excluye la skill, pero consume más de ese presupuesto de 50KB de lo que debería, que es cómo un problema de descripción se convierte en el problema de exclusión de otra persona.
Hay un sexto comportamiento que no es una exclusión pero explica una confusión diferente: "Si una skill global y una local del proyecto comparten el mismo nombre, la skill local del proyecto tiene prioridad". Tu skill puede estar presente y oculta (shadowed) en lugar de ausente.
El patrón en todo esto es el que se trata en por qué los agentes ignoran tus archivos de instrucciones: un archivo que la herramienta nunca cargó se ve idéntico a un archivo que el modelo decidió no usar, y ambos necesitan soluciones completamente diferentes.
Qué intenta la gente en su lugar
Reescribir la descripción para que sea más atractiva. El primer paso habitual, y solo ayuda si la skill está en el catálogo y está perdiendo en una evaluación de relevancia. Si se descartó por presupuesto, anidación o confianza, una mejor descripción no cambia nada, y una más larga empeora el problema del presupuesto.
Reiniciar Zed. Comprensible pero innecesario para cambios de contenido. Zed documenta la recarga en vivo: "Agregar, eliminar o editar un SKILL.md surte efecto de inmediato sin reiniciar la sesión". Reiniciar sí resuelve la cuestión de la confianza si aceptas el aviso al volver a entrar, que es probablemente por lo que a veces parece funcionar.
Invocar la skill explícitamente. Un buen diagnóstico, y ten en cuenta lo que demuestra. Si una invocación explícita funciona pero el uso autónomo nunca ocurre, te enfrentas a un problema de disable-model-invocation o de descripción, no a un problema de descubrimiento. Si el comando slash también falta, estás en territorio de confianza, ya que Zed excluye las skills de proyectos no confiables "del catálogo y de los comandos slash".
Copiar la skill a la raíz global. Esto suele solucionarlo a menudo, por lo que es un callejón sin salida muy satisfactorio: funciona porque la raíz global es confiable y plana, por lo que accidentalmente has eliminado dos causas a la vez sin aprender cuál se aplicaba. El próximo proyecto tendrá el mismo problema.
Mover todo a un archivo de instrucciones en su lugar. Tentador, y cambia la economía en lugar de resolverla: las instrucciones que siempre están cargadas consumen contexto en cada mensaje, que es la razón por la que existen las skills como una superficie bajo demanda. La distinción entre ambas, y por qué una no sustituye a la otra, se encuentra en por qué las skills de los agentes no son memoria.
La solución: Eliminar las cuatro causas en un orden fijo
Haz esto en secuencia. Cada paso es sencillo, cada uno es concluyente, y el orden importa porque las comprobaciones posteriores no tienen sentido si una condición anterior está activa.
Paso 1: Resuelve la confianza y el diseño antes de mirar cualquier otra cosa
Ambos son estructurales, y ambos son de sí o no.
Confirma que el worktree es de confianza. Si clonaste este repositorio recientemente y nunca otorgaste confianza, todas las skills locales del proyecto quedarán excluidas, y la ausencia de comandos slash para esas skills es tu confirmación.
Luego, aplana. Recorre las raíces de las skills —la raíz a nivel de usuario y la del propio worktree— y comprueba que cada skill sea una hija directa. El ejemplo de Zed sobre lo que falla es preciso: una ruta como ~/.agents/skills/group/my-skill/ no se descubre. Si encuentras carpetas agrupadas, esa es tu respuesta, y la solución es subirlas un nivel en lugar de renombrar nada.
Vale la pena saberlo mientras estás allí: .agents/skills/ no es una convención exclusiva de Zed. Windsurf, Zencoder y OpenHands leen skills de la misma ruta, y Factory lee .agents/ como uno de sus directorios de compatibilidad. Un diseño agrupado que otra herramienta toleraba es exactamente el tipo de cosas que llega con un repositorio compartido y silenciosamente te cuesta skills en Zed.
Paso 2: Audita el presupuesto del catálogo en su totalidad, no por skill
Esta es la comprobación que nadie hace, porque el presupuesto es compartido y el fallo se atribuye al archivo equivocado.
Suma la longitud del nombre y la descripción de cada skill en ambas raíces. Estás buscando el total frente a un límite de 50KB en nombres y descripciones. Luego, busca la advertencia que Zed dice que muestra en la interfaz de usuario cuando las skills no caben; si está ahí, tienes tu causa, y la solución es recortar descripciones en lugar de eliminar skills.
Mantén cada descripción por debajo de la guía de 1024 bytes mientras lo haces. Zed permite que se carguen descripciones más largas con una advertencia, pero consumen un presupuesto que una descripción más corta no consumiría, y la skill que terminen expulsando no será la que estabas editando.
Paso 3: Separa "no está en el catálogo" de "decidió no usarlo"
Ahora, y solo ahora, se pueden responder las preguntas sobre el frontmatter y la relevancia.
Comprueba si existe disable-model-invocation: true. Si está configurado, la skill se ha excluido deliberadamente de la selección autónoma y solo se ejecutará cuando lo solicites.
Comprueba si hay una colisión de nombres con una skill global, ya que la local del proyecto tiene prioridad y la global que esperabas está quedando oculta.
Luego, si la skill está presente y el agente sigue sin recurrir a ella, estás en territorio de descripciones, y ten en cuenta el coste de iterar ahí. Zed documenta que "los cambios en el name o la description de una skill invalidan la caché de prompts del modelo para la sesión actual", por lo que una optimización rápida tiene un precio real a mitad de la sesión.
Una restricción más a tener en cuenta antes de empezar a reestructurar: "Mantén el cuerpo de SKILL.md por debajo de 500 líneas. Mueve el material detallado a archivos de referencia y enlázalos desde el cuerpo". Los cuerpos largos son una preocupación independiente del catálogo, pero son la razón por la que una skill que sí se activa puede seguir sin ser útil.
Configurando esto en MemoryLake
Las cuatro causas anteriores son mecánicas, y una vez que las hayas solucionado te quedará la pregunta más difícil: qué parte de este conocimiento debería haber estado en una skill en primer lugar. Los procedimientos reutilizables pertenecen a las skills. Las decisiones permanentes —por qué existe esta convención, qué enfoque rechazaste, cuál es realmente la restricción— no son procedimientos, y vincularlas al catálogo de un solo editor las coloca detrás de un presupuesto de bytes y un aviso de confianza.
MemoryLake mantiene esa segunda categoría como una capa que todas las herramientas leen, de modo que las decisiones no compiten con tus skills por el espacio del catálogo y no desaparecen en un repositorio recién clonado.
Paso 1: Crea una clave API
Inicia sesión, abre la configuración de tu espacio de trabajo y genera una clave API. Esta es la credencial que tu editor y tus agentes utilizan para leer la misma capa, así que créala una vez y mantenla accesible desde cada máquina en la que trabajes.
Paso 2: Sube tus primeras memorias
Traslada el material que actualmente está rellenando las descripciones de tus skills: las razones detrás de las convenciones, las restricciones que hacen que el enfoque obvio sea incorrecto, las decisiones que no quieres volver a discutir. Descripciones más cortas, catálogo más pequeño, el mismo conocimiento disponible.
Paso 3: Conecta tu IA y agentes
Conecta Zed y cualquier otra herramienta en la que trabajes. Las decisiones permanentes llegan a todas partes, y tus skills vuelven a ser lo que mejor se les da: procedimientos que el agente puede utilizar bajo demanda.
Qué cambia esto en la práctica
La primera diferencia es que el presupuesto deja de ser un juego de suma cero. Cuando las descripciones son cortas porque el razonamiento reside en otra parte, agregar una skill deja de expulsar a otra, y la advertencia en la interfaz de usuario deja de ser algo que aprendes a ignorar.
La segunda es que un clon recién hecho se puede usar de inmediato. El control de confianza es un valor predeterminado de seguridad sensato, pero el conocimiento que un nuevo colaborador necesita en su primera hora no debería estar bloqueado por él. El vacío que deja es el mismo que se describe en cuando Zed olvida el contexto del proyecto.
La tercera es que tu instinto organizativo deja de ser castigado. Querías carpetas porque tienes treinta skills en cinco dominios. Mantén las skills planas, coloca el razonamiento del dominio en una capa que no tenga restricciones de diseño y obtendrás la estructura sin perder el descubrimiento.
La cuarta se manifiesta con los agentes externos. Zed se asegura de señalar que los agentes que no controla leen sus propios archivos de instrucciones, lo cual cubrimos en los agentes externos de Zed y el contexto. Una capa fuera del catálogo del editor es lo único que todos ellos pueden compartir.
Buenas prácticas para un catálogo de skills que siga siendo detectable
Trata las descripciones como espacio de catálogo, no como documentación. Una frase sobre lo que hace y cuándo usarla. Todo lo demás va en el cuerpo o en archivos de referencia.
Audita el total después de cada adición. El límite se aplica a la suma, por lo que el número significativo nunca es por skill.
Mantén el diseño plano incluso cuando parezca incorrecto. Hijas directas de la raíz, sin carpetas de agrupación. Codifica la agrupación en los nombres si lo necesitas.
Otorga confianza deliberadamente al clonar. Y recuerda que hasta que lo hagas, las skills del proyecto no estarán presentes ni en el catálogo ni en los comandos slash, lo que hace que su ausencia sea una mala señal de cualquier otra cosa.
Comprueba si hay ocultamiento (shadowing) antes de depurar el contenido. Una skill local del proyecto con el mismo nombre gana, por lo que la global que estabas leyendo puede no ser la que está en juego.
No alteres el requisito de autorización. Zed establece que el agente no puede editar archivos SKILL.md ni sus recursos empaquetados sin tu autorización explícitamente, incluso en un proyecto de confianza, para evitar que una conversación comprometida modifique las skills que rigen las futuras. Ese es un buen valor predeterminado; no busques formas de eludirlo.
Decide qué pertenece realmente a una skill. Procedimientos, sí. Razonamiento, no. La cuestión de la clasificación es la misma que en cuánta memoria deberías darle a un agente de IA, y hacerlo bien es lo que mantiene el catálogo pequeño.
Conclusión
El sistema de skills de Zed está bien documentado y todas sus restricciones están publicadas: un presupuesto de 50KB en nombres y descripciones, solo hijas directas de la raíz, solo worktrees de confianza y un campo de exclusión voluntaria. Lo que las hace difíciles es que cuatro causas independientes producen un mismo síntoma idéntico, y tres de ellas dejan tu archivo con un aspecto perfectamente correcto.
Así que sigue el orden. Confianza y diseño primero, porque son estructurales. Presupuesto segundo, como un total. Frontmatter y relevancia al final, porque esas preguntas solo tienen sentido una vez que la skill está realmente en el catálogo. Y luego hazte la pregunta que subyace a todo el ejercicio: si lo que intentabas enseñarle al agente era realmente un procedimiento, o si era una decisión que nunca debería haber estado compitiendo por el espacio del catálogo en primer lugar. Vale la pena entender en general qué cargan realmente las herramientas y en qué orden; lo que realmente leen los agentes de programación cubre el panorama general.