Durante unos dos años mi cocina funcionó con tres sistemas. El especiero que venía con el piso, atornillado a la pared sobre la placa. El cajón que organicé yo mismo cuando el especiero se llenó. Y un estante en la despensa para todo lo que no cabía en ninguno de los dos.
En los tres había pimentón. Lo sé porque lo compré tres veces.
No es un desastre; se vive con ello. Lo que me rompió fue un sábado en que un amigo cocinó en mi casa y me pasé la noche entera de pie detrás de él — no, la sartén buena está debajo del fregadero, esa sal es gruesa, echa la mitad, el horno calienta de más. Cocina mejor que yo. Simplemente no podía trabajar en mi cocina sin mí dentro.
Hace dos semanas me di cuenta de que nuestros repositorios estaban exactamente así.
Tres especieros, una cocina
OwlMeans Common es la biblioteca sobre la que se apoya cada proyecto que construimos, y cada uno de esos proyectos lo construye un agente. Así que un repositorio aquí no guarda solo código: guarda las instrucciones que el agente lee antes que nada — cómo ordenamos las cosas, qué no se hace nunca, de qué se encarga cada script.
Dábamos soporte a dos agentes, Claude Code y GitHub Copilot, y cada uno quería su propio estante. Así que cada regla se escribía dos veces — una como .claude/skills/<nombre>/SKILL.md y otra como .github/instructions/<nombre>.instructions.md. Dos archivos de contexto siempre cargados, casi idénticos. Dos mapas del repositorio. El mismo script de shell, byte a byte, en dos directorios. Dos carpetas de memoria separándose en silencio.
El impuesto está a la vista en el historial: un commit de aquella época toca doce archivos de habilidades y sus once gemelos espejados. Nadie decidió que fuera buena idea. Se acumuló, igual que se acumula un tercer especiero.
Un estante, una tarjeta
Así que lo arranqué. Todo se mudó a una sola carpeta — .agents/, con las habilidades, las reglas, los scripts y la memoria — y todo lo que un agente debe leer antes de empezar se mudó a un único archivo en la raíz: AGENTS.md. En OwlMeans Common eso borró doscientos trece archivos de instrucciones duplicados. CLAUDE.md, que antes eran ochenta y seis líneas de absolutamente todo, hoy pesa seiscientos bytes.
El estante no lo inventé yo. Cogí el que todos los demás ya habían acordado — y cómo llegaron a ese acuerdo es justo la razón por la que me fío de él.
En mayo de 2025 Amp propuso un único archivo llamado AGENT.md, en singular. Después OpenAI eligió el plural para Codex — y el plural es precisamente el punto, porque un mismo archivo lo comparten muchos agentes. Amp podría haber peleado por su nombre. En lugar de eso escribieron: «en vez de insistir en lo que se nos ocurrió a nosotros, decidimos que preferíamos un único estándar», con la condición de que OpenAI asegurara el dominio agents.md. OpenAI lo hizo, y Amp se cambió.
Pasó de veinte mil repositorios en agosto de 2025 a más de sesenta mil hoy, y en diciembre se donó a la Agentic AI Foundation, bajo la Linux Foundation. Veintitrés herramientas lo leen ya de forma nativa: Codex, Cursor, Copilot, Gemini CLI, Zed, Windsurf, Devin, Jules, Aider.
La otra mitad del estante llegó desde la dirección contraria. Agent Skills — el formato SKILL.md — era de Anthropic, y se abrió como especificación pública en diciembre de 2025, tutelada por esa misma fundación. Define exactamente cómo es una carpeta de habilidad y no dice absolutamente nada sobre dónde va esa carpeta. Así que cada fabricante eligió su directorio padre. Codex escanea .agents/skills. Copilot acepta .agents/skills. Eso decidió por mí.
El invitado que trae sus propios cuchillos
Hay un agente que no lee la tarjeta de la puerta.
Claude Code lee CLAUDE.md, y solo CLAUDE.md. La petición de que lea también AGENTS.md está abierta desde marzo — la issue #34235 del repositorio de Claude Code, dentro de un grupo con miles de votos — y sigue abierta. Lo cual tiene su gracia, dado que fue Anthropic quien escribió el formato de habilidades que ocupa la otra mitad de la carpeta.
El arreglo tentador es una segunda copia. Todo el que lo intenta cuenta el mismo final: dos archivos editados a mano siempre se separan, y un archivo de instrucciones que se ha separado de la realidad es peor que no tener archivo, porque el agente se lo cree.
Así que hicimos un puente. CLAUDE.md sobrevive con seiscientos diez bytes, idéntico byte a byte en todos los repositorios, y su primera línea es @AGENTS.md. El resto es una nota que dice que las habilidades viven en .agents/skills/ y que nunca deben escribirse en otro sitio. Después, un pequeño script de shell genera un symlink por habilidad dentro de un .claude/skills/ ignorado por git, y un hook de sesión los regenera cada vez. Por habilidad, no por directorio: Claude Code acepta una entrada de habilidad enlazada, pero no una carpeta de habilidades enlazada — de esas cosas que solo se aprenden probando.
Recetas de mi puño y letra
El segundo cambio importa más que la carpeta.
Un libro de cocina dice hornear veinticinco minutos a ciento ochenta. La tarjeta de dentro de mi armario dice veintidós minutos, al fondo a la izquierda, este horno calienta de más. Las dos son correctas; solo una habla de mi cocina.
Los proyectos de OwlMeans no instalan habilidades genéricas: cada uno cultiva las suyas. Nuestro repositorio de la plataforma lleva diecinueve; el repositorio del agente, al lado, veintitrés — y donde los nombres coinciden, el contenido no: execution significa la abstracción en uno y el uso de esa abstracción del lado de la plataforma en el otro. Eso no es duplicación. Son dos cocinas distintas.
El problema de una tarjeta pegada a una puerta es que los hornos cambian. Por eso ahora el harness cierra el círculo. Aprobar un plan es también aprobar la pasada que viene después: cuando el trabajo aterriza, el agente vuelve sobre las habilidades que ese trabajo tocó, reescribe las que han dejado de ser ciertas, y el informe final tiene que traer una tabla de qué actualizó, qué creó y qué no necesitó nada — con su motivo. Un informe sin esa tabla cuenta como inacabado.
Y una regla más, que me gusta más de lo que esperaba: una habilidad enuncia las reglas vigentes, nunca lo que cambió. Nada de boletines fechados, nada de antes X, ahora Y. La prueba es que una habilidad terminada debe leerse como si la cosa siempre hubiera sido así.
Estantes por plato, no por fecha de compra
El tercer cambio es el último que soltaría.
Los agentes ahora tienen memoria y, si los dejas, la llevan como un diario. La nuestra lo era: archivos con nombre de lo que había pasado, tipo slot-status-reconciler.md o null-error-investigation.md, cada uno abriendo con lo que estábamos haciendo esa semana. Eso es un registro de la compra. Anota perfectamente cuándo compraste algo y no dice nada sobre lo que pide la cena de hoy.
Así que reagrupamos los estantes por plato. Un nodo de memoria se llama ahora como una parte real del proyecto — un subsistema, un asunto como el enrutado o las traducciones, un servicio externo o el propio repositorio — y nunca como un evento, una fecha o una tarea. Su cuerpo se divide en qué es cierto, qué debe cumplirse, qué te muerde y dónde mirar; y las fechas se permiten en exactamente una sección: la del trabajo aún en curso.
El trabajo de verdad lo hace el índice. Cincuenta líneas como mucho, una por nodo, cada una con las rutas que ese nodo cubre. El agente lo lee al empezar la sesión y nada más; cuando llega una tarea, cruza las rutas de la tarea con esas líneas y abre el nodo o los dos nodos que encajan. Nunca lee el almacén entero.
Y las escrituras son fusiones. Cuando algo cambia, reescribes la línea en su sitio — nunca añades debajo una corrección fechada, o el archivo vuelve a convertirse en un diario sin que te des cuenta. Nuestro repositorio de plataforma pasó de veinte archivos cronológicos a once nodos estructurales, y encontrar cualquier cosa dejó de ser una excavación.
Puedes tenerlo sin más
Da un paso atrás y nada de esto es exótico. Una carpeta en lugar de tres. Una tarjeta en la puerta que explica cómo funciona la casa. Recetas de tu puño y letra, al día. Estantes agrupados por lo que de verdad cocinas.
Aun así costó dos semanas, y la mayor parte se fue en cosas que no se pueden buscar: que el estándar existe y cuál ganó, que una carpeta de habilidades enlazada falla donde sí funcionan los enlaces por habilidad, que la memoria organizada por eventos se pudre y la organizada por estructura no.
Así que aquí va la oferta honesta.
Si estás construyendo algo real con un agente, vas a chocar con esto. Añadirás un segundo agente y empezarás a escribirlo todo dos veces. Criarás una carpeta de memoria que se lee como un diario que nadie quiere abrir. Puedes hacer lo que hice yo y quemar dos semanas. A mí me compensó — es mi trabajo.
No es el tuyo.
Esto es lo que entrega OwlMeans. Cada proyecto que construye la Plataforma sale con el harness ya dentro — .agents/, AGENTS.md, habilidades hechas a medida de ese proyecto, un grafo de memoria con la forma de su propio código — y OwlMeans Services le ajusta lo mismo a una base de código que ya tienes. Todo es tuyo. Sin lock-in y sin agente de la casa: Codex, Copilot, Claude Code, lo que salga el trimestre que viene — todos leen el mismo estante.
Cualquier cocinero, cualquier cocina. Ahórrate mis dos semanas — puedes tenerlo sin más.
OwlMeans construye SaaS TypeScript full-stack a partir de tus historias de usuario — tipado, listo para SSO y tuyo para seguir construyendo con cualquier agente. Descubre lo que puede hacer →