Hizo una demo de su propia AI Agent Skill en una reunión con el cliente, y los números no cuadraban

En la sala de reuniones, Lin Zhean (un personaje ilustrativo — un administrador de sistemas internos de una firma contable pequeña, no un cliente real) abrió su pantalla compartida, listo para hacer la demo de la ‘skill de consolidación de reportes mensuales de sucursales’ que había pasado toda la noche del sábado construyendo. Su gerente estaba sentado a su lado, y el cliente ya estaba en la llamada esperando ver el resultado. Presionó ejecutar. El AI Agent reunió rápidamente los números de cada sucursal en un solo reporte, excepto que el total general en la última columna no coincidía con los subtotales de al lado.

La sala quedó en silencio durante tres segundos. Su gerente habló primero: ‘¿De dónde salió este número?’ Lin Zhean no supo responder, porque él mismo no tenía idea de cómo la IA había sumado esas cifras. Solo sabía que le había pedido a la IA que le escribiera esta ‘skill’ el sábado por la noche anterior; una vez terminada parecía razonable, así que simplemente empezó a usarla.

Esa noche, desarmó todo el proceso y se dio cuenta de que había caído directamente en varios de los errores más comunes con las ‘AI Agent Skills’ — el tipo de errores que son invisibles hasta que realmente los pones en uso.

Su Skill Que la IA Nunca Llegó a Abrir

Lin Zhean abrió el archivo skill.md que había escrito y lo revisó de nuevo, y descubrió que el campo ‘description’ al principio del YAML era vago — algo como ‘genera consolidaciones de reportes mensuales’. El problema es que un AI Agent no carga el contenido completo de cada skill al iniciarse; primero solo mira el nombre y la descripción de cada skill, y usa esas pocas palabras para juzgar si este es el momento adecuado para usarla. Con una descripción vaga, es probable que el Agente concluya ‘tal vez sirva, tal vez no’ y simplemente la omita, calculando todo sobre la marcha — lo cual resultó ser la primera capa de por qué falló su demo: es posible que la skill nunca se haya activado, y que la IA simplemente haya calculado ese reporte por su cuenta, a su manera.

Reescribió la descripción de forma mucho más explícita: dejando claro qué hace la skill y exactamente cuándo debe usarse — por ejemplo, ‘Consolida los detalles de ingresos mensuales de cada sucursal en un reporte mensual; úsala cuando el usuario pida un reporte mensual, un cierre de mes o un resumen de cifras de sucursales’. También había escuchado que los modelos tienden naturalmente más a subutilizar una skill que a sobreutilizarla, así que la descripción debería inclinarse hacia ser directa — incluso un poco de ‘autopromoción’ descarada — en lugar de quedarse demasiado conservadora o discreta.

La Skill Que ‘la IA Escribió por Él’ en Realidad No le Enseñó Nada

Una vez resuelto el problema de activación, Lin Zhean abrió el cuerpo de la skill y lo leyó de nuevo, y encontró que la mayor parte del contenido era relleno genérico que sirve para cualquier cosa, como ‘por favor verifica que los datos de entrada sean correctos’ y ‘maneja adecuadamente los casos de error’ — cosas que la IA ya sabe, así que escribirlas en una skill equivale a no escribir nada. Lo que realmente pertenece a una skill es la parte que la IA nunca podría descubrir por sí misma: tu forma específica de hacer este trabajo en particular — qué paso suele fallar, qué le rechazó su gerente la última vez, qué reglas de excepción raras se esconden en los reportes antiguos.

Así que desenterró los reportes antiguos que su gerente había devuelto tres veces el mes anterior, junto con los comentarios de revisión de ese entonces, y fue anotando uno por uno exactamente qué había salido mal cada vez y cómo se había corregido finalmente. Estas ‘lecciones ya aprendidas a la fuerza’ resultaron ser la parte verdaderamente valiosa de la skill — porque es el detalle que la IA no tiene forma de buscar por sí misma; solo alguien que realmente ha hecho este trabajo lo sabe.

Mientras Más Parches le Agregaba, Más Empezaba la IA a ‘Perderse’

Después de ir agregando una lección tras otra, el archivo de la skill se fue haciendo cada vez más largo, hasta que eventualmente la ejecución del Agente se hizo más lenta e incluso empezó a pasar por alto puntos que se le habían indicado antes. Fue entonces cuando Lin Zhean entendió: una vez que se selecciona una skill, todo su contenido se carga en el contexto de la conversación actual, compitiendo con todo lo demás que se está procesando por la misma porción de presupuesto de atención. Mientras más larga sea, más ‘espacio de pensamiento’ disponible de la IA queda desplazado por su propio manual de instrucciones, justo en el momento en que se supone que debe hacer el trabajo real.

La solución no es recortar el contenido hasta dejarlo vacío, sino organizarlo por capas: mantener el cuerpo de la skill limitado solo a lo que la IA realmente necesita en el momento — aproximadamente 500 líneas, que se traducen en algo así como 5,000 tokens (esta es una regla práctica del presentador del video original, no un estándar oficial de conversión de este sitio ni de ninguna plataforma; el número real de tokens varía según el modelo y el tokenizador). Los detalles más finos que no se necesitan cada vez — como una regla de excepción específica de una sucursal en particular — van en una subcarpeta aparte, que la IA solo lee cuando realmente se encuentra con esa situación, en lugar de consumir gratuitamente el presupuesto de ejecución diaria. Esta fue la primera vez que Lin Zhean se dio cuenta de que escribir una skill es en realidad su propio tipo de planificación cuidadosa del presupuesto de tokens — más detalle no significa automáticamente más seguridad.

Ese Total Que No Cuadraba No Era Casualidad

Volviendo al problema del total que falló frente al cliente. Al revisarlo, Lin Zhean descubrió que, para el paso de la suma, originalmente había dejado que la IA leyera los números y los sumara mentalmente por sí misma — pero un modelo de lenguaje, en esencia, está ‘prediciendo’ el siguiente resultado más probable, no realizando realmente una operación aritmética exacta. Mientras más campos hay y más desordenados están los números, más fácil es que la IA se equivoque en la suma — y que suene completamente segura mientras lo hace.

Cambió ese paso de ‘sumar’ de ‘dejar que la IA lo calcule ella misma’ a un pequeño bloque fijo de lógica de cálculo que la skill invoca directamente para hacer la suma; la IA ya no calcula mentalmente, y solo es responsable de organizar los datos y colocar el resultado calculado en el reporte. Ese tipo de error de total que no cuadra, el que explotó frente a un cliente, se convirtió desde entonces en una categoría de error que simplemente no puede volver a ocurrir — porque lo correcto ya no depende de que la IA lo ‘adivine’ en el momento, sino de una lógica que produce el mismo resultado cada vez que se ejecuta. También descubrió que este principio no se limita a la aritmética: cualquier paso que deba ser preciso y consistente cada vez debería delegarse a una lógica fija, y la IA solo debería encargarse de decidir cuándo invocarla.

Casi Instala un Archivo de Skill Que ‘Alguien Más Ya Había Escrito’

Después de arreglar la skill y lograr que el reporte mensual produjera los números correctos, Lin Zhean vio en un grupo de Line del sector que alguien había compartido un archivo comprimido con una ‘skill de conciliación de facturas’ ya lista, con la nota: ‘Solo suéltala y úsala, es súper conveniente’. Por un momento pensó en instalarla directamente — después de todo, no es más que algunas instrucciones de texto y un par de scripts, ¿qué tan grave podría ser?

Pero entonces recordó la skill que él mismo acababa de arreglar: podía ejecutar código, leer y escribir archivos locales, e incluso llegar a tocar claves de API ya configuradas en el sistema — en otras palabras, instalar la skill de un desconocido equivale, en cierto sentido, a ejecutar directamente en tu propio entorno un programa escrito por alguien que no conoces. Más tarde se enteró de que el mismo video que explicaba estas mejores prácticas también mencionaba una auditoría de aproximadamente cuatro mil skills disponibles públicamente, en la que alrededor del 35% presentaba algún tipo de falla de seguridad, y cerca del 13% contenía algo más grave — como código malicioso o técnicas diseñadas para inducir a la IA a realizar acciones no deseadas (esta cifra es el relato del presentador del video sobre cierta auditoría; el video no identifica más a fondo la fuente, se trata de un relato de segunda mano no verificado de forma independiente por este sitio ni por AITK, y se ofrece únicamente como referencia de conciencia de riesgo, sin representar la proporción real de ningún repositorio de skills público en específico).

No instaló el archivo comprimido directamente. En cambio, dedicó diez minutos a abrir las instrucciones y los scripts que contenía y leerlos primero, para confirmar exactamente qué archivos tocaría y si enviaría algo hacia afuera — de la misma forma en que evaluarías si añadir un nuevo paquete a un proyecto. A partir de entonces, ‘leer antes de usar’ se convirtió en su acción predeterminada frente a cualquier skill que no hubiera escrito él mismo.

La Semana Siguiente, en la Misma Sala de Reuniones, Vuelve a Presionar Ejecutar

En la demo del reporte mensual de la semana siguiente, Lin Zhean volvió a presionar ejecutar, en la misma sala de reuniones, frente al mismo gerente y el mismo cliente. Esta vez, el total cuadró desde el primer intento, sin esperas ni interrupciones extra en pantalla. Nadie lo elogió especialmente — un reporte correcto no debería merecer elogios; se supone que simplemente debe ser correcto.

Pero después de que terminó la reunión, Lin Zhean hizo una cosa más por su cuenta: convirtió todos los tropiezos de esas últimas semanas en una ‘lista de verificación previa al lanzamiento de skills’ compartida para su equipo, para que a partir de ahora cualquiera que quiera conectar una nueva skill a un flujo de trabajo en producción tenga que pasar primero por esa lista, en lugar de hacer lo que él hizo la primera vez: escribirla, que pareciera razonable, y llevarla directo a una demo frente a un cliente.

FAQ

P1: ¿Cuál es la diferencia entre una AI Agent Skill y un prompt normal?

Un prompt suele ser una instrucción puntual dada en el momento, dentro de una sola conversación. Una skill, en cambio, es un ‘manual de operación’ persistente y basado en archivos que le enseña a la IA la forma específica en que quieres que se haga cierto trabajo, de una vez por todas — no necesitas volver a explicarlo cada vez, y la IA decide por sí misma, cuando lo necesita, si debe recurrir a ella.

P2: ¿Una skill es mejor mientras más detallada esté?

No. Una vez que un Agente selecciona y ejecuta una skill, todo su contenido ocupa el presupuesto de procesamiento actual — escribirla demasiado larga en realidad desplaza la atención de la IA hacia todo lo demás y ralentiza su respuesta. La regla general es: escribe solo el ‘enfoque específico y propio’ que la IA no podría haber descubierto por sí sola; los detalles que no se necesitan a diario deben separarse en una carpeta complementaria y cargarse solo cuando realmente se necesiten.

P3: ¿Por qué una IA que parece tan inteligente todavía se equivoca en algo tan simple como sumar?

Porque un modelo de lenguaje, en esencia, está ‘prediciendo’ el siguiente resultado más probable, no realizando en verdad un cálculo preciso. Mientras más campos y más desordenados los números, más fácil es que la IA se equivoque haciendo el cálculo mentalmente sobre la marcha. Cualquier paso que deba ser preciso y consistente cada vez debería manejarse con lógica de programa fija, y la IA solo debería encargarse de decidir cuándo invocarla.

P4: ¿Está bien simplemente instalar un archivo de skill ya hecho que alguien más compartió?

Lo mejor es tratarlo de la misma forma en que tratarías la introducción de un nuevo paquete de software: un archivo de skill puede contener código que realmente se ejecuta, y puede llegar a tocar archivos locales o claves de API ya configuradas en tu sistema. Leerlo y confirmar qué hace realmente antes de instalarlo es mucho más seguro que ‘suena conveniente, así que simplemente lo uso’.

P5: ¿Estas prácticas solo aplican a los productos de Claude?

Según el video original, este enfoque de skills basado en ‘carpeta más archivo de instrucciones’ está siendo impulsado como un estándar abierto multiplataforma (agentskills.io), y el video también menciona que otras plataformas de Agentes, como OpenAI Codex, funcionan de manera similar. Esto es un relato de segunda mano del presentador del video — este sitio no ha verificado de forma independiente si las especificaciones reales son completamente idénticas entre plataformas — pero los principios de juicio que cubre este artículo (escribir descripciones precisas, mantener el contenido conciso, no dejar que la IA adivine en pasos que importan) son pensamiento de ingeniería general, no limitado a las herramientas de un solo proveedor.

Nota de la Fuente

Este artículo está basado en un video del canal de YouTube ‘IBM Technology’, publicado el 10 de agosto de 2026, titulado ‘5 Best Practices for Building AI Agent Skills’ (presentado por Martin Keen y Bri Kopecki), reorganizado y contado de forma narrativa en lugar de traducido literalmente. ‘Lin Zhean’ en este artículo es un personaje ilustrativo usado con fines explicativos, no un cliente real; el escenario de la demo del reporte mensual y las correcciones descritas son una reconstrucción ilustrativa, no el registro de un caso de ningún cliente real. La sección que indica que una auditoría de seguridad de skills públicas encontró aproximadamente 35% con fallas de seguridad y cerca de 13% con problemas graves es el relato del presentador del video sobre cierta auditoría; el propio video no identifica más a fondo la fuente, y este sitio no lo ha verificado de forma independiente — se ofrece únicamente como referencia de conciencia de riesgo y no representa la proporción real de ningún repositorio de skills en específico. La estructura de archivos de skill descrita (carpetas skill.md, references y scripts) y la orientación sobre cantidad de líneas/tokens también provienen del video original; las especificaciones reales deben verificarse con el estándar público de agentskills.io y la documentación oficial de cada plataforma. La afirmación de que ‘agentskills.io es un estándar abierto multiplataforma’ y que ‘plataformas como OpenAI Codex funcionan de manera similar’ es igualmente un relato de segunda mano del presentador del video, y este sitio no ha verificado de forma independiente si las especificaciones reales son completamente idénticas entre plataformas.

Actúa Ahora

Tener claro cuándo debería activarse realmente una AI Agent Skill, cuánto contenido necesita y qué pasos no deberían dejarse a que la IA adivine, es en realidad el mismo ejercicio que tener claro cuántos tokens está quemando tu automatización de IA cada mes — ambos empiezan por poner a la vista un consumo que de otra forma es invisible, para saber dónde trazar el límite. Prueba AI Token King gratis, y déjanos mostrarte exactamente cuántos tokens está usando realmente cada agente y cada skill de tu equipo, para que puedas establecer los límites de uso correctos para tu equipo.