Qué son las skills de un agente de IA (y cómo revisarlas antes de instalar una)

10 de agosto del 202613 minIA, Agentes, Skills, Seguridad, Claude Code, Codex, DevOps

Respuesta corta (60 segundos): Una skill es un paquete versionado de instrucciones (y, opcionalmente, herramientas y scripts) que un agente de IA carga bajo demanda cuando la tarea lo requiere. A diferencia de un prompt (texto efímero que vive en el chat) o de un plugin (código que se ejecuta y devuelve datos), una skill es documentación reusable que el agente lee cuando decide que aplica. Antes de instalar una skill de terceros revisá cuatro cosas: procedencia (autor y licencia), permisos (qué herramientas declara), mantenimiento (último commit, tests, issues) y superficie de ataque (qué puede ejecutar contra tu filesystem, red y credenciales).

Si usás Claude Code, Codex CLI, Cursor, o cualquier coding assistant con agentes que trabajan sobre tu máquina, ya viste el concepto: hay un directorio .skills/ o .agents/skills/ y dentro, archivos Markdown que le enseñan al agente cosas específicas — cómo revisar tu SEO, cómo correr una migración, cómo aplicar el estilo de tu empresa. Lo que casi nadie explica bien es qué son exactamente, en qué se diferencian de un prompt o un plugin, y cómo auditar una antes de meterla en tu repo. Este post es la guía que wish hubiera tenido la primera vez que recomendé skills a un cliente.

Qué es una skill, concretamente

Una skill es un archivo (o conjunto de archivos) que contiene:

1. Un nombre y una descripción que el agente usa para decidir si la carga.
2. Instrucciones en lenguaje natural sobre cuándo aplicar la skill y cómo proceder.
3. Opcionalmente, herramientas y scripts declarados con permisos acotados.

La idea central es simple: en lugar de pegar un prompt largo en cada conversación, escribís una vez un procedimiento reusable, lo versionás en tu repo, y el agente lo carga solo cuando la tarea coincide con su descripción. Es el equivalente a tener un manual de procedimientos para tu agente.

Anatomía mínima de una skill (formato típico, similar al usado por Claude Code, Codex y otros):

mi-skill/
└── SKILL.md          # nombre, descripción, instrucciones
    ├── scripts/      # opcional: código ejecutable
    └── tools.json    # opcional: declaración de herramientas y permisos

El archivo SKILL.md siempre lleva un frontmatter con dos campos que el agente indexa:

---
name: nombre-de-la-skill
description: >-
  Una descripción corta que el agente usa para decidir si la carga.
  Si la tarea encaja con esta descripción, la skill se inyecta en el
  contexto. Si no, el agente ni la ve.
---

Lo que viene después del frontmatter son instrucciones en prosa. Pueden ser tan cortas como un checklist o tan largas como un manual de 200 líneas. El agente las lee como contexto adicional cuando decide activar la skill.

Qué aporta una skill (y qué no)

Una skill aporta tres cosas, en orden de importancia:

1. Instrucciones especializadas (el núcleo)

Texto que describe un procedimiento, una convención, o un dominio. Ejemplos típicos:

• "Cómo auditar el SEO de una página (qué mirar, en qué orden, qué reportar)"
• "Cómo escribir commits conventional en este repo"
• "Cómo aplicar el sistema de diseño de la empresa"
• "Cómo deployar a producción sin romper la pipeline"

Esto es conocimiento reusable que de otro modo tendrías que pegar en cada conversación o re-explicar cada vez que abrís un chat nuevo.

2. Herramientas declaradas (opcional)

La skill puede declarar herramientas que el agente ya tiene disponibles: leer un archivo, ejecutar un comando, hacer una búsqueda. Lo que cambia con la skill es qué herramientas se exponen y bajo qué condiciones. Una skill de SEO, por ejemplo, puede declarar permiso de leer public/ y hacer fetch de URLs, pero no de ejecutar comandos del sistema.

3. Scripts y utilidades (opcional)

Algunas skills incluyen scripts que el agente puede invocar. Por ejemplo, una skill de "regenerar imágenes de blog" puede traer un scripts/regenerate.js que el agente llama cuando corresponde. Estos scripts corren con los permisos del usuario que ejecuta el agente — es decir, con acceso a tu filesystem.

Lo que una skill no es:

• No es un modelo distinto al que ya usás.
• No es un plugin en el sentido clásico de Chrome/Figma (no se inyecta en una UI).
• No es un agente paralelo — es contenido que el agente actual lee.

Skill vs prompt vs plugin: la diferencia real

Esta es la confusión más común. Los tres términos suenan similares pero hacen cosas distintas.

La forma más clara de pensarlo:

• Prompt = lo que decís en este momento.
• Skill = el manual de procedimientos que el agente consulta.
• Plugin = una herramienta que el agente usa para hacer algo concreto.

Ejemplo concreto

Imaginá que querés que tu agente revise SEO de una página antes de mergear un PR.

• Sin skill, con prompt: tendrías que pegar el checklist en cada chat ("primero mirá el title tag, después la meta description, después los headings…"). Se pierde entre sesiones.
• Con skill: escribís una vez skills/seo-audit/SKILL.md con el checklist. Cada vez que pedís una auditoría, el agente detecta que la tarea coincide y carga la skill automáticamente.
• Con plugin: escribís un binario tipo seo-audit-cli que lee la URL y devuelve un JSON. El agente lo llama como herramienta.

Las tres se pueden combinar: la skill le dice al agente cuándo y cómo auditar; el plugin le da los datos para hacerlo; el prompt del usuario le dice qué página auditar.

Quién usa skills hoy (y por qué importa)

El patrón se popularizó entre 2024 y 2026 con el auge de los coding agents. Tres referencias concretas del ecosistema que vale la pena conocer:

• Claude Code (Anthropic): usa .claude/skills/<nombre>/SKILL.md con frontmatter name + description. Soporta tools declaradas por skill.
• Codex CLI / OpenAI (2026): usa .codex/skills/ con el mismo patrón, integrando tools del sistema.
• Pi coding agent (el agente que está leyendo este archivo): usa .pi/skills/ y .agents/skills/, también con frontmatter name + description y carga bajo demanda.
• Cursor, Aider, Continue.dev: cada uno tiene su convención, pero el patrón es el mismo — un directorio versionado con skills que el agente indexa.

Lo común a todos: las skills son archivos de texto en tu repo. Eso tiene tres consecuencias prácticas:

1. Se versionan con git. Un cambio en una skill es un PR revisable, con diff, con code review.
2. Se pueden auditar. Antes de mergear, mirás qué hace la skill como mirás cualquier código.
3. Se pueden compartir. Un registry central (oficial o de la comunidad) distribuye skills curadas. La pregunta es cuáles confiar — y eso nos lleva al checklist.

El checklist de seguridad: 4 cosas que revisás antes de instalar una skill

Una skill es código que corre con tus permisos. Si la instalás sin revisar, le estás dando al autor original acceso a tu filesystem, tu red y, potencialmente, tus credenciales. Esto no es teórico — ya hubo incidentes de skills maliciosas en registries públicos en 2025. El checklist mínimo antes de instalar cualquier skill de terceros:

1. Procedencia

• ¿Quién la escribió? Un autor conocido con track record es distinto de un usuario anónimo creado ayer.
• ¿Bajo qué licencia? MIT/Apache 2 son seguras para uso comercial. "All rights reserved" o ausencia de licencia es una bandera roja.
• ¿Está firmada o firmada por la organización? Algunos registries publican checksums o firmas. Usalas si existen.
• ¿Tiene historia? Mirá el log de git: si el repo tiene un commit inicial y después silencio de dos años, desconfiá.

2. Permisos

• ¿Qué herramientas declara? Si la skill dice "puede ejecutar comandos del sistema", es distinto a una que solo lee archivos.
• ¿Qué operaciones habilita? Lectura de archivos es de bajo riesgo. Escritura en tu home, rm -rf, ejecución de binarios: alto riesgo.
• ¿Accede a la red? Llamadas HTTP salientes pueden exfiltrar datos. Si la skill declara una herramienta de fetch, mirá a dónde llama y con qué payload.
• ¿Accede a credenciales? Si lee variables de entorno o archivos tipo ~/.aws/credentials, .ssh/, .npmrc, etc., es una bandera roja seria.

3. Mantenimiento

• ¿Tiene commits recientes? Más de 12 meses sin actividad suele significar que la skill quedó abandonada — y abandonada es vulnerable a que alguien la tome y le inyecte código.
• ¿Tiene tests? Las skills con tests son más confiables: significa que el autor pensó en casos de falla.
• ¿Tiene issues abiertos sin responder? Una acumulación de issues críticos sin triage es señal de abandono.
• ¿Hay un canal para reportar problemas? Un README con instrucciones claras de "cómo reportar una vulnerabilidad" es buena señal. La ausencia total de instrucciones es mala señal.

4. Superficie de ataque

• ¿La skill ejecuta código que toca tu filesystem? Si sí, ¿qué archivos y con qué permisos?
• ¿Hace llamadas de red? ¿A qué hosts? ¿Con qué datos? Si no podés responder, no la instales.
• ¿Tiene dependencias externas? Una skill que importa un paquete npm aleatorio está heredando la superficie de ataque de ese paquete (y de sus transitivas).
• ¿Está ofuscada? Skills con código minificado, nombres de variables sin sentido o lógica difícil de seguir son una bandera roja inmediata. Si no podés leer qué hace, no la corras.

Tabla resumen

Regla de pulgar: si tres de las cuatro columnas están en "baja preocupación" y la cuarta no es preocupante, podés instalarla con monitoreo. Si dos o más están en "alta preocupación", no la instales sin auditoría independiente.

Cómo crear tu primera skill (5 minutos)

Si querés probar el patrón sin instalar nada de terceros, podés crear una skill propia en tu repo. El flujo mínimo es:

1. Elegí un procedimiento que repetís. Ejemplo: "cada vez que abro un PR, quiero que el agente revise tres cosas antes de mergear".
2. Creá un directorio .skills/<nombre>/ (o .agents/skills/<nombre>/, o el que use tu agente).
3. Escribí SKILL.md con frontmatter name + description y el procedimiento en prosa.
4. Versioná con git y commiteá. Si tu agente indexa skills del repo, va a aparecer disponible sin que hagas nada más.

Ejemplo real mínimo, una skill de "revisión de PRs":

.agents/skills/pr-review/
└── SKILL.md

---
name: pr-review
description: >-
  Usar cuando el usuario pide revisar un pull request o un diff antes
  de mergear. Cubre style guide, tests, seguridad básica y formato de
  conventional commits.
---

# PR Review

Cuando el usuario pida revisar un PR o un diff:

1. **Style guide** — verificar que el código sigue el style guide del
   repo (`.eslintrc`, `.prettierrc`, `gofmt`, etc.).
2. **Tests** — confirmar que el cambio incluye tests, o justificar
   por qué no.
3. **Seguridad básica** — buscar secrets hardcodeados, llamadas a
   endpoints sin autenticación, inputs no validados en handlers HTTP.
4. **Conventional commits** — verificar que el mensaje del commit sigue
   el formato `tipo(scope): descripción`.

Reportar los hallazgos en orden de severidad. No aprobar si falla
seguridad o tests.

Eso es todo. Esa skill vive en tu repo, se puede revisar en un PR, y el agente la carga automáticamente cuando pedís una revisión. Si cambia el style guide, actualizás SKILL.md con un nuevo PR.

Cuándo NO usar skills

Conviene no usar skills cuando:

• El procedimiento es único o de una sola vez. Escribilo como prompt en el chat.
• Necesitás ejecución de lógica compleja. Ahí conviene un plugin/tool, no una skill (las skills son texto, no código de aplicación).
• El equipo no va a mantener el archivo. Una skill abandonada es peor que no tener skill — porque alguien puede confiar en que existe y aplicarla desactualizada.
• El procedimiento cambia cada semana. Las skills son contenido estable; si cambia todo el tiempo, mantenerlas se vuelve overhead.

En esos casos, un prompt bien escrito en el system prompt del equipo o un script versionado alcanza.

Lo que viene

Tres tendencias que vas a ver en los próximos 12 meses:

1. Registries firmados con attestation. Igual que npm introdujo npm audit y npm signing, los registries de skills van a empezar a exigir firmas y checksums. Confiar en una skill va a ser tan rutinario como confiar en una dependencia.
2. Skills con permisos declarados en el frontmatter. Hoy los permisos están en el código de la skill; en 2027 van a estar en el YAML, auditable sin ejecutar nada. Es el equivalente a un package.json con permissions.json.
3. Curación comunitaria por dominios. Igual que pasa con las actions de GitHub, van a emerger listas curadas por comunidad ("skills oficiales de SEO", "skills oficiales de seguridad") que dan una capa de confianza implícita. Eligé siempre de esas listas antes que del registry abierto.

Mientras tanto, el consejo práctico sigue siendo el mismo: revisá procedencia, permisos, mantenimiento y superficie antes de instalar. Si una de las cuatro te genera duda, no la instales sin auditoría.

---

Sources and verified data:

• Claude Code skills documentation (Anthropic, 2026) — formato de SKILL.md, frontmatter y carga bajo demanda.
• Anthropic Claude Sonnet 5 launch (Jun 30 2026) — referencia de pricing para el cálculo de costo de operaciones con skills.
• Codex CLI skills reference (OpenAI, 2026) — patrón equivalente en el ecosistema OpenAI.
• Pi coding agent skills format — spec del frontmatter name + description.
• OWASP Top 10 for LLM Applications (2025) — framework para evaluar superficie de ataque en herramientas de agentes.
• npm supply chain attack analysis (2025) — precedente de cómo registries abiertos pueden comprometer el entorno de un developer.

Preguntas frecuentes

¿Qué es una skill de un agente de IA?

Una skill es un paquete versionado de instrucciones y, opcionalmente, herramientas y scripts que un agente de IA carga bajo demanda cuando la tarea lo requiere. A diferencia de un prompt (texto que se envía en cada conversación) o un plugin (extensión que conecta el modelo con un sistema externo), una skill es contenido reusable que el agente lee solo cuando decide que aplica.

¿En qué se diferencia una skill de un prompt?

Un prompt es texto que vos escribís (o el sistema inyecta) en cada conversación; vive en el chat. Una skill es un archivo Markdown versionado que describe un procedimiento o dominio, que el agente carga cuando la tarea coincide con su descripción. Las skills se comparten, versionan y revisan como código; los prompts no.

¿En qué se diferencia una skill de un plugin o una herramienta?

Un plugin/herramienta (tool) es código que se ejecuta y devuelve datos (leer un archivo, llamar a una API). Una skill es principalmente documentación e instrucciones: le dice al agente cuándo y cómo usar las herramientas que ya tiene. Una skill puede declarar herramientas propias, pero su núcleo es texto.

¿Las skills pueden ejecutar código o conectarse a internet?

Depende del agente. En sistemas como Claude Code, Codex CLI o coding assistants similares, una skill puede incluir scripts y declarar herramientas con permisos acotados (lectura de archivos, ejecución de comandos, acceso a red). El alcance de esos permisos es lo que tenés que revisar antes de instalar una.

¿Qué revisar antes de instalar una skill de terceros?

Cuatro cosas: (1) procedencia — quién la escribió y bajo qué licencia, (2) permisos — qué herramientas declara y qué operaciones habilita, (3) mantenimiento — si tiene commits recientes, tests y un canal para reportar issues, (4) superficie de ataque — si ejecuta código que toca tu filesystem, red o credenciales. Si falla cualquiera de las cuatro, no la instales sin auditoría.

¿Las skills reemplazan a los prompts del sistema?

No, se complementan. El system prompt es el "modo de ser" del agente (tono, reglas globales, identidad). Las skills son conocimiento y procedimientos específicos que se cargan según la tarea. Es análogo a un sistema operativo vs las aplicaciones: el SO te da el entorno, las apps te dan capacidades.