AGENTS.md y Skills: el sistema real para que tu agente no “invente” ni se pierda

Seguro que os ha pasado: abrís ChatGPT o Claude, le pegáis un trozo de código, le pedís que arregle algo y… desastre. O te alucina, o te rompe otra cosa, o te escribe código que no tiene nada que ver con cómo trabajáis en vuestro equipo.

¿Sabéis por qué pasa esto? Porque estáis haciendo «Coding con IA» en lugar de «Ingeniería de Software con IA». Y hay un mundo de diferencia.

Lo que os voy a explicar hoy, basado en la arquitectura que se ha marcado Gentleman Programming, es la diferencia entre ser un amateur que copia y pega prompts, y tener un sistema robusto, infalible y profesional. Vamos a diseccionar el video paso a paso para que podáis implementarlo ya mismo.

Empezamos por el principio.

Ingeniería de software con IA: el cambio de mentalidad que te salva el proyecto

Seamos sinceros, la mayoría usa la IA como si fuera un becario muy rápido pero un poco «lento» de entendederas. Le damos todo el código de golpe y esperamos que haga magia. Pero la realidad es que, a medida que vuestros proyectos crecen (un monorepo, microservicios, miles de líneas de código), este enfoque tradicional se rompe.

El problema no es la IA, el problema es el contexto y la cultura.

Cuando entra un desarrollador humano nuevo a vuestra empresa, no le soltáis el código fuente el primer día y le decís «toma, arréglame este bug». No. Primero le hacéis un onboarding. Le explicáis:

1. «Aquí usamos estos naming conventions».
2. «La arquitectura es Hexagonal».
3. «No usamos axios, usamos fetch«.
4. «Los tests se hacen con Playwright«.

Eso es la cultura del proyecto. Y eso es exactamente lo que le falta a vuestros Agentes de IA.

La diferencia: Coding vs. Engineering

Para que lo entendáis mejor, he preparado esta tabla comparativa. Si os identificáis con la columna de la izquierda, necesitáis esta arquitectura urgentemente.

La promesa de esta arquitectura

Lo que vamos a ver en esta serie de posts es una arquitectura que yo mismo he probado y es una locura. Se basa en estandarizar cómo la IA interactúa con vuestro código.

No se trata de usar una herramienta mágica de pago. Se trata de usar archivos estándar (Markdown) y una estructura de carpetas lógica para que CUALQUIER IA (Cursor, Copilot, Claude, OpenAI) sepa exactamente qué hacer, cómo hacerlo y dónde hacerlo antes de escribir una sola línea de código.

Si queréis llevar vuestros proyectos al siguiente nivel y dejar de pelearos con el chat, quedaos porque vamos a destripar cómo crear el cerebro de vuestro proyecto.

AGENTS.md explicado: el “manual de trabajo” para que tu IA no improvise

A ver, pensad un momento. Cuando entráis a un repositorio de código nuevo en GitHub, ¿qué es lo primero que miráis? El

README.md

Pues bien, las IAs no son humanos. No necesitan que les expliques con palabras bonitas la filosofía del proyecto. Necesitan instrucciones crudas, directas y técnicas.

Por eso, Gentleman introduce el concepto del AGENTS.md (o a veces lo veréis como

.claude.md

.cursorrules

¿Qué demonios es el AGENTS.md?

Es la Fuente de Verdad para vuestro agente. Es un archivo Markdown que vive en la raíz de vuestro proyecto (y en subcarpetas, ojo al dato) y su única misión es decirle a la IA: «Así es como trabajamos aquí».

No es documentación para ti. Es documentación para que cuando le digas a Claude «Crea un componente», no te lo haga en

classes

hooks

boostrap

Tailwind

Anatomía de un AGENTS.md efectivo

Para que esto funcione, no vale poner cuatro frases. Tiene que tener una estructura clara. Fijaos en este ejemplo práctico de lo que debería contener:

# AGENTS.md - Contexto del Proyecto

## 1. Project Overview
Este es un proyecto Next.js 14 usando App Router. Es una plataforma SaaS de gestión de inventario.

## 2. Tech Stack (Tecnologías Permitidas)
- Framework: Next.js 14 (App Router)
- UI: Tailwind CSS + Shadcn/UI
- State: Zustand
- Data Fetching: TanStack Query
- NO USAR: Redux, Axios, Bootstrap, CSS Modules.

## 3. Code Style (Reglas No Negociables)
- TypeScript Strict Mode siempre activado.
- Usar `const` para definiciones, nunca `let` si no es necesario.
- Naming: camelCase para variables, PascalCase para componentes.
- Estructura de carpetas: Feature-based architecture.

## 4. Setup Commands
Para arrancar el entorno, el agente debe saber qué comandos ejecutar si necesita probar algo:
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`

¿Por qué esto lo cambia todo?

Imaginad que entra un junior a vuestro equipo. Si le dais este archivo, tardará horas en leerlo y asimilarlo. Pero un LLM… un LLM se lo come en milisegundos.

Al tener este archivo:

1. Elimináis la ambigüedad: La IA ya no tiene que «adivinar» si usáis TypeScript o JavaScript. Lo sabe.
2. Reducís el Prompting: Ya no tenéis que escribir en cada mensaje «recuerda usar Tailwind». Está en su ADN (el AGENTS.md).
3. Aceleráis el desarrollo: El agente va directo al grano, sin rodeos ni alucinaciones de librerías raras.

Es, básicamente, inyectarle la cultura de ingeniería de vuestro equipo directamente al cerebro de la IA.

Este archivo es la base, pero tiene un problema gordo si el proyecto crece. ¿Os imagináis un archivo de 5000 líneas con todas las reglas de backend, frontend, devops…? La IA se volvería loca.

¿Queréis saber cómo solucionamos el problema de que la IA «se empanada» cuando le damos demasiada información?

Contexto mínimo viable: cómo evitar alucinaciones cuando tu repo crece

Fijaos en esto. Tenéis un proyecto gigante. Le pasáis a la IA 50 archivos de golpe para que tenga «todo el contexto». Le pedís un cambio sencillo y… PUM. La IA se inventa una función que no existe, importa algo de una ruta imaginaria o se olvida de la regla más básica que le disteis al principio.

¿Os suena? Eso son las alucinaciones por saturación de contexto.

El cerebro de la IA tiene un límite (y no es solo de tokens)

Los LLMs (Modelos de Lenguaje Grande) tienen lo que llamamos una «Ventana de Contexto». Aunque modelos como Claude 3 o GPT-4o tienen ventanas enormes (cientos de miles de tokens), su capacidad de atención no es infinita.

Si le dais toda la codebase:

1. Aumentáis el ruido: La IA tiene que buscar una aguja (vuestra instrucción) en un pajar (todo el código irrelevante).
2. Baja el rendimiento: Cuanto más tiene que leer, más «tonta» se vuelve procesando lógica compleja.
3. Se distrae: Empieza a mezclar patrones del módulo de autenticación cuando le pedisteis algo de CSS.

La regla de oro de Gentleman: No queremos darle todo el contexto. Queremos darle el contexto MÍNIMO VIABLE para ejecutar la tarea con precisión quirúrgica.

El flujo correcto: Usuario → AGENTS.md → código (y por qué funciona siempre)

Aquí es donde Gentleman saca la pizarra (Excalidraw) y nos muestra la diferencia entre trabajar a lo bruto y trabajar con ingeniería.

El Flujo Amateur (El que falla)

graph LR
    A[Usuario] -->|Prompt + 100 Archivos| B(Agente IA)
    B -->|Intenta procesar todo| C{Codebase Completa}
    C -->|Alucinaciones / Error| D[Resultado Basura]

El Flujo de Ingeniería (El que funciona)

graph LR
    A[Usuario] -->|Prompt Específico| B(Agente IA)
    B -->|1. Consulta primero| C[AGENTS.md]
    C -->|Le da el mapa y las reglas| B
    B -->|2. Acceso Quirúrgico| D{Parte Específica del Codebase}
    D -->|Código Perfecto| E[Resultado Épico]

¿Qué está pasando aquí realmente?

Fijaos en el cambio. Antes de que el Agente toque una sola línea de código, hace una parada técnica en el

AGENTS.md

1. Consulta el Mapa: El AGENTS.md le dice: «Si vas a tocar la UI, los componentes están en /src/components, usamos Tailwind y no uses CSS modules».
2. Filtro Inteligente: Con esa info, el agente YA NO NECESITA leer la configuración de la base de datos ni los scripts de despliegue. Los ignora.
3. Ejecución: Va directo al archivo que necesita, aplica las reglas que acaba de leer y ejecuta.

Es como si en vez de leerse la biblioteca entera para buscar un dato, le dierais el índice del libro exacto y la página exacta.

Resultado

El agente trabaja:

• Más rápido: Procesa menos tokens.
• Más barato: Menos tokens de entrada/salida.
• Sin alucinaciones: Al tener las reglas frescas y claras («usa fetch, no axios«), no tiene espacio para inventarse cosas.

Pero claro, aquí nos topamos con un muro. Si mi proyecto es un Monorepo con Backend en Python, Frontend en Next.js y Scripts en Go… ¿Cómo meto todas esas reglas en un solo

AGENTS.md

¿Queréis ver la solución de escalabilidad que propone Gentleman para proyectos grandes?

¡Al lío! Aquí es donde la cosa se pone interesante y profesional de verdad. Si estáis trabajando en un proyecto serio, esto os va a salvar la vida.

Monorepos y proyectos grandes: por qué un solo AGENTS.md se vuelve veneno

Imaginad un Monorepo típico de empresa:

• /apps/web (Next.js)
• /apps/mobile (React Native)
• /packages/ui (Librería de componentes)
• /backend (Python/FastAPI)

Si intentáis meter las reglas de TODO esto en un solo

AGENTS.md

• Si el agente va a tocar el Backend, ¿para qué demonios necesita leer las reglas de Tailwind del Frontend? Es ruido. Ruido puro.
• Si el agente va a tocar la Web, ¿qué le importa cómo se gestionan las migraciones de la base de datos en Python?

Al final, volvéis a saturar la ventana de contexto, el agente se confunde y empieza a aplicar reglas de Python en archivos de TypeScript. Un caos.

AGENTS.md por módulos: la arquitectura modular que escala sin ruido

La arquitectura de Gentleman aplica el principio clásico de la ingeniería: Modularidad.

En lugar de tener un «Mega-Cerebro» centralizado, vamos a tener pequeños cerebros distribuidos por todo el proyecto.

La Jerarquía de Agentes

Vamos a crear una red de archivos

AGENTS.md

1. ROOT/AGENTS.md (El Orquestador General):
   Este es el portero. Contiene solo la información global y el mapa de alto nivel.
   • Contenido: «Este es un monorepo con Web y Backend. Si necesitas trabajar en Web, ve a /apps/web. Si es Backend, ve a /backend.»
2. /apps/web/AGENTS.md (El experto en Frontend):
   Aquí están las reglas específicas de la web.
   • Contenido: «Usamos Next.js, Tailwind, Zustand. No uses img, usa next/image.»
3. /backend/AGENTS.md (El experto en Backend):
   Aquí las reglas de la API.
   • Contenido: «Python 3.11, Pydantic para validación, SQLAlchemy para ORM.»

¿Cómo funciona el flujo ahora?

Cuando le pides al agente: «Crea un endpoint de usuarios en el backend».

1. El agente lee el Root AGENTS.md.
2. Ve que la carpeta de backend es /backend.
3. Salta a esa carpeta y lee el /backend/AGENTS.md.
4. Se carga SOLO el contexto de Python y base de datos.
5. Ignora completamente todo lo que tenga que ver con React o CSS.

Resultado: El agente tiene una claridad mental absoluta. Solo tiene en la cabeza las reglas que aplican a su tarea actual. Cero distracciones.

Plantilla AGENTS.md perfecta: reglas claras, setup y “NO negociables”

Para que veáis esto visualmente, así es como debería quedar vuestro árbol de directorios. Hacedle una captura mental a esto:

mi-proyecto-monorepo/
├── AGENTS.md              # 👈 EL GENERAL: Mapa del sitio y reglas globales
├── package.json
├── apps/
│   ├── web/
│   │   ├── AGENTS.md      # 👈 EL EXPERTO WEB: Reglas de React, CSS, Next
│   │   ├── src/
│   │   └── ...
│   └── mobile/
│       ├── AGENTS.md      # 👈 EL EXPERTO MÓVIL: Reglas de React Native
│       └── ...
└── backend/
    ├── AGENTS.md          # 👈 EL EXPERTO BACKEND: Reglas de Python, API
    ├── src/
    └── ...

El concepto de «Cultura Local»

Esto permite definir «micro-culturas» dentro de vuestro proyecto.

• A lo mejor en el Frontend sois muy estrictos con el linting y los tests de UI.
• Pero en el Backend os importa más la eficiencia de las queries y la seguridad.

Con esta estructura, cada parte del proyecto tiene sus propias leyes, y el agente las respeta escrupulosamente según dónde esté «pisando».

Vale, ya tenemos los archivos distribuidos. Pero… ¿qué ponemos EXACTAMENTE dentro de cada uno para que sea efectivo y no un tocho infumable?

¿Queréis ver la plantilla perfecta para escribir un AGENTS.md que funcione?

¡Genial! Ya tenemos la estructura de carpetas montada. Ahora toca rellenar esos archivos

AGENTS.md

Skills para agentes IA: cómo cargar conocimiento “just-in-time” (estilo Matrix)

Escuchadme bien: Un AGENTS.md no es una carta de amor. No tenéis que ser amables, ni enrollaros, ni explicar la historia de la empresa desde 1990.

A la IA le da igual vuestra misión y visión. Lo que quiere son datos binarios: ceros y unos, síes y noes. Tenéis que ser quirúrgicos. Gentleman nos da las secciones exactas que tiene que tener este archivo para que funcione como un reloj suizo.

Aquí tenéis la plantilla maestra. Copiadla, pegadla y adaptadla.

La Plantilla Perfecta (Copiad esto)

# Contexto de Agente: [Nombre del Módulo/Proyecto]

## 1. Comandos de Setup (Vital)
Si el agente necesita arreglar algo y probarlo, tiene que saber cómo arrancar la máquina. No le hagáis adivinar.
- **Instalar:** `pnpm install`
- **Dev Server:** `pnpm dev` (Corre en puerto 3000)
- **Tests:** `pnpm test:ui` (Solo tests de este módulo)

## 2. Tech Stack (Los Ingredientes)
Aquí es donde evitáis que la IA alucine. Si no le decís qué usar, usará lo que le dé la gana.
- **Framework:** Next.js 14 (App Router)
- **Estilos:** Tailwind CSS (Nada de CSS-in-JS ni Styled Components)
- **Estado:** Zustand
- **Iconos:** Lucide React
- **IMPORTANTE:** No instalar nuevas dependencias sin permiso explícito.

## 3. Reglas de Código (La "Cultura")
Las manías de vuestro equipo convertidas en leyes marciales.
- **TypeScript:** Strict mode ON. No usar `any`.
- **Estilo:** Comillas simples, sin punto y coma al final.
- **Patrón:** Functional components siempre. Nada de clases.
- **Naming:** Los componentes se llaman `PascalCase`, las funciones `camelCase`.

## 4. Reglas Críticas (NO NEGOCIABLES)
Esto es lo que marca la diferencia. Reglas de "Dispara a matar" si no se cumplen.
- **NEVER:** Nunca uses `useEffect` si puedes usar Server Components.
- **ALWAYS:** Usa `clsx` o `cn()` para unir clases de Tailwind.
- **NEVER:** No dejes `console.log` en el código final.

Por qué esta estructura funciona

1. Setup: La IA sabe probar su propio código. Si falla el test, sabe qué comando correr para verificarlo.
2. Tech Stack: ¿Cuántas veces os ha importado axios cuando usáis fetch? Con esta sección, eso se acabó. Le habéis prohibido usar cosas fuera del stack.
3. Reglas Críticas: Los «NEVER» (Nunca) son tan importantes como los «ALWAYS» (Siempre). Son barreras de seguridad para que el código no se degrade.

El tamaño importa

Gentleman insiste en esto: Mantenedlo corto.

Un buen

AGENTS.md

Recordad: Información densa, directa y técnica.

Pero esperad, porque ahora viene el giro de guion. Incluso con estos archivos, a veces necesitamos que el agente sepa hacer cosas muy complejas, como «Crear un componente completo con tests, historia de storybook y documentación».

Si metemos todas las instrucciones de cómo hacer eso en el

AGENTS.md

¿La solución? Las SKILLS. Esto es lo que separa a los niños de los adultos en el mundo de la IA.

¿Queréis saber cómo crear «Habilidades» para vuestra IA y que se convierta en un experto en tareas específicas?

¡Esto sí que es canela en rama! Agarraos, porque aquí es donde pasamos de tener un agente «listillo» a tener un agente Experto.

Diseño de Skills pro: trigger, scope, auto-invoke y control de herramientas

¿Os acordáis de Matrix? ¿Cuando a Neo le enchufan un cable y le cargan el programa de «Kung Fu» en el cerebro justo antes de pelear? Pues las Skills son exactamente eso.

Hasta ahora, con los archivos

AGENTS.md

Si le metéis al

AGENTS.md

La Filosofía «Just-In-Time»

La solución de Gentleman es crear una carpeta llamada

skills/

El truco es este: El agente NO lee todas las skills todo el tiempo. Eso saturaría su cerebro.
En su lugar, el agente solo «aprende» la skill cuando la necesita.

• ¿Vas a tocar un archivo .py? → Carga la Skill de Python.
• ¿Vas a crear un test? → Carga la Skill de Playwright.
• ¿Vas a hacer un Commit? → Carga la Skill de Commits.

El resto del tiempo, esas instrucciones ni existen para él. Es eficiencia pura.

Caso real (Prowler): separar UI y API sin mezclar reglas ni patrones

Vale, Lymcon, ¿pero cómo se ve esto en el código? ¿Es un JSON? ¿Un script?
No, ¡es Markdown otra vez! Pero con esteroides.

Cada Skill vive en su propia carpeta dentro de

skills/

skill.md

Anatomía de una Skill (skills/react-component/skill.md)

Fijaos en este ejemplo. Esto es lo que tenéis que escribir:

---
name: react-component-expert
description: Crea componentes de React siguiendo Atomic Design.
trigger: Cuando el usuario pida crear o refactorizar un componente de UI.
scope: [ui]
auto_invoke: "Creating React Components"
allowed-tools: [read, write, grep]
---

# Guía para Componentes React

Aquí abajo va toda la chicha técnica que antes te ocupaba espacio en el general:

1. **Estructura:**
   - Cada componente debe tener su propia carpeta.
   - `index.ts` solo para exportar.
   - `Component.tsx` para la lógica y vista.

2. **Patrones:**
   - Usar `React.forwardRef` si es un átomo.
   - Usar `cva` (class-variance-authority) para variantes de estilo.

3. **Ejemplo Correcto:**
   ```tsx
   // Copia este patrón, no inventes nada
   export const Button = ...

Los campos mágicos de la Metadata

Analicemos esto porque es clave:

1. trigger (El Gatillo):
   Es una frase en lenguaje natural. El agente lee esto y dice:
   «Ah, el usuario me ha pedido un componente, esto coincide con mi trigger, ¡me cargo esta skill!».
2. scope (El Alcance):
   Esto es un invento de Gentleman (y es brutal). Le dice al sistema en qué parte del proyecto vive esta skill.
   Si pone [ui], esta skill solo se inyectará en el AGENTS.md de la carpeta /ui.
   No ensuciará el backend.
3. auto_invoke:
   Esto es para la tabla de automatización que veremos luego. Obliga al agente a usar la skill sí o sí ante ciertas acciones.
4. allowed-tools:
   Seguridad. ¿Queréis que una skill de documentación pueda borrar archivos? No. Pues aquí se lo prohibís.

El Resultado

Con esto conseguís que vuestro Agente sea Modular.

• ¿Tenéis que actualizar cómo hacéis los tests? Solo tocáis el archivo en skills/testing/skill.md.
• Automáticamente, cualquier agente que necesite hacer tests, leerá la versión actualizada.
• El contexto general se mantiene limpio y ligero.

Esto suena muy bien en teoría, pero seguro que queréis ver cómo se ve esto en un proyecto real, con código de verdad y ver
cómo interactúa el agente. Gentleman nos enseña el repo de Prowler (que es open source) y es una mina de oro.

¿Queréis que analicemos el ejemplo real de Prowler y cómo separa la UI de la API con este sistema?

¡Venga, vamos a ver esto en acción! Nada de teoría barata, vamos a ver código de verdad en un proyecto de verdad.

Orquestación con subagentes: cómo dividir tareas gigantes sin saturar contexto

Gentleman abre su editor (Neovim tuneado a lo Matrix) y nos enseña las tripas de Prowler, su herramienta de
ciberseguridad Cloud. Es un proyecto real, grande y complejo. Perfecto para ver si esto escala o es humo.

La Skill de UI: prowler-ui

Fijaos en lo que tiene montado en

skills/prowler-ui/skill.md

• El Problema: Prowler usa una librería de componentes llamada Shadcn/UI, pero con modificaciones. Si dejas a la IA sola,
  te importará los componentes por defecto y romperá el diseño.
• La Solución: La skill define explícitamente:
  1. Importaciones: «No importes de radix-ui, importa de @/components/ui/...«.
  2. Estilos: «Usa siempre cn() para fusionar clases, no uses strings a pelo».
  3. Componentes:
     «Para botones, usa nuestro componente <Button variant='custom'>, no el
     <button> de HTML».

Gracias a esto, cuando Gentleman le dice al agente «Crea un panel de control», el agente NO se inventa el diseño.
Copia exactamente los patrones definidos en esta skill.

La Skill de API: prowler-api

Por otro lado, tiene la skill del backend. Aquí las reglas son totalmente diferentes:

• Validación: «Usa Pydantic para todo. No valides a mano».
• Base de Datos: «Usa el ORM, nunca escribas SQL crudo».
• Seguridad: «Todos los endpoints deben verificar el token JWT antes de procesar nada».

La Magia del «Scope» en acción

Aquí es donde veis la potencia del campo

scope

• La skill prowler-ui tiene scope: [ui]. Por tanto, solo aparece referenciada en el AGENTS.md de la
  carpeta del frontend.
• La skill prowler-api tiene scope: [api]. Solo aparece en el backend.

Si el agente está trabajando en el frontend, NI SE ENTERA de que existe Pydantic. Su mente está limpia y enfocada en React
y Tailwind.

19:30 Subagentes y orquestación (El Jefe de Obra)

Vale, ya tenemos agentes listos y skills potentes. Pero, ¿qué pasa si la tarea es gigante?
Ejemplo: «Revisa todos los archivos de la carpeta UI y asegúrate de que los botones usan el nuevo componente».

Si un solo agente intenta hacer esto, leerá 500 archivos, se quedará sin memoria y colapsará.

Aquí entra el patrón del Agente Orquestador.

¿Cómo funciona el Orquestador?

Pensad en esto como un Jefe de Obra y sus obreros.

1. El Orquestador (Tú hablas con él): Recibe la orden: «Actualiza los botones».
2. Análisis: El Orquestador mira el mapa y dice: «Uff, son muchos archivos. Voy a necesitar ayuda».
3. Delegación: Crea Sub-Agentes (instancias efímeras de la IA).
   • Sub-Agente 1: «Tú encárgate de la carpeta /auth«.
   • Sub-Agente 2: «Tú de /dashboard«.
   • Sub-Agente 3: «Tú de /settings«.

El secreto: Aislamiento de Contexto

Cada Sub-Agente nace, carga SOLO la skill necesaria (

prowler-ui

Antes de morir, le envía un Resumen al Orquestador:
«He actualizado 5 archivos en /auth. Todo bien.».

El Orquestador NUNCA lee el código de los archivos. Solo lee los resúmenes. Así, su contexto nunca se satura, por muy
grande que sea el proyecto. Puede gestionar 1.000 archivos sin despeinarse porque él no hace el trabajo sucio; lo gestiona.

Ahora diréis: «Lymcon, esto suena a ciencia ficción. ¿De verdad funciona así?».
Pues sí. Y para demostrártelo, Gentleman se marca una demo en vivo usando OpenCode (un fork de VS Code) donde vemos al
agente «pensar» y delegar tareas en tiempo real.

¿Queréis ver cómo el agente cobra vida y empieza a invocar skills automáticamente?

¡Eso es lo que quería oír! Pasemos de la teoría a la práctica pura y dura. Aquí es donde se le ven las costuras al sistema… o donde
demuestra que es una genialidad. Y ya os adelanto: es lo segundo.

Demo en vivo: invocación automática de skills y ejecución quirúrgica

Gentleman utiliza OpenCode (un fork libre de VS Code con IA integrada) para la demo, pero recordad que esto funciona igual
en Cursor o con la CLI de Claude gracias a los scripts que veremos luego.

Lo fascinante aquí no es que la IA escriba código, es CÓMO toma la decisión de hacerlo.

El Flujo de la Demo paso a paso

1. El Interrogatorio: Gentleman empieza preguntando:
   «¿Qué skills tienes disponibles?».
   El agente no alucina. Lee el AGENTS.md (que ya está sincronizado) y le escupe una lista perfecta categorizada:
   «Tengo skills genéricas (React, TypeScript) y específicas de Prowler (UI, API, Compliance)».
2. La Petición (El Prompt):
   «Quiero crear un botón reutilizable dentro de la carpeta UI para cargar un finding».
3. El «Click» Mental del Agente: Aquí pasa la magia. En la consola del agente vemos cómo «piensa»:
   • Detecta que es una tarea de UI.
   • Detecta que es compleja.
   • Acción: * skill [name=prowler-ui].
   • Estado: ~ Delegating... (Creando Sub-Agente).
4. El Sub-Agente Investigador: El sub-agente no se pone a escribir código a lo loco. Primero usa herramientas:
   • Ejecuta glob para buscar dónde están los botones actuales.
   • Ejecuta grep para ver cómo se importan.
   • Lee el archivo button.tsx existente para copiar el estilo.
5. El Resultado: Genera un componente que usa shadcn modificado, con las importaciones correctas y respetando la estructura de carpetas definida en la skill. Cero errores de «no encuentro el módulo».

Diagrama del Flujo de Ejecución

Fijaos en este esquema. Así es como ocurre la magia en tiempo real dentro del cerebro de la IA:

sequenceDiagram
    participant User as Lymcon (Usuario)
    participant Orch as Agente Orquestador
    participant Sub as Sub-Agente (UI Expert)
    participant File as Codebase

    User->>Orch: "Crea un botón de carga en UI"
    Note over Orch: Analiza intención...
    Orch->>Orch: Detecta Trigger: "UI Task"
    Orch->>Sub: Invoca Skill [prowler-ui]
    
    Note over Sub: Carga contexto reducido (React + UI Rules)
    
    Sub->>File: ¿Existen botones parecidos? (ls/grep)
    File-->>Sub: Sí, en /components/ui/button.tsx
    
    Sub->>File: Lee button.tsx para copiar estilo
    File-->>Sub: Contenido del archivo
    
    Sub->>Sub: Genera código nuevo basado en patrón existente
    
    Sub->>Orch: "Aquí tienes el código propuesto"
    Orch->>User: Muestra el código final perfecto

Sync automático: un solo cerebro para Cursor, Claude y Copilot con symlinks

Vale, todo esto es precioso, pero si sois como yo (y sé que lo sois), estaréis pensando: «Lymcon, ni de coña voy a editar 4 archivos AGENTS.md a mano cada vez que cree una skill nueva».

Exacto. Los programadores somos vagos (esa es nuestra virtud). Por eso Gentleman creó el script definitivo: sync.sh.

El Problema de la Fragmentación

• Si usas Claude Desktop, necesitas un archivo .claude.md en la raíz.
• Si usas GitHub Copilot, necesitas .github/copilot-instructions.md.
• Si usas Cursor, necesitas .cursorrules.

¿Vais a mantener 3 archivos iguales manualmente? Ni hablar.

La Solución: Automatización Bash

El script

sync.sh

setup.sh

1. Inyección de Metadata:
   Lee todos los archivos skill.md de vuestra carpeta /skills. Extrae el campo trigger, scope y auto_invoke y reescribe las tablas de los archivos AGENTS.md automáticamente.
   • Resultado: Creas la skill, corres el script, y ¡ZAS! Todos los agentes del proyecto ya saben usarla.
2. Symlinks (Enlaces Simbólicos):
   En lugar de copiar y pegar el contenido para cada IA, crea «accesos directos» (symlinks).
   • Hace que .cursorrules apunte a tu AGENTS.md.
   • Hace que .claude.md apunte a tu AGENTS.md.

Así tienes una Única Fuente de Verdad. Si actualizas una regla en

skills/react/skill.md

Diagrama del Sistema de Sincronización

Aquí veis cómo un simple script Bash se convierte en el pegamento que mantiene todo el sistema unido y actualizado:

graph TD
subgraph SF["Skills Folder (Tu Trabajo)"]
  S1["skill.md (React)"]
  S2["skill.md (Python)"]
  S3["skill.md (Commits)"]
end

Script["Script sync.sh"]

subgraph AC["Archivos de Contexto (Automáticos)"]
  R["Root AGENTS.md"]
  U["UI AGENTS.md"]
  A["API AGENTS.md"]
end

subgraph IA["Compatibilidad IAs (Symlinks)"]
  C1[".cursorrules"]
  C2[".claude.md"]
  C3["copilot-instructions.md"]
end

S1 --> Script
S2 --> Script
S3 --> Script

Script -->|Inyecta Triggers| R
Script -->|Inyecta Triggers| U
Script -->|Inyecta Triggers| A

R -.->|Link| C1
R -.->|Link| C2
R -.->|Link| C3

Checklist final: monta tu sistema AGENTS + Skills y deja de “copiar prompts”

Llegamos al final. Hemos visto cómo pasar de pelear con la IA a tener un ejército de ingenieros virtuales que siguen nuestras órdenes al milímetro.

Resumen de la Arquitectura

1. AGENTS.md: El cerebro central. Corto, directo, cultural.
2. Skills: Módulos de conocimiento bajo demanda. Evitan alucinaciones.
3. Orquestación: Dividir tareas grandes en sub-agentes con contextos aislados.
4. Automatización: Scripts (sync.sh) para que la infraestructura se mantenga sola.

No os quedéis solo con la teoría. El repositorio de Prowler que usa Gentleman es público. Bajadlo, destripadlo y copiad la carpeta

skills

Esto no es el futuro, gente. Esto es cómo se trabaja HOY si queréis ser competitivos. Dejad de pedirle a la IA que os «escriba código» y empezad a diseñarle el sistema para que haga ingeniería.

Diagrama Final: El Ecosistema Completo

Este es el mapa del tesoro. Si implementáis esto, vuestra productividad se va a ir a la luna 🚀.

mindmap
  root((Ingeniería de Software con IA))
    Estandarización
      AGENTS.md (Root)
      AGENTS.md (Features)
      Reglas NO Negociables
    Skills (Habilidades)
      Just-in-Time Context
      Skills Técnicas (React, Python)
      Skills de Proceso (PR, Docs)
    Automatización
      sync.sh (Metadata)
      setup.sh (Symlinks)
      Compatibilidad Multi-IA
    Ejecución
      Agente Orquestador
      Sub-Agentes Efímeros
      Uso de Herramientas (Grep, LS)

¿Tenéis dudas sobre alguna parte? ¿Queréis que profundice en algún script? Os leo en los comentarios.