Guías

Agentes de código

Un agente que escribe tu app también escribe el texto que lleva dentro. Hay tres formas de darle el ciclo, y responden a preguntas distintas: correr los comandos, aprender las reglas o leer la documentación.

Tres canales, tres preguntas

Canal	Qué resuelve	Qué necesita
Servidor MCP	Correr el ciclo: diagnosticar, envolver el texto que ya escribiste, extraer, traducir	Una línea en tu cliente MCP
Agent Skill	Escribir bien el código a la primera: las reglas que mantienen el ciclo seguro	Un archivo copiado a tu proyecto
llms.txt	Encontrar la página correcta: un índice de esta documentación en markdown	Nada, ya se sirve solo

Se acumulan. La skill enseña las reglas, el servidor hace el trabajo y el índice es lo que lee un agente cuando necesita más que cualquiera de los dos. Ninguno puede aprobar una traducción automática, y eso es a propósito: al final de la página está el porqué.

El servidor MCP

@verbaly/mcp expone el ciclo como herramientas sobre el Model Context Protocol, así que un agente lo corre sin tocar una terminal. Funciona con cualquier cliente MCP, Claude Code y Cursor incluidos.

claude mcp add verbaly -- npx -y @verbaly/mcp

El servidor lee tu verbaly.config desde el directorio donde arranca. Pasa --root cuando ese no sea tu proyecto, y además cada herramienta acepta su propio root para un monorepo con más de una app.

Las seis herramientas

Van en el orden en que un agente se encuentra un proyecto: averiguar qué falla, envolver el texto que ya está, y recién entonces correr el ciclo sobre él.

Herramienta	Qué hace	¿Escribe?
verbaly_doctor	Revisa todo el montaje de una vez: configuración, catálogos, el plugin de tu framework, los tipos generados, los archivos que no pudo leer y cada traducción que el gate rechazaría	No
verbaly_wrap	Encuentra el texto escrito directamente en tu JSX y lo envuelve para que el compilador pueda tomarlo. Por defecto solo informa, y el texto que no puede tratar con seguridad lo lista en vez de reescribirlo	Sí
verbaly_extract	Escanea tu código, añade los mensajes nuevos a los catálogos y regenera los tipos	Sí
verbaly_status	Cobertura por idioma, y cuántas traducciones automáticas están esperando a una persona	No
verbaly_missing	Todo lo que haría fallar la puerta de CI: traducciones que faltan, keys desconocidas y traducciones que existen pero no pueden renderizar lo que renderiza el original	No
verbaly_translate	Rellena los huecos con el proveedor que tengas configurado y lo guarda todo como borrador	Sí

Las tres que solo leen se lo dicen al cliente, así que un agente puede mirar el estado de tu proyecto sin permiso para cambiar nada. Las que escriben avisan antes: extract y translate aceptan un dryRun que cuenta qué pasaría, y wrap solo informa salvo que le pidas que aplique.

Cada herramienta responde dos veces: una frase para quien lee la conversación, y la misma respuesta como datos. Un agente que pregunta por la cobertura recibe los números en sí, no una línea que descifrar, así que sigue funcionando aunque cambiemos cómo lo decimos.

Una herramienta que falla vuelve como un mensaje sobre el que el agente puede actuar, nunca como un servidor caído: un config que falta lo dice, y un catálogo que no es JSON válido también.

Traducir es el único paso que puede cortarse a medias, porque sale a la red. Cuando una parte no vuelve, el resto queda guardado igual y la respuesta nombra exactamente qué mensajes faltan, así que volver a pedirlo cuesta solo lo que falta.

La Agent Skill

Un servidor le dice a un agente qué puede correr. Una skill le dice qué escribir. La Agent Skill de Verbaly vive en el repositorio y lleva el ciclo más las reglas que lo mantienen seguro, así que el agente deja de inventarse keys de catálogo a mano.

npx degit AronSoto/verbaly/skills/verbaly .claude/skills/verbaly

Las reglas que lleva son las que se prestan a equivocación desde fuera: las keys se generan y jamás se escriben a mano, "" en un catálogo significa sin traducir, los placeholders y las etiquetas tienen que sobrevivir a la traducción tal cual, y los enlaces van por etiqueta con nombre más un mapa de enlaces, nunca un <a href> literal dentro de un mensaje.

llms.txt

Este sitio sirve /llms.txt, un índice en markdown de cada página de documentación con una línea sobre lo que cubre. Se genera desde el mismo menú lateral que estás viendo, así que no puede desincronizarse de la documentación real.

Es para el agente que lee antes de escribir. Apunta el tuyo ahí cuando necesite el mapa completo, y a una sola página cuando necesite una respuesta.

Por qué un agente no puede aprobar su propia traducción

Todo lo que produce verbaly_translate es un borrador, y los borradores no se publican: con verbaly check --drafts en CI, el build sigue fallando mientras quede alguno. La herramienta que los acepta, verbaly review --approve, no se le expone a los agentes a propósito.