Compré pimentón tres veces porque lo guardaba en tres sitios.
El apartamento venía con un especiero encima de los quemadores. Cuando se llenó, organicé un cajón. Después añadí un estante en la despensa. Cada sitio tenía su lógica en el momento en que lo monté. Pero entre los tres hacían que encontrar el pimentón fuera sorprendentemente difícil.
El problema salió a la luz cuando un amigo vino a cocinar a casa. Me pasé la noche detrás de él: la sartén buena está debajo del fregadero, esa sal es gruesa, el horno calienta más de la cuenta. Él cocina mejor que yo. Solo necesitaba indicaciones para moverse por mi cocina.
En agosto me di cuenta de que había hecho lo mismo con nuestros repositorios.
Las reglas duplicadas
Los proyectos de OwlMeans llevan algo más que código fuente. Llevan instrucciones para el agente de programación: dónde está cada cosa, qué comandos ejecutar y qué tiene que sobrevivir a una edición.
Trabajábamos con Claude Code y con GitHub Copilot. Una regla para uno se convertía en una habilidad en .claude/skills/; el otro recibía una copia en .github/instructions/. Los mapas del proyecto, los scripts de shell y la memoria fueron acumulando sus propios gemelos.
Un solo commit tocó doce archivos de habilidades y once versiones espejo. Cada corrección traía una pequeña duda: ¿había corregido también la otra copia?
En OwlMeans Common, la limpieza eliminó 213 archivos de instrucciones duplicados. Esa cifra describe el cambio en nuestro repositorio. No dice nada de cuánto más rápido se volvió un agente.
Lo que quedó en su lugar fue una única carpeta canónica .agents/ y un AGENTS.md en la raíz. Las habilidades, las reglas, los scripts y la memoria compartida tenían cada uno su sitio. Los archivos específicos de cada agente pasaron a ser puentes hacia esa fuente.
El formato compartido
AGENTS.md le da a un agente las instrucciones del proyecto en un archivo Markdown corriente. La especificación de Agent Skills define cómo se organizan la carpeta de una habilidad y su SKILL.md.
Resuelven problemas distintos. El archivo de la raíz le dice al agente cómo trabajar en este repositorio. Una habilidad guarda un procedimiento que el agente puede cargar para una tarea concreta.
La especificación de las habilidades no fija el directorio padre. Elegir .agents/skills/ fue una convención nuestra, pensada para las herramientas que usábamos. No debería presentarlo como un directorio que todos los agentes se hayan comprometido a descubrir.
La diferencia importa cuando añades otra herramienta. Un texto compartido solo sirve si la herramienta lo carga de verdad.
El puente para Claude
En la configuración de agosto conservamos un CLAUDE.md pequeño cuya primera instrucción era @AGENTS.md. Un script generaba un enlace simbólico por habilidad en .claude/skills/.
Así, Claude Code tenía los puntos de entrada que esperaba, sin que nosotros tuviéramos otro juego de instrucciones que mantener. El hook de sesión actualizaba los enlaces.
Llegamos a los enlaces por habilidad a base de probar. Enlazar el directorio completo de habilidades había fallado con nuestra configuración. Es una observación sobre aquel montaje, no una regla permanente para todas las versiones futuras de Claude Code.
El 15 de octubre de 2026 volví a mirar la petición de compatibilidad nativa con AGENTS.md. Seguía abierta. Si montas esta configuración hoy, consulta la documentación actual de Claude Code sobre la memoria y comprueba qué lee. Nuestro puente sigue importando la fuente de forma explícita.
Instrucciones que merecen conservarse
Mover archivos acabó con la duplicación. No hizo que su contenido fuera útil.
Una habilidad genérica sobre cómo escribir buen código le dice poco a un agente sobre nuestros puntos de entrada o nuestros slots de proyecto. Las instrucciones útiles explican esta base de código: qué paquete es dueño de un recurso, qué límite tiene que respetar un cambio y qué comprobación detecta el error.
Los paquetes de OwlMeans Common traen pautas junto a su código. Un proyecto generado puede instalarlas con @owlmeans/agent-skills. Los metadatos del paquete aportan las instrucciones; el repositorio aporta el contexto local.
Y alguien tiene que seguir manteniendo las dos cosas.
Nuestra regla es repasar las habilidades afectadas después de cada trabajo planificado de cierta envergadura. Si cambió un comando, una ruta o un comportamiento, hay que reescribir la instrucción que lo describe. Una habilidad enuncia la regla vigente. Una nota fechada que avisa de que la regla antigua dejó de funcionar obliga al siguiente agente a decidir qué párrafo manda.
Esto tiene un coste. Algunas tareas terminan con trabajo de documentación cuando el código ya pasa las comprobaciones. Prefiero pagarlo mientras todavía recuerdo por qué cambió la implementación.
La memoria, por subsistemas
La memoria tenía otro tipo de duplicación. Lo que llevábamos era una crónica de tareas.
Un archivo con el nombre de una investigación me contaba qué había pasado esa semana. Para saber qué era cierto en ese momento sobre el enrutamiento, tenía que leer varias investigaciones y averiguar cuál dejaba obsoletas a las demás.
Reorganizamos el almacén en torno al proyecto: enrutamiento, traducciones, despliegue, servicios externos. Un índice relaciona esos nodos con las rutas que cubren. El agente lee primero ese mapa y después abre los nodos que le interesan.
Cada escritura actualiza en su sitio el dato correspondiente. No añade otro relato fechado debajo de uno obsoleto. El trabajo que sigue en curso puede llevar fecha, pero las pautas ya asentadas no deberían obligar a reconstruir la sesión.
En el repositorio de la plataforma, veinte archivos cronológicos se convirtieron en once nodos estructurales. Esas fueron nuestras cifras durante la reorganización. Lo útil fue que ya sabía dónde mirar.
Aun así, un almacén de memoria necesita correcciones. Su forma no impide que se registre una suposición falsa, y un índice breve no garantiza que el agente cargue la página correcta. Lo que nos da es un lugar donde reparar la suposición cuando la encontramos.
Las dos semanas
La reorganización llevó dos semanas. Parte de ese tiempo se me fue en las convenciones de directorios y parte en los pequeños problemas de compatibilidad que solo aparecen cuando ejecutas otro agente.
Los proyectos que genera OwlMeans traen pautas para agentes. En Servicios, nuestro trabajo también incluye adaptar las habilidades y los metadatos al proyecto que entregamos. Mantener útiles esas pautas sigue siendo tarea de quien se ocupe del repositorio.
Mi amigo sigue necesitando saber que el horno calienta más de la cuenta. Al menos ahora tengo un solo sitio donde apuntarlo.
Publicado originalmente el 13 de agosto de 2026. Revisado el 15 de octubre de 2026 para distinguir los formatos compartidos de nuestra convención de directorios y para fechar las observaciones sobre la compatibilidad de las herramientas.