Deja que Claude Code configure tu agente de Ghosty

La ficha de un agente en Ghosty Studio tenía cuatro campos: nombre, modelo, identidad y un interruptor para Teams. Un cliente preguntó dónde se le daban archivos, dónde se instalaban skills y dónde se conectaban servidores MCP propios. En ningún sitio. Después preguntó si había API para que lo hiciera un agente. Tampoco.

Esto es lo que cambiamos para que las dos respuestas fueran sí, y lo que encontramos por el camino.

Un formulario de configuración es una API que nadie más puede llamar

La lógica de «guardar la ficha» vivía dentro del action de una ruta del panel. Funcionaba, pero sólo si eras un humano con el navegador abierto en esa URL. Nuestro servidor OAuth2 tenía definido desde hacía semanas el scope agents:write —«crear agentes y cambiar su configuración»— y ningún endpoint lo usaba: se mostraba en la pantalla de consentimiento y no protegía nada.

La plataforma hermana sí lo tenía resuelto: en EasyBits un agente se crea por API con archivos semilla y una lista de servidores MCP, las skills se instalan con un POST que recibe un SKILL.md y sus assets, y todo eso está expuesto como tools para que otro agente lo haga. Aprendimos el contrato (no copiamos el código: son runtimes distintos) y nos quedamos con la parte que importa: la unidad de configuración es una acción con un cuerpo JSON, y la pantalla es un cliente más de esa acción.

La persona que configura un agente ya tiene un agente

Quien crea un agente en Ghosty Studio, en 2026, casi siempre tiene abierto al lado Claude Code, Cursor o Codex. Pide las cosas en su idioma con más precisión de la que pone en un formulario de doce campos, y su agente de código sabe leer un SKILL.md, hacer un curl y comprobar el resultado.

Con eso, la configuración la hace su agente de código. La persona crea el agente en el panel, copia su token, y a partir de ahí habla:

La interfaz de usuario de esa API es una skill de 60 líneas: dice qué endpoint llamar, en qué orden, y qué no hacer (reiniciar una sola vez al final; leer antes de escribir; nunca imprimir el token). Se instala con un comando:

npx skills add https://ghosty.studio

Cinco endpoints y un token que sólo abre una puerta

La API entera cabe en una tabla:

Para autenticar podíamos exigir un cliente OAuth2 registrado, como en la app móvil. Para un agente de código que corre en la laptop de la persona eso es otro formulario. Cada agente ya tenía un token propio —el que usa el editor para conectarse por ACP— y ese token sólo alcanza a ese agente. Quien lo tenga puede configurar a Nora y a nadie más. Si se filtra, se rota desde la ficha y el anterior muere al instante.

Un detalle de diseño que copiamos de nuestra propia API de conversaciones: un token que no corresponde al :id responde 404, no 403. Un 403 confirma que ese id existe, y los ids de agente no son públicos.

La identidad nunca había llegado a la máquina

Al conectar el PATCH de identidad a la función que ya usaba la ficha, fuimos a comprobar dentro de la máquina del agente que el texto llegaba, y no llegaba. Ni por la API ni por la ficha: el campo se guardaba en la base de datos y el cerebro del agente no lo veía nunca. Con el motor que corre Claude dentro de la máquina, el prompt de sistema del arnés se descarta por diseño; el cerebro sólo lee el CLAUDE.md de su directorio de trabajo y sus skills. Y esos dos los reescribía el arranque de la máquina en cada boot, desde la copia horneada en la imagen. La ficha llevaba semanas guardando una identidad que nadie leía, sin un solo error.

La máquina tiene ahora un directorio persistente para lo que es del agente: ahí escribe la API la identidad y las skills, y el arranque lo anexa a lo horneado en vez de pisarlo. Para las skills hubo un cambio más: antes el directorio de skills era un enlace al de la imagen; una skill instalada ahí desaparecía al reiniciar. Ahora se enlaza una por una, las de casa y las del agente, y las del agente ganan si repiten nombre.

npx skills add no acepta un .md: exige un índice

Primer intento: publicar el SKILL.md en una URL y documentar npx skills add https://…/SKILL.md. La CLI contestó «No skills found». No busca un archivo: busca un índice de descubrimiento en /.well-known/skills/index.json (RFC 8615, el mismo mecanismo de .well-known que usan los certificados o los enlaces de apps), y de ahí baja cada archivo listado.

Publicar ese índice son 40 líneas, con una trampa: el servidor estático ignora los directorios que empiezan por punto, así que un public/.well-known/ daba 404 sin avisar. El índice se genera por ruta a partir de la carpeta de skills. A cambio, el comando queda en npx skills add https://ghosty.studio, y cuando publiquemos una segunda skill —una para Teams, por ejemplo— el mismo comando instalará las dos.

Lo que medimos

Contra una máquina recién creada con la imagen nueva, desde un agente de código con el token del agente:

• PATCH identidad + PUT un archivo + PUT una skill + POST restart: 4 llamadas, sin abrir el panel.
• Dentro de la máquina: el CLAUDE.md termina con la sección «Quién eres» y el texto exacto; la skill aparece enlazada junto a las de casa; el archivo está en el workspace.
• Primera respuesta del agente en el chat: «¡Hola! Soy Nora, de Dental Sur 🦷» — la identidad y el saludo que dicta la skill, sin haber tocado un formulario.
• El archivo no necesita reinicio: está en disco al terminar el PUT. La identidad y las skills sí: el cerebro las lee al arrancar la sesión.

Lo que no medimos porque no está: archivos, skills y MCP propios sólo existen en los motores con máquina propia. En los motores que corren en un pool compartido la API acepta identidad y modelo y responde 409 a lo demás, con un mensaje que dice exactamente eso. La skill sabe parar ahí en vez de reintentar.

Qué cambió

Cada ajuste de un agente existe primero como una acción que puede llamar una persona, un agente o un script con el mismo cuerpo JSON. La pantalla del panel llama a esa misma acción. Y hoy quien más la llama es el agente de código que la persona ya tiene abierto.