Agent Skills vs Custom Instructions en código IA: cuándo usar cada una

Los asistentes de IA para código han evolucionado mucho en poco tiempo. Ya no son solo autocompletado inteligente: son agentes que pueden razonar, planificar y ejecutar tareas complejas de forma autónoma. Pero cuanto más autónomo es un agente, más contexto necesita: saber cómo trabaja tu equipo, qué convenciones sigues, qué herramientas usas...

Ahí es donde aparece el concepto de Agent Skills ( "habilidades del agente", aunque nadie les llama así). Se trata de una manera estructurada de darle a tu asistente de IA exactamente la información que necesita, cuando la necesita, sin saturarlo con todo a la vez.

Imagina un proyecto con documentación técnica detallada: convenciones de Git, reglas de testing, guía de estilo para la API, instrucciones de despliegue y políticas de seguridad. Si metes todo eso en las "Custom Instructions" del proyecto, el agente las mete en el contexto en cada interacción, aunque solo estés pidiendo que te renombre una variable. Eso es ruido constante, y los modelos de lenguaje se degradan con ruido: prestan menos atención a lo importante y cometen más errores. Pero, encima, consumes más tókenes en cada llamada y tu límite mensual de uso te lo cepillas el día 5 del mes 🤦🏻‍♂️

Con los Skills, ese mismo conocimiento está troceado en bloques especializados. Cuando le pides al agente que revise un test, carga las instrucciones de testing. Cuando le pides que prepare un Pull Request, carga las convenciones de Git. Cuando renombras una variable, no carga nada extra. El agente trabaja siempre con el contexto mínimo necesario para hacer bien su trabajo. ¡Magia! No, solamente una buena idea, creada por Antropic para Claude Code y ahora adoptada por la mayoría de las herramientas de código asistido por IA (y también en la mayoría de chats convencionales).

¿Qué son las Agent Skills y para qué sirven?

Una Skill es, en esencia, un bloque de conocimiento empaquetado que le entregas al agente de IA para que sepa cómo comportarse en un contexto concreto. Piensa en ello como una ficha técnica que le dices al agente: "cuando trabajes en este proyecto para hacer esta tarea estas son las reglas por las que debes regirte y los pasos para realizar la tarea".

Un Skill puede contener instrucciones en lenguaje natural, referencias a scripts o herramientas, convenciones de nomenclatura, flujos de trabajo del equipo, o cualquier cosa que normalmente tendrías que explicar en cada conversación.

La clave está en que se define una sola vez y el agente la consulta automáticamente cuando es relevante.

El objetivo no es solo la comodidad, sino la consistencia. Sin Skills, cada sesión empieza desde cero. Con ellas, el agente sabe cómo trabajáis tú y tu equipo aunque sea la primera vez que ejecuta esa tarea.

El estándar abierto de Agent Skills (agentSkills.io) nació de la necesidad de portabilidad: la idea es que una Skill escrita para un asistente funcione también en otro. Así que si creas un Skill te vale para reutilizarlo en cualquier agente de código IA que los soporte, hoy en día la mayoría (Claude Code, GitHub Copilot, Codex, Gemini CLI, Antigravity, Cursor...).

¿Cómo funcionan las Agent Skills en la práctica?

Una Skill se define como un archivo de texto estructurado, normalmente en formato Markdown. Ese archivo tiene dos partes principales: una cabecera con metadatos (nombre, descripción, cuándo debe activarse) y el cuerpo con las instrucciones o recursos que el agente debe usar.

Un ejemplo mínimo tendría esta pinta:

text---
name: convenciones-git
description: Usa esta Skill cuando el usuario pida hacer commits, crear ramas o revisar el historial de Git
---

# Convenciones de Git del proyecto

- Las ramas de feature siguen el patrón: `feat/TICKET-descripcion`
- Los commits usan Conventional Commits: `feat:`, `fix:`, `chore:`...
- Nunca hacer push directo a `main`. Siempre PR con al menos una revisión.

Cuando el agente recibe una tarea, lee los metadatos de todas las Skills disponibles y decide cuáles son relevantes para esa tarea concreta. Solo entonces carga el contenido completo de las que necesita. Este comportamiento es importante, y tiene implicaciones técnicas que veremos más adelante.

Las Skills pueden vivir en el repositorio del proyecto (Skills de proyecto, para que todo el equipo las comparta) o en un directorio personal del desarrollador (Skills de usuario, para preferencias individuales, normalmente en una carpeta de tu carpeta raíz de usuario en el disco duro). De este modo, con las del proyecto garantizamos coherencia en el equipo, mientras que las personales permiten adaptar el comportamiento a nuestro flujo de trabajo particular.

¿Agent Skills o Custom Instructions: cuándo usar cada una?

Antes de que existieran las Agent Skills, la forma de personalizar los asistentes era mediante Custom Instructions: un archivo de texto o varios que se añade al contexto del asistente de forma global y permanente, con el dispendio de contexto y el ruido que ello supone.

Las custom instructions siguen siendo útiles, pero tienen limitaciones cuando trabajas en proyectos complejos.

La diferencia principal entre ellos no es tanto de formato, sino de alcance y activación entre otras dimensiones importantes:

Las Custom Instructions tienen sentido para preferencias que aplican de forma amplia: el idioma en que quieres las respuestas, el estilo de código general, si quieres respuestas más o menos detalladas, qué tecnologías concretas quieres usar.... Y también pueden ser específicas para un repositorio o incluso de carpetas concretas dentro de un proyecto. La mayoría de asistentes permiten ese nivel de granularidad.

Entonces, ¿dónde está la diferencia real? En que las Custom Instructions, sean globales, de proyecto o de carpeta, se cargan siempre que aplica su ámbito. Si tienes instrucciones ligadas a un repositorio, el agente las lleva en contexto en cada interacción dentro de ese repo, independientemente de lo que estés haciendo.

Con Agent Skills, el agente decide en cada tarea qué bloques de conocimiento son relevantes y carga solo esos. La granularidad es de la tarea, no del proyecto.

La regla práctica es: usa Custom Instructions para lo que no cambia y se aplica todo el rato, y Agent Skills para lo que sí cambia.

¿Cómo carga el agente la información? El sistema de tres niveles

Este es el detalle técnico que más me parece que se pasa por alto cuando se habla de Agent Skills, y es probablemente el más relevante para entender por qué funcionan bien en proyectos grandes.

Los agentes de IA trabajan con una ventana de contexto: la cantidad de texto que pueden "tener en mente" en un momento dado. Esa ventana es limitada y además normalmente los modelos degradan su rendimiento a medida que aumenta. Si metes demasiado contexto de golpe, el agente se degrada: presta menos atención a las cosas importantes, comete más errores, y de paso gastas más tókenes (lo que, o bien te puede cortar el servicio si superas el límite, o te puede costar dinero según el modelo de costes que tengas con el proveedor del asistente). Incluso aunque ejecutes un LLM local que "no te cueste dinero" (te lo cuesta de otra manera), un contexto más grande de lo necesario penaliza el rendimiento y también mete ruido.

Las Agent Skills resuelven este problema con un sistema de carga progresiva en tres niveles:

• Nivel 1 — Metadatos: el agente carga solo los nombres y descripciones de todas las Skills disponibles. Es una lectura ligera. Con eso decide cuáles son relevantes para la tarea actual.

• Nivel 2 — Instrucciones: para las Skills seleccionadas, carga el contenido de las instrucciones en lenguaje natural. Ya tiene lo suficiente para orientarse sobre cómo actuar.

• Nivel 3 — Recursos: solo si la tarea lo requiere, carga los recursos adicionales referenciados en la Skill: scripts, fragmentos de código, instrucciones adicionales, documentación técnica específica en la web o en el propio repositorio...

  El resultado es que en cada momento el agente tiene en contexto solo lo que necesita. Una tarea de refactorización de código no carga las instrucciones de la Skill de despliegue en producción. Una operación sobre Git no arrastra la documentación de la API del proyecto.

Instrucción recibida
     │
     ▼
Lee metadatos de TODAS las Skills  ← nivel 1 (ligero)
     │
     ▼
Selecciona Skills relevantes
     │
     ▼
Carga instrucciones de las Skills seleccionadas  ← nivel 2
     │
     ▼
¿Necesita recursos adicionales?
     ├── No → ejecuta la tarea
     └── Sí → carga solo esos recursos  ← nivel 3

Este diseño tiene tres efectos prácticos importantes:

1. El agente es más preciso porque trabaja con contexto relevante, no con todo a la vez.

2. El coste en tókenes se reduce porque no hay información innecesaria en cada llamada.

3. Puedes tener decenas de Skills en un proyecto sin que eso penalice apenas el rendimiento: el agente no las carga todas, solo las que aplican.

Esto contrasta directamente con meter todo en las Custom Instructions o en el system prompt: ese texto va siempre en contexto, lo necesites o no. Con un par de instrucciones no pasa nada. Con un proyecto mediano, se convierte en ruido y en todos los problemas mencionados.

¿Merece la pena el esfuerzo de crear Agent Skills propias?

La respuesta corta: depende de cuánto tiempo pases explicándole lo mismo al asistente.

Si trabajas en un proyecto de corta duración o en solitario, probablemente las Custom Instructions te bastan. La sobrecarga de crear y mantener Skills no se justifica si el contexto del proyecto es simple.

Pero si tu equipo tiene convenciones establecidas, múltiples proyectos con características distintas, o flujos de trabajo que el asistente tiene que seguir de forma consistente, las Skills amortizan el esfuerzo inicial con rapidez. La primera semana inviertes tiempo en documentar lo que ya existe. A partir de ahí, el asistente deja de cometer los mismos errores repetitivos y deja de hacerte las mismas preguntas.

Hay otro argumento menos obvio: las Skills te obligan a documentar. Escribir una Skill para un flujo de trabajo implica explicar ese flujo de forma clara y explícita. Ese proceso a menudo revela inconsistencias o pasos que "todo el mundo sabe" pero que nadie ha escrito nunca. El valor no es solo para la IA, es para el equipo.

Si te paras a pensarlo, en el fondo crear las Skills de tu equipo o de tu forma de trabajar, te obliga a hacer lo que deberías hacer en un proyecto normal que solo involucre a personas: tenerlo todo bien documentado. Con los LLMs, que son muy listos pero "saben demasiado", tiene incluso más importancia.

Además no hay que olvidar que el ecosistema de Skills públicas también está creciendo. Existen repositorios comunitarios con Skills listas para usar para frameworks, herramientas de testing, pipelines de CI/CD o convenciones de código ampliamente usadas. Y si nos salimos del código, todavía para muchas otras tareas. Antes de escribir la tuya desde cero, vale la pena revisar si alguien ya lo ha hecho por ti.

Y hay un truco que muchas veces se pasa por alto: puedes pedirle al propio agente que te genere las Skills. Dale el contexto básico de tu tarea (objetivo, las convenciones que sigues, las herramientas que usas, cómo trabaja tu equipo...) y pídele que estructure todo eso en un Skill listo para usar. No saldrán perfectas a la primera, pero te ahorran el trabajo de partir de la hoja en blanco. Las retocas un poco en unos minutos, y ya tienes una base sólida. Luego las vas iterando a medida que las vayas usando y descubriendo "cositas". Es un uso un poco "meta": usar el asistente para enseñarle cómo quieres que se comporte, pero muy efectivo.