I noticed the problem the third time I updated the same sentence across four different files. The sentence was simple: "this project uses TypeScript strict mode." It lived in CLAUDE.md, in .cursorrules, in .github/copilot-instructions.md, and in GEMINI.md. Four tools, four formats, four maintenance surfaces. The same thought, written four times, for four different audiences that are all, fundamentally, trying to do the same thing: understand my project.
Herald started there. Not from a thesis about standards, but from the fatigue of repetition.
The agentic tooling space has exploded in the last year. Claude Code, Cursor, Copilot, Gemini CLI, Windsurf, Kiro, Roo Code, the list grows monthly. Each tool is genuinely useful. Each tool also has its own convention for how you communicate your project's rules, architecture, and intentions to it. Most of these conventions are just Markdown files with different names in different locations.
The problem is not that these files exist. The problem is that they represent the same knowledge, fragmented. Every new tool you adopt means a new file to create. Every architectural decision you update means a new round of edits. Every convention you refine drifts, slightly, across each file, until the tools are operating from subtly different mental models of your project.
This is not a catastrophic failure. It is a slow erosion. And slow erosions are the hardest kind to notice.
In ancient Greece, the herald was the trusted messenger between worlds. Between armies. Between cities. Between gods. Heralds were inviolable , their message was always delivered, always trusted, always first. They did not carry their own opinion. They carried the official word of whoever sent them.
The word itself comes from Old French herault, rooted in the Frankish hariwald, from hari, army, and wald, rule or command. The herald was, etymologically, the one who commanded the army's voice. Not a soldier. Not a general. The intermediary. The one whose presence guaranteed safe passage and whose words carried institutional weight regardless of who was listening.
I chose the name because the analogy is almost exact. .herald/ arrives before any agent touches your code. It carries your project's official word: the architecture, the conventions, the rules, the intent. Every tool reads from the same source. No translation required.
Herald defines a folder, not a file. .herald/ sits at the root of your project and organizes context into five layers. context/ holds the foundational knowledge: what the project is, how it's structured, what conventions it follows. skills/ holds reusable capabilities your agents can invoke , compatible with the existing SKILL.md standard. commands/ holds named single-shot tasks, the equivalent of slash commands that work across every tool. agents/ holds named subagents with precise roles: a reviewer, a tester, a documentation writer. permissions/ holds allow and deny rules, committed to git, auditable, explicit.
Each layer is additive. You can start with only context/ and a main.yaml manifest. The system degrades gracefully. It does not demand completeness before it is useful.
One of the constraints I cared about from the beginning was token cost. A context file that loads ten thousand tokens at session start is not a feature. It is a tax. Herald addresses this through tiered loading. The manifest and context/ load always, at around two hundred tokens. Skill bodies load only when the agent's task matches the skill. Reference files load only when the skill explicitly needs them. If a skill goes unused, it costs nothing.
The philosophy here is that good context is precise context. Not comprehensive. Not exhaustive. Precise.
Herald does not ask you to abandon your existing tooling. The CLI , npx herald-agents compile all , reads your .herald/ source and generates every vendor file your tools expect. CLAUDE.md, .cursorrules, copilot-instructions.md, GEMINI.md, all of them. You edit once. You compile once. The tools receive what they expect.
This is the same mental model as a build system. You do not hand-edit your dist/ folder. You write source, you compile output, you trust the process.
Herald is not just a folder structure. It is a specification. Version 1.0 defines conformance levels from B1 to B6, a machine-readable schema for main.yaml, detection algorithms for tool builders, and a compatibility layer that coexists with AGENTS.md and other existing conventions without conflict.
I wrote it as a spec because I believe the problem is not mine to solve alone. If the tooling ecosystem is going to converge, it needs a shared language. The spec is that language. The CLI is just one implementation of it.
Herald is not a product with a backend. It is not a service you subscribe to. The spec is CC0 , public domain. The generator runs entirely in the browser, client-side, no data sent anywhere. The CLI requires no account, no token, no registration. If Herald disappears tomorrow, your .herald/ folder still works. The files are plain text. The manifest is readable YAML. The knowledge belongs to you.
I am skeptical of tools that make themselves indispensable by holding your data. Herald is designed to be forgettable in the best sense: you use it once, commit the folder, and never think about vendor formats again.
The agentic era is early. The conventions are still forming. There is a window, right now, where the cost of establishing a shared standard is low and the benefit is high. Herald is my attempt to contribute something to that window: a simple, open, vendor-neutral format that puts the knowledge back where it belongs , in your repository, under your control, readable by anything.
The name felt right from the start. The herald arrives first. It carries the official word. It does not take sides. It does not belong to any one party. It serves whoever sends it.
That is exactly what I wanted.
You can generate your own .herald/ here and explore the spec here.
- A. R. Brea, written 11 Mar 2026
Me di cuenta del problema la tercera vez que actualicé la misma frase en cuatro archivos distintos. La frase era sencilla: «este proyecto usa el modo estricto de TypeScript». Vivía en CLAUDE.md, en .cursorrules, en .github/copilot-instructions.md y en GEMINI.md. Cuatro herramientas, cuatro formatos, cuatro superficies que mantener. La misma idea, escrita cuatro veces, para cuatro audiencias distintas que, en el fondo, intentan hacer lo mismo: entender mi proyecto.
Herald empezó ahí. No a partir de una tesis sobre estándares, sino del cansancio de repetirme.
El espacio de las herramientas agénticas ha explotado en el último año. Claude Code, Cursor, Copilot, Gemini CLI, Windsurf, Kiro, Roo Code; la lista crece cada mes. Cada herramienta es realmente útil. Y cada herramienta tiene también su propia convención para que le comuniques las reglas, la arquitectura y las intenciones de tu proyecto. La mayoría de estas convenciones no son más que archivos Markdown con nombres distintos en ubicaciones distintas.
El problema no es que estos archivos existan. El problema es que representan el mismo conocimiento, fragmentado. Cada nueva herramienta que adoptas supone un nuevo archivo que crear. Cada decisión de arquitectura que actualizas supone una nueva ronda de ediciones. Cada convención que refinas se desvía, ligeramente, en cada archivo, hasta que las herramientas trabajan con modelos mentales sutilmente distintos de tu proyecto.
No es un fallo catastrófico. Es una erosión lenta. Y las erosiones lentas son las más difíciles de detectar.
En la antigua Grecia, el heraldo era el mensajero de confianza entre mundos. Entre ejércitos. Entre ciudades. Entre dioses. Los heraldos eran inviolables: su mensaje siempre se entregaba, siempre se creía, siempre llegaba primero. No llevaban su propia opinión. Llevaban la palabra oficial de quien los enviaba.
La palabra procede del francés antiguo herault, con raíz en el fráncico hariwald, de hari, ejército, y wald, mando. El heraldo era, etimológicamente, quien comandaba la voz del ejército. Ni soldado ni general. El intermediario. Aquel cuya presencia garantizaba un paso seguro y cuyas palabras tenían peso institucional, escuchara quien escuchara.
Elegí el nombre porque la analogía es casi exacta. .herald/ llega antes de que ningún agente toque tu código. Lleva la palabra oficial de tu proyecto: la arquitectura, las convenciones, las reglas, la intención. Todas las herramientas leen de la misma fuente. Sin necesidad de traducción.
Herald define una carpeta, no un archivo. .herald/ se sitúa en la raíz de tu proyecto y organiza el contexto en cinco capas. context/ contiene el conocimiento fundamental: qué es el proyecto, cómo está estructurado, qué convenciones sigue. skills/ contiene capacidades reutilizables que tus agentes pueden invocar, compatibles con el estándar SKILL.md existente. commands/ contiene tareas puntuales con nombre, el equivalente a los slash commands que funcionan en todas las herramientas. agents/ contiene subagentes con nombre y roles precisos: un revisor, un tester, un redactor de documentación. permissions/ contiene reglas de permitir y denegar, versionadas en git, auditables, explícitas.
Cada capa es aditiva. Puedes empezar solo con context/ y un manifiesto main.yaml. El sistema se degrada con elegancia. No exige estar completo para ser útil.
Una de las restricciones que me importaron desde el principio fue el coste en tokens. Un archivo de contexto que carga diez mil tokens al empezar la sesión no es una funcionalidad. Es un impuesto. Herald lo resuelve con una carga por niveles. El manifiesto y context/ se cargan siempre, en torno a doscientos tokens. El cuerpo de las skills solo se carga cuando la tarea del agente encaja con la skill. Los archivos de referencia solo se cargan cuando la skill los necesita explícitamente. Si una skill no se usa, no cuesta nada.
La filosofía es que un buen contexto es un contexto preciso. No exhaustivo. No completo. Preciso.
Herald no te pide que abandones tus herramientas actuales. La CLI, npx herald-agents compile all, lee tu fuente .herald/ y genera todos los archivos de proveedor que esperan tus herramientas. CLAUDE.md, .cursorrules, copilot-instructions.md, GEMINI.md, todos ellos. Editas una vez. Compilas una vez. Las herramientas reciben lo que esperan.
Es el mismo modelo mental que un sistema de build. No editas a mano tu carpeta dist/. Escribes el código fuente, compilas la salida y confías en el proceso.
Herald no es solo una estructura de carpetas. Es una especificación. La versión 1.0 define niveles de conformidad de B1 a B6, un esquema legible por máquinas para main.yaml, algoritmos de detección para quienes construyen herramientas y una capa de compatibilidad que convive con AGENTS.md y otras convenciones existentes sin conflictos.
La escribí como especificación porque creo que no es un problema que me toque resolver solo a mí. Si el ecosistema de herramientas va a converger, necesita un lenguaje compartido. La especificación es ese lenguaje. La CLI es solo una implementación de ella.
Herald no es un producto con backend. No es un servicio al que te suscribes. La especificación es CC0, dominio público. El generador se ejecuta íntegramente en el navegador, en el cliente, sin enviar datos a ningún sitio. La CLI no requiere cuenta, ni token, ni registro. Si Herald desaparece mañana, tu carpeta .herald/ sigue funcionando. Los archivos son texto plano. El manifiesto es YAML legible. El conocimiento te pertenece.
Desconfío de las herramientas que se hacen imprescindibles reteniendo tus datos. Herald está diseñado para ser olvidable en el mejor sentido: lo usas una vez, haces commit de la carpeta y no vuelves a pensar en formatos de proveedor.
La era agéntica está empezando. Las convenciones todavía se están formando. Hay una ventana, ahora mismo, en la que el coste de establecer un estándar compartido es bajo y el beneficio es alto. Herald es mi intento de aportar algo a esa ventana: un formato sencillo, abierto y neutral respecto a los proveedores, que devuelve el conocimiento a donde pertenece: a tu repositorio, bajo tu control, legible por cualquier cosa.
El nombre me pareció el adecuado desde el principio. El heraldo llega primero. Lleva la palabra oficial. No toma partido. No pertenece a ninguna de las partes. Sirve a quien lo envía.
Eso es exactamente lo que quería.
Puedes generar tu propio .herald/ aquí y explorar la especificación aquí.
- A. R. Brea, escrito el 11 mar 2026