Delphi AI Skills: código Delphi correcto con agentes IA

Escribir código se ha vuelto barato. Lo que cuesta, ahora, es conseguir que se escriba bien: delphi-ai-skills enseña a los agentes IA (Claude Code, Codex, Cursor, Gemini) la API real de DelphiMVCFramework, con directrices, estilo, seguridad y tests incorporados.

Desde hoy es público delphi-ai-skills: un conjunto de skills open source (Apache-2.0) que enseñan a los agentes IA de programación a escribir código DelphiMVCFramework que compila, que sigue las convenciones correctas y que nace ya seguro. Funciona con Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue y con cualquier otra herramienta capaz de leer instrucciones en Markdown.

En resumen

• Qué es: siete skills open source (Apache-2.0) que enseñan a un agente IA la API real de DelphiMVCFramework 3.5.0, en lugar de dejar que la adivine.
• Para quién: para quien escribe REST API, Minimal API o aplicaciones web en Delphi con la ayuda de un agente IA.
• Agentes soportados: Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue, y cualquier agente que lea Markdown.
• Instalación: git clone, y después install_in_claude.bat (o _codex, _cursor, _gemini).
• Qué cambia: se acabó el MapGroup en lugar de Prefix, el ToFree que libera dos veces el objeto devuelto, y llegan endpoints filtrados por el usuario autenticado y tests de integración DUnitX de verdad.
• Repositorio: github.com/danieleteti/delphi-ai-skills

El código se ha vuelto barato. La dirección no.

Durante treinta años la parte cara del oficio ha sido teclear. El diseño lo tenías en la cabeza, y el cuello de botella era convertirlo en líneas: escribir el controlador, el DTO, los tests, el boilerplate, el CRUD. Quien producía más líneas correctas por hora valía más.

Esa escasez se ha terminado. Hoy un agente IA me escribe en treinta segundos un controlador CRUD con tests incluidos. Ya no es una novedad de conferencia: es el día normal de quien programa en 2026. Y cuando algo se vuelve abundante, el valor se desplaza a otro sitio.

Se desplaza a la dirección. Si el código cuesta poco de producir, la pregunta interesante ya no es “cuánto tardas en escribirlo”, sino:

• ¿sigue nuestras convenciones, o se inventa unas nuevas en cada sesión?
• ¿usa la API que el framework tiene de verdad, o la que el agente imagina que el framework tiene?
• ¿el endpoint que acaba de generar está filtrado por el usuario autenticado, o lee el pedido de cualquiera que pase un ID en la URL?
• el código que acabo de aceptar con un golpe de Tab, ¿quién lo mantiene dentro de dos años?

El riesgo del código barato es exactamente ese: producir deprisa mucho código mediocre, plausible al leerlo y equivocado en los detalles, cada trozo con su pequeño estilo personal. Un agente dejado suelto es rapidísimo construyendo deuda técnica.

La respuesta no es frenar al agente. Es guiarlo: darle directrices, modos operativos, un estilo de la casa y reglas de seguridad incorporadas, de modo que el camino correcto sea también el camino por defecto. Es exactamente el trabajo que hacen las skills.

Qué es una skill para un agente IA

Una skill es un archivo Markdown que el agente carga bajo demanda, solo cuando tu petición coincide con su descripción. En el contexto del agente están siempre, y nada más, el nombre y una línea de descripción por cada skill instalada. Cuando pides “crea un controlador DMVCFramework”, el agente reconoce la coincidencia y entonces abre el archivo, que le explica la API real del framework: los nombres exactos de las units, los atributos, las reglas de ownership de los objetos, los idiomas propios del framework, las trampas ya conocidas.

Carga bajo demanda: la documentación pesada entra en juego solo cuando la tarea la requiere.

Es un mecanismo sencillo pero con una propiedad valiosa: la ventana de contexto se mantiene libre. La skill principal, dmvcframework, guarda en su SKILL.md el núcleo operativo (bootstrap, controladores, respuestas, ownership, middleware, errores típicos) y traslada el material pesado a archivos reference/ que el agente abre solo si la tarea lo exige: el ORM ActiveRecord, la validación, el contenedor de inyección de dependencias, los backend de servidor, dotEnv, los SSE.

El problema concreto: código Delphi plausible que no compila

Pedidle a un agente sin skills una Minimal API con DelphiMVCFramework. Recibiréis código bien escrito, bien indentado, bien comentado, y que no compila.

La misma petición, el mismo modelo. A la izquierda los nombres que el framework tendría si fuese ASP.NET, a la derecha los que tiene de verdad.

Los nombres equivocados no son casuales: son los que el framework tendría si fuese ASP.NET Core, porque de ASP.NET Core el modelo ha leído millones de líneas y de DelphiMVCFramework muchas menos. Así aparece MapGroup en lugar de Prefix, OkResponse en lugar de Ok, clases middleware que no existen, y un ToFree alrededor del objeto devuelto que lo libera dos veces, porque de liberarlo ya se encarga el framework.

Hay una pregunta que desenmascara a un agente no instruido en diez segundos:

En una functional action de DelphiMVCFramework, ¿debo usar ToFree sobre el objeto que devuelvo?

La respuesta correcta es no: el framework libera el objeto devuelto, y ToFree lo liberaría una segunda vez. Un agente sin skills suele responder que sí, y su código hace una doble liberación.

Cada skill del proyecto ha nacido precisamente reproduciendo antes el error: se hace fallar al agente, se documenta la API que el framework tiene de verdad, se relanza la misma tarea y se comprueba que ahora la acierta. Ningún nombre de API escrito de memoria: todo verificado en los fuentes y en los samples de DelphiMVCFramework 3.5.0 (silicon).

Las siete skills para DelphiMVCFramework

Son complementarias: las skills de Minimal API y de aplicaciones web dan por supuesto el núcleo para entidades, validación e inyección de dependencias, y la skill de aplicaciones web delega el markup en dmvcframework-ui y la sintaxis htmx en htmx-skill en lugar de duplicarlas. Instaladlas todas: es el agente quien elige las adecuadas.

Si no conocéis los temas que las skills enseñan al agente, aquí tenéis el punto de partida humano: las Minimal API de DMVCFramework, las aplicaciones web Delphi con TemplatePro y, en el terreno de la IA, el servidor MCP para DMVCFramework con su agente. Las skills son la pieza que faltaba: no le dan al agente nuevas herramientas, le dan el saber para usar bien las que ya tiene.

Seguridad: no un control final, sino una precondición del código generado

Esta es la parte que más me importa, y el motivo por el que dmvcframework-security no es una skill que se invoca al terminar el trabajo, sino una dependencia obligatoria de las demás skills de servidor: cualquier endpoint que reciba entrada de un cliente la arrastra consigo.

El código generado deprisa se equivoca siempre en los mismos puntos. El más común, y el más grave, es el IDOR: el endpoint que se fía del ID de la URL.

// MAL: cualquier usuario autenticado puede leer los pedidos de cualquiera
function TOrdersController.GetOrder(const ID: Integer): IMVCResponse;
begin
  Result := OKResponse(TMVCActiveRecord.GetByPK<TOrder>(ID));
end;

El ID llega de la URL. Nada lo vincula con quien está llamando. La regla que la skill impone al agente es que el control de propiedad sea la propia consulta, no un if puesto después:

function TOrdersController.GetOrder(const ID: Integer): IMVCResponse;
var
  lOrder: TOrder;
begin
  // el control de propiedad ES la consulta
  lOrder := TMVCActiveRecord.GetOneByWhere<TOrder>(
    'id = ? and customer_id = ?', [ID, CurrentUserID], False);
  if lOrder = nil then
    Exit(NotFoundResponse);      // misma respuesta que "no es tuyo": no revelar la existencia
  Result := OKResponse(lOrder);
end;

La diferencia entre las dos versiones son tres líneas. Pero la primera es una filtración de datos que solo está esperando a ocurrir, y en un mundo en el que el código se acepta a golpes de Tab, es la versión que acaba en producción. Una regla escrita en una skill vale mucho más que una regla escrita en una checklist que nadie relee: la skill se aplica mientras el código nace, no después.

Lo mismo vale para el estilo y para las directrices de proyecto. Las skills no enseñan solo “cómo se llama esta función”: enseñan cómo se trabaja aquí. Por ejemplo, imponen partir de un proyecto creado con el wizard del IDE, en lugar de inventarse un bootstrap a medias desde cero, y respetar el backend de servidor que el proyecto ya tiene: si estáis corriendo en WebBroker bajo ISAPI o Apache, las skills lo reconocen, lo mantienen y nunca os proponen migrar.

Los tests: el contrapeso al código barato (DUnitX e IMVCRESTClient)

Si hay algo que la era del código abundante hace más importante, no menos, son los tests.

El razonamiento es sencillo. Antes, el código lo escribías tú: lo tenías en la cabeza línea a línea, y podías permitirte (sin razón, pero podías) fiarte de esa comprensión. Hoy el código llega de un agente, en cantidad, y tú lo lees en diagonal. Lo único que te dice si ese código hace de verdad lo que crees ya no es tu lectura: es un test que falla. El test se ha convertido en el lugar donde vive tu intención, y el código es solo la manera, ya barata, de satisfacerla.

Y hay un segundo motivo, aún más práctico: el test es el único lenguaje en el que el agente puede verificarse a sí mismo. Un agente que tiene una suite que lanzar cierra el ciclo (escribo, compilo, ejecuto los tests, corrijo) sin que tú tengas que hacer de compilador humano en cada vuelta. Sin tests, el agente tiene una única fuente de verdad: tú.

Por eso dmvcframework-testing no es una skill accesoria. Enseña al agente el stack de tests real de DelphiMVCFramework: DUnitX como runner, un IMVCServer in-process (Indy Direct) e IMVCRESTClient como cliente HTTP fluido. Ningún servidor externo que arrancar, ningún WebModule: el servidor nace y muere dentro del test.

function StartTestServer(APort: Integer; out AEngine: TMVCEngine): IMVCServer;
begin
  AEngine := TMVCEngine.Create(
    procedure(Config: TMVCConfig)
    begin
      Config[TMVCConfigKey.DefaultContentType] := TMVCMediaType.APPLICATION_JSON;
    end);
  AEngine.AddController(TCustomersController);

  Result := TMVCServerFactory.CreateIndyDirect(AEngine);
  Result.Listen(APort);
end;

Fijaos en un detalle que ya justifica por sí solo instalar la skill: esto funciona también si la aplicación en producción corre como ISAPI bajo IIS o como módulo Apache. El host no es lo que estáis probando, lo son el engine, los controladores y los middleware. Un agente no instruido, a quien le pide tests para un proyecto WebBroker, le responde intentando arrancar IIS.

Los tests de integración son HTTP de verdad contra el servidor in-process, y la skill obliga a aseverar sobre el status code y el body, no sobre el hecho de que la llamada no haya explotado:

procedure TCustomersTests.Create_Returns201_And_Location;
var
  lResp: IMVCRESTResponse;
begin
  lResp := FClient.Post('/api/customers',
    '{"firstName":"Daniele","lastName":"Teti","email":"d.teti@example.com"}');

  Assert.AreEqual(HTTP_STATUS.Created, lResp.StatusCode);
  Assert.IsNotEmpty(lResp.HeaderValue('Location'));
end;

procedure TCustomersTests.Post_Invalid_Email_Returns422;
var
  lResp: IMVCRESTResponse;
begin
  lResp := FClient.Post('/api/customers',
    '{"firstName":"Bob","lastName":"X","email":"not-an-email"}');
  // la validación falla => 422, y la action nunca se ejecutó
  Assert.AreEqual(HTTP_STATUS.UnprocessableEntity, lResp.StatusCode);
end;

Pero la parte que de verdad me interesa es otra, y es el punto en el que la skill de los tests y la de la seguridad se dan la mano. Probad la cerradura, no solo la llave. Para cada recurso protegido, el test que cuenta no es el que verifica que el propietario recibe un 200: es el que verifica que cualquier otro no llega hasta él.

procedure TSecureTests.NoToken_Returns401;
begin
  // el test que caza el [MVCRequiresAuthentication] que olvidaste
  Assert.AreEqual(HTTP_STATUS.Unauthorized, FClient.Get('/api/admin/stats').StatusCode);
end;

procedure TOrdersTests.User_Cannot_Read_Another_Users_Order;
begin
  // el pedido 1 pertenece a user1
  FClient.SetBearerAuthorization(TokenFor('user2'));
  // 404, no 403: un 403 confirmaría que el pedido existe
  Assert.AreEqual(HTTP_STATUS.NotFound, FClient.Get('/api/orders/1').StatusCode);
end;

Este es el test IDOR, es decir exactamente el agujero del párrafo anterior, capturado en tres líneas. Es también el test que casi nadie escribe, porque un 200 para el propietario da la sensación tranquilizadora de que el endpoint “funciona”. La regla que la skill impone al agente es tajante: para cada verbo de cada recurso que tiene un propietario, hace falta el test que demuestre que otro usuario es rechazado. Un GET bien filtrado y un DELETE dejado abierto siguen siendo una filtración de datos.

El sentido está todo ahí: al pedir “escribe los tests de integración para los endpoints Customers, incluidos los casos de autorización”, el agente no produce solo unos tests, produce los tests que vosotros no habríais tenido ganas de escribir. Y es el tipo de trabajo en el que el código barato es una bendición de verdad, en vez de una forma elegante de acumular deuda. La skill trae consigo también scripts/run-tests.bat, para que el agente compile y ejecute la suite por su cuenta, y vea el rojo antes de deciros que ha terminado.

Cómo instalar las skills Delphi en Claude Code, Codex, Cursor y Gemini

Clonad el repositorio y lanzad el script de vuestro agente (Windows):

git clone https://github.com/danieleteti/delphi-ai-skills.git
cd delphi-ai-skills
install_in_claude.bat

Para Claude Code no hace falta nada más: las skills se descubren solas. Para Codex, Cursor y Gemini CLI están install_in_codex.bat, install_in_cursor.bat e install_in_gemini.bat, que copian las skills y escriben el puntero en el archivo de instrucciones del agente (AGENTS.md, .cursor/rules/*.mdc, GEMINI.md), porque esos agentes no las descubren por sí mismos.

Cada script acepta una ruta de proyecto, si preferís instalar las skills dentro del repositorio y versionarlas para todo el equipo:

install_in_claude.bat C:\DEV\mi-proyecto

Después se crea el proyecto con el wizard del IDE (File → New → Other → Delphi Projects → DelphiMVCFramework), se compila una vez, se lanza el agente dentro de esa carpeta y se le pide lo que haga falta:

Añade un controlador Customers con CRUD completo, apoyado en una entidad ActiveRecord sobre la tabla customers

Un último consejo que marca una diferencia notable: si tenéis los fuentes de DelphiMVCFramework en disco, decídselo al agente (“los fuentes de DMVCFramework están en C:\DEV\dmvcframework”). Las skills saben que pueden estar incompletas o desfasadas, y en ese caso están instruidas para verificar en vez de adivinar: leen los fuentes y los samples, y si aun así no están seguras lo dicen, en lugar de inventar.

Una sesión de verdad, de principio a fin

Se acabó la teoría. Así es una sesión real dentro de un proyecto generado por el wizard, con Claude Code. Nunca “llamáis” a una skill: describís la tarea, y la skill se carga sola.

$ cd C:\DEV\OrdersAPI
$ claude

> añade un controlador Customers con CRUD completo, apoyado en
  una entidad ActiveRecord sobre la tabla customers

● Skill(dmvcframework)
  ⎿  SKILL.md cargada
  ⎿  reference/activerecord.md abierta (entidad + mapping)
● Skill(dmvcframework-security)
  ⎿  SKILL.md cargada (el endpoint acepta entrada del cliente)

● Read(EngineConfigU.pas)    proyecto wizard detectado, backend Indy Direct
● Read(Controllers.Base.pas) estilo de la casa: functional action, IMVCResponse

● Write(Entities.Customer.pas)
● Write(Controllers.Customers.pas)
● Edit(EngineConfigU.pas)     +1 línea: AddController(TCustomersController)

  Hecho. Notas:
  - GET /api/customers/($id) está filtrado por el cliente autenticado, no
    solo por el ID: un usuario no puede leer la fila de otro.
  - El objeto devuelto por OKResponse lo libera el framework:
    nada de ToFree, sería una doble liberación.
  - El campo "id" está excluido de la deserialización (mass assignment).

Las tres notas finales no son cortesía: son las reglas de las skills que han trabajado mientras el código nacía. Un agente sin skills, con el mismo prompt, os habría entregado un GetByPK(ID) sin filtrar, un ToFree de más y un DTO que deja que el cliente le escriba el id.

Se continúa en la misma conversación, y la skill de los tests entra en escena sola:

> ahora escribe los tests de integración, incluidos los casos de autorización

● Skill(dmvcframework-testing)
  ⎿  SKILL.md cargada

● Write(Tests.Server.pas)      IMVCServer in-process, sin WebModule
● Write(Tests.Customers.pas)   9 tests: CRUD, 404, 422, 401, IDOR
● Bash(scripts\run-tests.bat)
  ⎿  Running... 9 tests, 8 passed, 1 FAILED
     [FAIL] User_Cannot_Read_Another_Users_Order
            expected 404, got 200

  El test IDOR falla: OrdersController.GetOrder todavía busca solo
  por PK. Lo corrijo (estaba fuera del perímetro que me habías dado,
  ¿lo confirmas?)

Este es el punto en el que el círculo se cierra: un test escrito por el agente ha encontrado un agujero en código que el agente no había escrito. Con la mera generación de código ese bug se quedaba ahí. Es el motivo por el que, en un mundo de código barato, las directrices y los tests valen más que la velocidad.

El mismo trabajo con Codex, Cursor, Gemini o cualquier otro agente

Las skills son Markdown puro, sin sintaxis propietaria: el contenido es idéntico en todos los agentes, solo cambia la manera en que el agente descubre que esos archivos existen.

Con Codex la misma sesión de antes tiene la forma siguiente: la petición es idéntica, y solo cambia el rastro con el que el agente declara haber leído la skill.

$ codex
> añade un controlador Customers con CRUD completo (DMVCFramework)

  Leo skills/dmvcframework/SKILL.md, como pide AGENTS.md.
  Este endpoint recibe entrada del cliente: leo también
  skills/dmvcframework-security/SKILL.md.
  ...

Ojo a un detalle: en los agentes distintos de Claude Code la carga no está garantizada, depende de cuánto respete ese agente su propio archivo de instrucciones. Por eso, con Codex, Cursor o Gemini, conviene nombrar el framework en el prompt (“crea un controlador DMVCFramework”, no “crea un controlador”): es el disparador más fuerte. Y si sospecháis que la skill no se ha cargado, decidlo explícitamente:

Usa la skill dmvcframework. Después crea el controlador para Orders.

También hay una forma, de diez segundos, de saber si el agente que tenéis delante está instruido o no. Preguntadle:

En una functional action de DelphiMVCFramework, ¿debo usar ToFree sobre el objeto que devuelvo?

Si responde no, porque el framework ya libera el objeto devuelto y ToFree lo liberaría dos veces, la skill está activa. Si responde que sí, su código está haciendo una doble liberación y vosotros lo descubriréis en producción.

Preguntas frecuentes sobre delphi-ai-skills

¿Qué es delphi-ai-skills? Es un proyecto open source (Apache-2.0) que reúne siete skills para agentes IA de programación, dedicadas a DelphiMVCFramework. Una skill es un archivo Markdown que el agente carga bajo demanda y que le enseña la API real del framework: units, atributos, reglas de ownership de los objetos, idiomas propios del framework y trampas conocidas.

¿Con qué agentes IA funcionan? Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Continue y cualquier agente capaz de leer instrucciones en Markdown. El repositorio incluye los scripts de instalación para los cuatro primeros.

¿Por qué un agente IA sin skills escribe código Delphi que no compila? Porque escribe de memoria, y recae en los patrones de los frameworks que ha visto mucho más, típicamente ASP.NET Core. Así genera nombres plausibles pero inexistentes, por ejemplo MapGroup en lugar de Prefix u OkResponse en lugar de Ok, y un ToFree sobre el objeto devuelto que provoca una doble liberación, dado que de liberarlo ya se encarga el framework.

¿Las skills se ocupan también de la seguridad? Sí, y es la parte más importante. dmvcframework-security es una dependencia obligatoria de todas las skills de servidor: se aplica a cualquier endpoint que reciba entrada de un cliente. Cubre control de acceso e IDOR, mass assignment, inyección SQL, XSS en TemplatePro, CSRF, path traversal, subida de archivos, SSRF y open redirect, cabeceras de seguridad, hardening del JWT y gestión de los secretos.

¿Las skills saben escribir los tests? Sí, con el stack de tests real del framework: DUnitX como runner, un IMVCServer in-process con Indy Direct e IMVCRESTClient como cliente HTTP, sin servidores externos y sin WebModule, incluso cuando en producción la aplicación corre como ISAPI o como módulo Apache. Cubren los tests CRUD, los de autenticación y los tests de autorización (IDOR).

¿Las skills crean el proyecto Delphi desde cero? No, y es una decisión deliberada. El proyecto hay que crearlo con el wizard del IDE, compilarlo una vez, y solo entonces se lanza el agente dentro de esa carpeta. Las skills reconocen el layout del wizard y añaden funcionalidad dentro de él, en lugar de inventarse un bootstrap a medias.

¿Funcionan sobre un proyecto WebBroker o ISAPI existente? Sí. El backend por defecto para un proyecto nuevo es Indy Direct, pero un proyecto WebBroker existente (ISAPI bajo IIS, módulo Apache) está plenamente soportado: las skills reconocen el host, lo mantienen y nunca proponen una migración. Todo lo que está por encima del host, es decir controladores, routing, ActiveRecord, validación, inyección de dependencias y middleware, es idéntico en cualquier backend.

Versión 0.1.0 de las Delphi AI Skills, y el camino por delante

Es una primera release. Las skills están escritas y verificadas sobre DelphiMVCFramework 3.5.0, pero todavía no han atravesado decenas de proyectos reales: esperad alguna aspereza, y por favor comunicadla. Mientras estemos en 0.x, la forma misma del conjunto hay que considerarla inestable: las skills podrán dividirse, unirse, renombrarse o eliminarse a medida que el uso real muestre qué hace falta de verdad.

El criterio para contribuir es uno solo, y no es negociable: cada afirmación debe ser verificable en los fuentes o en un sample de DelphiMVCFramework, citando el archivo. Ningún nombre de API escrito de memoria, nunca. Es exactamente la disciplina que pedimos a los agentes, y sería curioso no aplicárnosla a nosotros.

El proyecto está aquí: github.com/danieleteti/delphi-ai-skills. Las issues y las pull request son bienvenidas.

Escribir código, a estas alturas, es la parte fácil. Decidir qué código se quiere, y conseguir que sea ese el que sale incluso cuando lo escribe una máquina, es el oficio que queda. Las Delphi AI Skills sirven para eso: dar a un agente IA las directrices, el estilo, la seguridad y los tests con los que queremos que nazca el código Delphi.