Cómo funcionan los skills de agentes de IA

Respuesta

Un skill reúne instrucciones en SKILL.md y recursos opcionales para que un agente siga un procedimiento. El agente interpreta el Markdown y usa herramientas para ejecutar los scripts cuando la tarea lo requiere.

El nombre y la descripción permiten descubrirlo; el contenido completo se carga cuando se utiliza.¹
Claude Code, Codex e IBM Bob tienen rutas de instalación diferentes.²
Un buen skill define entradas, decisiones, pasos, resultados y cómo comprobarlos.³

AlcanceGuía en españolconsultada el 23 de octubre de 2026

¿Cómo actúa un skill durante una tarea?

De la petición al resultado

Estructura del diagrama

Usuario peticion
Metadatos catalogo
Elegir skill activar
Leer SKILL.md leer
Evaluar recursos recursos-paso
Aplicar pasos aplicar
Verificar verificar
activar → leer · activar
aplicar → verificar · evidencia
catalogo → activar · coincidencia
leer → recursos-paso · instrucciones
peticion → catalogo · tarea
recursos-paso → aplicar · según tarea

Usuario
Por ejemplo: «Revisa este archivo y genera un informe».
Metadatos
El agente conoce el nombre y la descripción de los skills disponibles.
Elegir skill
Se activa por solicitud explícita o por una tarea que coincide con su descripción.
Leer SKILL.md
El agente lee el procedimiento completo antes de aplicarlo.
Evaluar recursos
Decide qué referencias, plantillas o scripts necesita para esta tarea.
Aplicar pasos
Lee referencias, usa plantillas o ejecuta scripts con herramientas si hacen falta.
Verificar
Revisa el resultado con los criterios indicados y comunica el producto final.

La carga progresiva evita incorporar todos los archivos de todos los skills al contexto. El detalle de selección depende del agente.¹³

¿Qué archivos contiene?

Anatomía de un skill

Estructura del diagrama

mi-skill/ raiz
SKILL.md principal
YAML: name y description cabecera
Markdown: procedimiento cuerpo
scripts/ scripts
references/ referencias
assets/ recursos
agents/openai.yaml interfaz
raiz → principal
principal → cabecera
principal → cuerpo
raiz → scripts
raiz → referencias
raiz → recursos
raiz → interfaz

Archivo o carpeta	Función	¿Es obligatorio?
`SKILL.md`	Metadatos YAML al inicio; instrucciones Markdown después.	Sí, en el formato abierto.
`scripts/`	Código para cálculos, conversiones o tareas repetibles.	No.
`references/`	Documentación que el agente consulta cuando corresponde.	No.
`assets/`	Plantillas, imágenes, ejemplos de salida y otros recursos.	No.
`agents/openai.yaml`	Presentación, política de invocación y dependencias en Codex.	No; extensión específica del agente.

El árbol descompone conceptualmente SKILL.md en cabecera y cuerpo; esas dos partes pertenecen al mismo archivo. Las carpetas auxiliares son convenciones recomendadas.¹³

¿Qué lenguaje se utiliza y quién lo ejecuta?

Formato o lenguaje	Uso dentro del skill	Quién lo interpreta o ejecuta
Markdown `.md`	Pasos, decisiones, ejemplos y referencias.	El modelo interpreta las instrucciones.
YAML	Metadatos entre delimitadores `---`.	El agente o su cargador lee los campos.
Python `.py`	Procesar archivos, calcular, transformar datos.	Un intérprete Python mediante una herramienta.
JavaScript `.js` o `.mjs`	Automatización, APIs, generación de HTML.	Node.js u otro entorno compatible.
TypeScript `.ts`	Automatización con tipos.	Un entorno que soporte TS o código compilado a JS.
Bash o Shell `.sh`	Encadenar herramientas de terminal.	Una shell disponible en el sistema.
JSON, CSV y otros datos	Configuración, esquemas y ejemplos.	El script o la herramienta que los consuma.

Un skill puede funcionar solo con Markdown. Los lenguajes de scripts dependen del entorno y de las herramientas del agente. Instalar el skill tampoco instala automáticamente Python, Node.js o sus dependencias.¹

Ejemplos de ejecución que puede indicar SKILL.mdbash

python3 scripts/validar.py entrada.json
node scripts/generar.mjs entrada.json
bash scripts/comprobar.sh

¿Qué cambia entre Claude Code, Codex e IBM Bob?

Agente	Instalación local en el proyecto	Instalación personal o global
Claude Code	`.claude/skills/mi-skill/SKILL.md`	`~/.claude/skills/mi-skill/SKILL.md`
Codex	`.agents/skills/mi-skill/SKILL.md`	`~/.agents/skills/mi-skill/SKILL.md`
IBM Bob	`.bob/skills/mi-skill/SKILL.md`	`~/.bob/skills/mi-skill/SKILL.md`
Cursor, vía Skills CLI	`.agents/skills/mi-skill/SKILL.md`	`~/.cursor/skills/mi-skill/SKILL.md`
GitHub Copilot, vía Skills CLI	`.agents/skills/mi-skill/SKILL.md`	`~/.copilot/skills/mi-skill/SKILL.md`

En Claude Code se puede invocar con /nombre-del-skill. En Codex CLI y su extensión se puede seleccionar con /skills o mencionar con $nombre-del-skill. Ambos admiten selección por descripción.⁴³

Las rutas de IBM Bob, Cursor y Copilot y el identificador bob se verificaron en Skills CLI. No se confirmó aquí una sintaxis nativa de invocación de Bob.²

El formato base es compartido; las opciones específicas requieren comprobar compatibilidad. Por ejemplo, agents/openai.yaml pertenece a Codex y context: fork es una opción de Claude Code.³⁴

¿Cómo escribir un árbol de decisiones en Markdown?

Define preguntas observables y una acción para cada respuesta. Este método es una recomendación de diseño para evitar instrucciones ambiguas.

Decidir si hacen falta referencias o scripts

Estructura del diagrama

¿Entradas completas? entrada
Pedir el dato faltante solicitar
¿Tarea mecánica repetible? automatizar
¿Falta contexto de dominio? contexto
Ejecutar script disponible ejecutar
Leer referencia indicada consultar
Aplicar instrucciones instrucciones
automatizar → contexto · No
automatizar → ejecutar · Sí
contexto → consultar · Sí
contexto → instrucciones · No
entrada → automatizar · Sí
entrada → solicitar · No

Árbol de decisiones copiable para SKILL.mdmarkdown

## Decisiones
- Si falta la ruta del archivo: pedirla antes de continuar.
- Si la tarea exige un cálculo repetible:
  - Si existe un script adecuado: usarlo.
  - Si no existe: seguir el procedimiento manual documentado.
- Si falta contexto del dominio: leer references/reglas.md.
- Si las entradas están completas: aplicar el procedimiento.
- Después de cualquier ruta: verificar el resultado.
- Si falla la verificación: corregir la causa y volver a verificar.

Las condiciones escritas guían al modelo. Para una validación estricta de datos o cálculos, implementa también la comprobación en un script.

¿Qué técnicas de Markdown ayudan a crear buenos skills?

Técnica	Cómo escribirla	Para qué sirve
Contrato de entrada y salida	`## Entradas` y `## Salida`	Define qué recibir y qué entregar.
Pasos numerados	`1. Inspecciona...`	Expresa un orden de trabajo.
Árbol de decisiones	Listas con condiciones `Si...`	Elige rutas según hechos observables.
Tabla de decisión	Condición, acción y comprobación.	Compara varios casos sin repetir pasos.
Ejemplos de entrada y salida	Bloques de código con casos concretos.	Aclara el formato esperado.
Checklist final	`- [ ] Comprueba...`	Define los criterios de aceptación.
Referencias progresivas	Enlace relativo con cuándo leerlo.	Mantiene corto el archivo principal.
Límites y recuperación	`Si falla X, haz Y`.	Evita reintentos sin criterio.

Estas técnicas son recomendaciones de autoría. La especificación permite instrucciones libres y recomienda separar referencias extensas del archivo principal.¹

Cabecera portable de SKILL.mdyaml

---
name: revisar-documento
description: Revisa claridad y estructura de un texto y entrega hallazgos priorizados. Usar cuando pidan revisar un borrador. No usar para traducir.
---

Cuerpo de SKILL.md después de la cabecera YAMLmarkdown

# Revisar documento

## Entradas
Recibe el texto o su ruta, el público y el objetivo.

## Procedimiento
1. Lee el documento completo.
2. Identifica el objetivo y los criterios de revisión.
3. Aplica las decisiones de la sección siguiente.
4. Entrega hallazgos con ubicación y una propuesta concreta.

## Decisiones
- Si falta el texto o el archivo: solicita ese dato.
- Si el público no se conoce: declara el supuesto que usarás.
- Si se requiere una guía de estilo: lee references/estilo.md.

## Salida
Entrega una tabla: ubicación, problema, propuesta y prioridad.

## Verificación
- [ ] Cada hallazgo apunta a un fragmento real.
- [ ] Las propuestas preservan la intención del autor.
- [ ] Los supuestos quedan visibles.

¿Dónde se encuentran y cómo llegan al agente?

Del catálogo al agente

Estructura del diagrama

SkillsMP skillsmp-nodo
skills.sh skillssh-nodo
Repositorio GitHub github-nodo
Revisar archivos revisar-nodo
Skills CLI o copia instalador-nodo
Carpeta local o global carpetas-nodo
Claude, Codex o Bob agente-nodo
skillsmp-nodo → github-nodo · descubrir
skillssh-nodo → github-nodo · descubrir
github-nodo → revisar-nodo · código
revisar-nodo → instalador-nodo · elegir
instalador-nodo → carpetas-nodo · instalar
carpetas-nodo → agente-nodo · descubrir

Lugar	Qué aporta
SkillsMP	Catálogo para descubrir skills y abrir su origen. No certifica ni instala los skills que indexa.
skills.sh	Directorio del ecosistema y acceso a comandos del instalador Skills CLI.
GitHub	Archivos, historial, licencia y versiones del repositorio fuente.
anthropics/skills	Colección de Anthropic.
openai/skills	Colección de OpenAI.
vercel-labs/agent-skills	Colección de Vercel.
tt-a1i/archify	Skill usado para generar esta guía visual.

También puedes llegar directamente a un repositorio sin pasar por un catálogo. Revisa la licencia, el procedimiento y los scripts antes de instalarlos.⁵⁶⁷

¿Cómo instalar un skill local o globalmente?

Skills CLI es un instalador de terceros. Ejecuta los comandos locales desde la raíz del proyecto; -g cambia el alcance a tu usuario.⁷

1. Ver skills disponibles antes de instalarbash

npx skills add tt-a1i/archify --list

2. Instalación LOCAL para Claude Code, Codex e IBM Bobbash

npx skills add tt-a1i/archify --skill archify --agent claude-code codex bob

3. Instalación GLOBAL para esos agentesbash

npx skills add tt-a1i/archify --skill archify --agent claude-code codex bob -g

Opción	Efecto
Sin `-g`	Disponible en el proyecto donde ejecutas el comando.
`-g` o `--global`	Disponible para tu usuario en varios proyectos de esa máquina.
`--skill archify`	Selecciona un skill del repositorio.
`--agent codex`	Elige el agente de destino. Admite varios agentes.
`--copy`	Crea copias en lugar de enlaces simbólicos.
`-y`	Omite los diálogos del instalador; úsalo tras revisar lo que instalarás.

Global significa el alcance del skill para tu usuario. No equivale a npm install -g, ni lo instala para todos los usuarios del equipo. El instalador puede usar una copia compartida y enlaces a las rutas de los agentes.⁷

Consultar, actualizar o retirar skillsbash

npx skills list
npx skills list -g
npx skills check
npx skills update
npx skills remove archify

También puedes crear manualmente la carpeta del skill y guardar allí SKILL.md y sus recursos, usando las rutas de la tabla de agentes.¹²

¿Cómo comprobar que el skill está bien construido?

El nombre identifica una tarea concreta y coincide con la carpeta.
La descripción explica cuándo usarlo y delimita su alcance.
La cabecera YAML contiene name y description.
Cada referencia y script mencionado existe en una ruta relativa.
Las dependencias de los scripts están documentadas.
Se probó con un caso válido, uno incompleto y uno fuera de alcance.
La salida cumple criterios que se pueden comprobar.
El agente encuentra el skill en el alcance local o global esperado.

Un skill orienta el trabajo del agente; los permisos, herramientas y políticas del entorno siguen determinando qué acciones se pueden ejecutar.⁴³