Portada del artículo: Cómo crear skills para agentes de IA: recomendaciones y un ejemplo
Inteligencia Artificial

Cómo crear skills para agentes de IA: recomendaciones y un ejemplo

26 de octubre de 2026Camilo Andrés RodríguezREAD_TIME: 24_MIN

Le explicas a tu agente de IA cómo quieres que revise un artículo, cómo se nombra una rama o qué formato tiene tu informe semanal. Funciona. Al día siguiente empiezas otra sesión y hay que explicarlo todo otra vez. Pegar el mismo texto largo en cada conversación es lento, y dejarlo siempre cargado gasta espacio que el agente necesita para otras cosas.

Las skills resuelven justo eso: guardas el procedimiento una vez, en una carpeta, y el agente lo recupera solo cuando hace falta. Este artículo explica qué son, cuándo elegirlas frente a otras opciones, cómo escribirlas bien y termina con una skill completa que puedes copiar.

Para quién es: para quien ya usa un agente de IA (por ejemplo Claude Code o Codex) y quiere dejar de repetir instrucciones. No hace falta programar para entender los conceptos; el ejemplo final sí incluye un script pequeño.

En corto

  • Una skill es una carpeta con un archivo SKILL.md: un nombre, una descripción y las instrucciones de una tarea. Puede traer scripts y documentos de apoyo.
  • El agente solo lee el nombre y la descripción al empezar; el resto lo carga cuando la tarea coincide. Eso se llama divulgación progresiva.
  • Es un formato abierto (agentskills.io) que Anthropic publicó como estándar en diciembre de 2025 y que usan Claude Code y Codex, entre otras herramientas.
  • Se escribe bien con: descripción clara de qué hace y cuándo usarla, instrucciones breves, scripts para lo mecánico y pruebas con tareas reales.
  • Las skills ejecutan instrucciones y código: instala solo las que vengan de fuentes de confianza.

Qué es una skill

Una skill es una carpeta. Dentro, un archivo obligatorio llamado SKILL.md y, si hace falta, otras carpetas:

nombre-de-la-skill/
├── SKILL.md          # obligatorio: metadatos + instrucciones
├── scripts/          # opcional: código que el agente puede ejecutar
├── references/       # opcional: documentación de apoyo
└── assets/           # opcional: plantillas, imágenes, datos

SKILL.md empieza con un bloque de datos llamado front matter (texto entre dos líneas de ---, en formato YAML) y sigue con las instrucciones en Markdown. El bloque lleva como mínimo dos campos: name y description.

La idea central es cómo se carga. Un agente puede tener decenas de skills instaladas, y si todas ocuparan espacio desde el principio, no quedaría lugar para trabajar. Por eso se cargan por capas:

CapaQué se cargaCuándoTamaño orientativo
1. Descubrimientoname y description de cada skillAl iniciarUnos 100 tokens por skill
2. ActivaciónEl cuerpo completo de SKILL.mdCuando la tarea coincide con la descripciónMenos de 5.000 tokens recomendados
3. EjecuciónScripts, referencias y plantillasSolo si las instrucciones lo pidenSin límite fijo

Cómo leerla: el agente “sabe” que existen todas tus skills por su descripción (una línea o dos), pero solo lee las instrucciones completas de la que necesita. Un token es la unidad en que los modelos cuentan el texto; unos 100 por skill significa que tener muchas instaladas cuesta poco hasta que se usan. Las cifras vienen de la especificación del estándar y son recomendaciones, no un muro técnico.

De dónde viene y quién la usa

Anthropic presentó las Agent Skills el 16 de octubre de 2025 y el 18 de diciembre de 2025 las publicó como estándar abierto, con su especificación en agentskills.io. La documentación de Claude Code indica que sigue ese estándar y le añade extras propios (por ejemplo, controlar si la skill se activa sola o solo cuando la invocas con /nombre). La documentación de Codex, por su parte, describe su soporte de skills como construido sobre el mismo estándar. Una skill bien hecha, por tanto, no queda atada a una sola herramienta, aunque cada una tiene sus propias carpetas y campos opcionales.

Dónde guardarla cambia según la herramienta:

HerramientaSkills personalesSkills del proyecto
Claude Code~/.claude/skills/<nombre>/SKILL.md.claude/skills/<nombre>/SKILL.md
Codex$HOME/.agents/skills.agents/skills en el repositorio

Cómo leerla: las skills personales te acompañan en todos tus proyectos; las del proyecto se versionan junto al código y las comparte todo el equipo. Claude Code detecta skills nuevas o editadas sin reiniciar, salvo que la carpeta de skills de nivel superior se cree después de iniciar la sesión (entonces hace falta /reload-skills).

Skill, tool, MCP o AGENTS.md: cuál elegir

Hay cuatro mecanismos que se parecen y se confunden con facilidad. Cada uno responde a una pregunta distinta:

MecanismoQué esPregunta que responde
Tool (function calling)Una función que el modelo puede pedir que se ejecute; la aplicación la ejecuta y devuelve el resultado“¿Qué puede hacer el agente?”
MCPUn estándar abierto para conectar al agente con herramientas, bases de datos y APIs externas“¿A qué sistemas se conecta?”
AGENTS.md / CLAUDE.mdUn archivo de reglas que el agente lee al empezar cada sesión“¿Qué debe saber siempre de este proyecto?”
SkillUn procedimiento empaquetado que se carga bajo demanda“¿Cómo se hace esta tarea concreta?”

Cómo leerla: una tool o un servidor MCP dan capacidades (consultar una base de datos, leer una API); una skill da método (en qué orden hacerlo, con qué criterios, en qué formato entregarlo). Se combinan: una skill puede indicar cómo usar bien una herramienta MCP. La guía de buenas prácticas de Claude Code resume la frontera entre archivo de reglas y skill: el archivo de reglas se carga en cada sesión, así que debe contener solo lo que aplica siempre; el conocimiento o los flujos que solo importan a veces van en skills, que se cargan bajo demanda.

Una regla práctica para decidir:

  • ¿Aplica a todo el proyecto, siempre? Va al archivo de reglas (por ejemplo “usa este comando para ejecutar los tests”).
  • ¿Es un procedimiento que repites a veces? Es una skill.
  • ¿Necesita acceder a un sistema externo? Necesitas una tool o un servidor MCP; la skill puede acompañarlo.
  • ¿Es algo que debe ocurrir sí o sí en cada ocasión? Un archivo de instrucciones es solo una indicación; para algo obligatorio, la documentación de Claude Code recomienda los hooks, que son deterministas.

Si quieres profundizar en los archivos de reglas y en cómo escribir instrucciones, está la guía práctica de ingeniería de prompts, y para el uso con APIs y modelos locales, el artículo avanzado.

El archivo SKILL.md, campo por campo

La especificación define estos campos en el front matter:

Campo¿Obligatorio?Reglas
nameSíDe 1 a 64 caracteres. Solo letras minúsculas, números y guiones. No puede empezar ni terminar en guion, ni llevar dos guiones seguidos. Debe coincidir con el nombre de la carpeta.
descriptionSíDe 1 a 1.024 caracteres. Debe decir qué hace la skill y cuándo usarla.
licenseNoNombre de la licencia o archivo que la contiene.
compatibilityNoHasta 500 caracteres. Requisitos del entorno (programas, red, producto).
metadataNoPares clave-valor para datos propios (autor, versión).
allowed-toolsNoHerramientas preaprobadas. Es experimental y no todos los agentes lo soportan.

Cómo leerla: solo dos campos son obligatorios. El name es un identificador, no un título bonito: sin mayúsculas ni espacios. Además de la especificación, la documentación de Anthropic para su plataforma añade que el nombre no puede contener las palabras reservadas “anthropic” o “claude” ni etiquetas XML. Claude Code admite más campos opcionales propios (como disable-model-invocation, que impide que Claude cargue la skill por su cuenta) y ignora sin error los que no conoce; fuera de Claude Code, por ejemplo al subir una skill a claude.ai, solo se aceptan los seis campos del estándar y cualquier otro provoca un error.

El cuerpo no tiene formato obligatorio. La especificación recomienda incluir pasos, ejemplos de entrada y salida, y casos límite, y mantener SKILL.md por debajo de 500 líneas, moviendo el detalle a archivos aparte.

Recomendaciones para escribir buenas skills

Estas recomendaciones salen de las guías oficiales de agentskills.io y de Anthropic; cada una apunta al mismo objetivo: que el agente active la skill cuando toca y la siga bien.

1. Parte de un conocimiento real, no de un texto genérico

Pedirle a una IA “hazme una skill de revisión de código” sin darle nada tuyo produce procedimientos vagos del tipo “maneja los errores adecuadamente”. La guía de agentskills.io recomienda extraer la skill de una tarea real: haz la tarea con el agente, anota qué pasos funcionaron, qué correcciones hiciste y qué formato tenían los datos, y recién entonces conviértelo en skill. También sirve alimentar la creación con material propio: guías de estilo, comentarios de revisiones, el historial de cambios de un repositorio.

2. Escribe solo lo que el agente no sabe

Cada línea de la skill compite por espacio con la conversación. La pregunta de las guías oficiales es: “¿el agente se equivocaría sin esta instrucción?”. Si no, sobra. No hace falta explicar qué es un PDF ni cómo funciona HTTP; sí hace falta decir qué convenciones usa tu equipo, qué herramienta usar y cuáles son los errores típicos.

3. La descripción lo decide todo

La descripción es lo único que el agente ve antes de decidir si carga la skill. Debe cubrir dos cosas: qué hace y cuándo usarla, con las palabras que usaría una persona real al pedirlo.

DescripciónProblema
Ayuda con documentosVaga: el agente no sabe cuándo aplicarla
Revisa los básicos de SEO de un artículo de blog en Markdown (...). Úsala cuando el usuario pida revisar, auditar o dejar listo para publicar un post, aunque no mencione "SEO".Dice qué hace, cuándo y cubre peticiones que no nombran el tema

Cómo leerla: la segunda opción incluye el contexto de uso. Las guías recomiendan ser algo “insistente” y listar situaciones donde la skill aplica aunque el usuario no use la palabra técnica. Hay dos matices a la hora de redactarla: la guía de Anthropic recomienda escribirla en tercera persona (“Procesa archivos Excel”) porque se inyecta en el prompt del sistema, mientras que agentskills.io propone un tono imperativo (“Usa esta skill cuando…”). Mezclar ambos, como en el ejemplo de abajo, es razonable. Y en Claude Code la descripción se corta a 1.536 caracteres en el listado, así que lo importante va primero.

Conviene saber además que los agentes tienden a consultar skills para tareas que superan lo que ya saben hacer solos. Una petición trivial de un solo paso puede no activar la skill aunque la descripción coincida.

4. Elige bien el nombre y el tamaño

Anthropic recomienda nombres en gerundio que describan la actividad (processing-pdfs, reviewing-code) y evitar nombres vagos como helper o utils. En cuanto al alcance, la guía de agentskills.io lo compara con una función: una skill debe cubrir una unidad de trabajo coherente. Demasiado estrecha, y hay que cargar varias para una tarea; demasiado amplia, y cuesta que se active con precisión.

5. Da libertad donde se puede y rigidez donde duele

Ajusta cuánto controlas según lo frágil que sea la tarea. Si hay varias formas válidas (una revisión de código), explica el criterio y deja decidir al agente. Si un error es costoso (una migración de base de datos), da el comando exacto y prohíbe modificarlo. Y ofrece una opción por defecto, no un menú: “usa X; si el archivo está escaneado, usa Y” funciona mejor que “puedes usar X, Y, Z o W”.

6. Lo mecánico, en un script

Si una parte debe salir siempre igual (contar caracteres, validar un formato, convertir un archivo), un script es más fiable que pedirle al agente que lo calcule. La documentación de Anthropic apunta que los scripts ahorran tokens, porque solo el resultado entra al contexto, no el código. Dos cuidados: deja claro en SKILL.md si el agente debe ejecutar el script o leerlo, y haz que los mensajes de error sean específicos para que el agente pueda corregirse solo.

7. Usa plantillas, ejemplos y una sección de “gotchas”

Cuando necesitas un formato de salida, una plantilla concreta funciona mejor que describirlo con palabras, porque los agentes copian bien las estructuras. Y la sección más valiosa suele ser una lista de gotchas: hechos del entorno que contradicen lo que se asumiría (“la tabla users usa borrado lógico, filtra siempre por deleted_at IS NULL”). Cada vez que tengas que corregir al agente por el mismo error, añade esa corrección ahí.

8. Que el agente verifique su trabajo

Los patrones de validación (hacer el trabajo, ejecutar un comprobador, corregir y repetir hasta que pase) mejoran la calidad. Para operaciones por lotes o destructivas, ambas guías proponen “planificar, validar, ejecutar”: primero un plan en un archivo, luego un script que lo comprueba contra la fuente de verdad y solo entonces la ejecución.

9. Estructura con capas y mantén las referencias cortas

Si SKILL.md crece, mueve el detalle a references/ y dile al agente cuándo leer cada archivo (“lee references/errores.md si la API devuelve un código distinto de 200”). Mantén las referencias a un solo nivel de profundidad desde SKILL.md: la guía de Anthropic advierte de que, cuando un archivo enlaza a otro, el agente puede leerlo solo en parte. Evita también información que caduca (“antes de agosto de 2025 usa X”) y usa siempre los mismos términos para lo mismo.

10. Pruébala con tareas reales y varios modelos

La guía de Anthropic recomienda crear evaluaciones antes de escribir documentación extensa: ejecutar tareas representativas sin la skill, anotar dónde falla el agente, escribir lo mínimo para corregirlo y comparar. Aconseja un mínimo de tres evaluaciones y probar con los modelos que vayas a usar (uno pequeño puede necesitar más detalle que uno grande). Para la activación, agentskills.io propone unas 20 consultas de prueba (8 a 10 que deban activar la skill y 8 a 10 que no, preferiblemente casos parecidos pero distintos), ejecutar cada una unas 3 veces porque el comportamiento varía, y reservar cerca del 40 % como conjunto de validación para no ajustar la descripción solo a los ejemplos que ya viste.

11. Trátala como código que ejecuta cosas

Una skill puede incluir scripts y dar instrucciones que el agente sigue. Anthropic recomienda instalar skills solo de fuentes de confianza, revisar antes las de origen dudoso (sobre todo scripts e instrucciones que apunten a conectarse a sitios externos) porque una skill maliciosa podría introducir vulnerabilidades o exfiltrar datos.

Un ejemplo completo: reviewing-post-seo

Para ver todo junto, esta es una skill pequeña y útil: revisa los básicos de SEO de un artículo de blog escrito en Markdown. Un script mide lo que se puede medir (longitudes, formato del slug, saltos de encabezados, imágenes sin texto alternativo) y las instrucciones indican al agente cómo presentar el resultado.

Se eligió esta skill porque cumple con lo que pide el estándar y con las recomendaciones anteriores: es un procedimiento repetible, una parte es mecánica (script) y otra requiere criterio (explicar y proponer correcciones).

La estructura

reviewing-post-seo/
├── SKILL.md
├── references/
│   └── umbrales.md
└── scripts/
    └── check_post.py

El nombre de la carpeta coincide con el campo name, como exige la especificación. Es una skill de tres archivos: instrucciones breves en SKILL.md, los motivos de cada umbral en references/umbrales.md (se lee solo si hay que cambiarlos) y el cálculo en scripts/check_post.py.

SKILL.md

---
name: reviewing-post-seo
description: Revisa los básicos de SEO de un artículo de blog en Markdown (título, descripción, slug, encabezados, imágenes y enlaces) y devuelve un informe con errores y avisos. Úsala cuando el usuario pida revisar, auditar o dejar listo para publicar un post, aunque no mencione "SEO".
license: MIT
metadata:
  version: "1.0"
---

# Revisión SEO básica de un post

## Pasos

1. Localiza el archivo `.md` del post. Si el usuario no lo indica, pregunta cuál es.
2. Ejecuta el script con la ruta del archivo:

   ```bash
   python3 scripts/check_post.py ruta/al/post.md
   ```

3. Lee el informe. Cada línea empieza por `ERROR` (hay que corregirlo) o `AVISO` (conviene revisarlo).
4. Resume al usuario los hallazgos, del más grave al menos grave, y propone una corrección concreta para cada uno. No reescribas el post si no te lo piden.
5. Si el script termina con código 2, el archivo no se pudo leer o no tiene front matter: díselo al usuario y no inventes un informe.

## Reglas

- Los umbrales (60 caracteres de título, 70 a 160 de descripción) son convenciones editoriales, no reglas de Google. Si el usuario usa otros, edita `references/umbrales.md` y las constantes del script.
- El script solo revisa lo que se puede medir. No juzgues la calidad del contenido ni la intención de búsqueda salvo que te lo pidan.
- No modifiques el archivo del post durante la revisión.

## Más detalle

Para saber por qué existe cada regla y cómo cambiarla, lee `references/umbrales.md`.

Observa cómo aplica las recomendaciones: la descripción dice qué hace y cuándo usarla (incluso si el usuario no dice “SEO”); los pasos son cortos y numerados; la tarea frágil (medir) la hace un script, mientras que el resumen para la persona queda a criterio del agente; y hay una regla explícita sobre qué hacer cuando el script falla, para que el agente no invente un informe.

references/umbrales.md

# Umbrales del informe

| Comprobación | Nivel | Regla por defecto | Motivo |
| --- | --- | --- | --- |
| Título presente | ERROR | `title` no vacío | Sin título no hay enlace en los resultados |
| Título largo | AVISO | más de 60 caracteres | Google lo acorta si no cabe; no hay un límite oficial |
| Descripción presente | ERROR | `description` no vacía | Sin ella el buscador improvisa el fragmento |
| Descripción corta o larga | AVISO | menos de 70 o más de 160 caracteres | Convención editorial para que el fragmento se lea completo |
| Slug válido | ERROR | solo minúsculas, números y guiones | URLs limpias y estables |
| Encabezado H1 en el cuerpo | AVISO | no debería haber `# ` | La plantilla ya pinta el título como H1 |
| Saltos de nivel | AVISO | un H2 no puede saltar a H4 | Estructura legible para lectores y buscadores |
| Imágenes sin alt | ERROR | `![](...)` con texto alternativo vacío | Accesibilidad y contexto de la imagen |
| Enlaces internos | AVISO | al menos uno que empiece por `/` | Ayuda a descubrir otras páginas del sitio |

Para cambiar un umbral, edita las constantes al inicio de `scripts/check_post.py`.

Cómo leerla: la tabla explica el motivo de cada comprobación y su gravedad. Los límites de 60 caracteres para el título y de 70 a 160 para la descripción son una convención editorial, no una regla de Google: la documentación de Google indica que no hay un límite de longitud para el título ni para la meta descripción, y que el resultado se acorta en la búsqueda según el ancho del dispositivo. Por eso el script los trata como avisos y no como errores.

scripts/check_post.py

#!/usr/bin/env python3
"""Revisa los básicos de SEO de un post en Markdown con front matter YAML.

Uso: python3 check_post.py ruta/al/post.md
Códigos de salida: 0 sin errores, 1 con errores, 2 archivo ilegible o sin front matter.
"""
import re
import sys
from pathlib import Path

TITLE_MAX = 60  # convención editorial: Google acorta lo que no cabe, no hay límite oficial
DESC_MIN, DESC_MAX = 70, 160  # convención editorial, ver references/umbrales.md
SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")


def split_front_matter(text):
    """Devuelve (front matter, cuerpo, línea del archivo donde empieza el cuerpo)."""
    match = re.match(r"^---\n(.*?)\n---\n(.*)$", text, re.DOTALL)
    if not match:
        return None, text, 1
    return match.group(1), match.group(2), match.group(1).count("\n") + 4


def read_field(front, key):
    # Solo valores de una línea, con comillas dobles, simples o sin comillas.
    match = re.search(rf"""^{key}:\s*["']?(.*?)["']?\s*$""", front, re.MULTILINE)
    return match.group(1).strip() if match else ""


def check(front, body, first_line=1):
    findings = []
    title = read_field(front, "title")
    desc = read_field(front, "description")
    slug = read_field(front, "slug")

    if not title:
        findings.append(("ERROR", "Falta el título (title)."))
    elif len(title) > TITLE_MAX:
        findings.append(("AVISO", f"Título de {len(title)} caracteres (máx. recomendado {TITLE_MAX})."))

    if not desc:
        findings.append(("ERROR", "Falta la descripción (description)."))
    elif not DESC_MIN <= len(desc) <= DESC_MAX:
        findings.append(("AVISO", f"Descripción de {len(desc)} caracteres (rango recomendado {DESC_MIN}-{DESC_MAX})."))

    if slug and not SLUG_RE.match(slug):
        findings.append(("ERROR", f"Slug no válido: '{slug}' (usa minúsculas, números y guiones)."))

    fence = None  # marcador del bloque de código abierto (``` o ~~~)
    last_level = 1
    has_internal_link = False
    for number, line in enumerate(body.splitlines(), start=first_line):
        marker = re.match(r"\s{0,3}(`{3,}|~{3,})", line)
        if marker:
            mark = marker.group(1)
            if fence is None:
                fence = mark
                continue
            if mark[0] == fence[0] and len(mark) >= len(fence):
                fence = None
                continue
        if fence:
            continue
        heading = re.match(r"^(#{1,6})\s+\S", line)
        if heading:
            level = len(heading.group(1))
            if level == 1:
                findings.append(("AVISO", f"Línea {number}: hay un H1 en el cuerpo; la plantilla ya usa el título."))
            elif level > last_level + 1:
                findings.append(("AVISO", f"Línea {number}: salto de H{last_level} a H{level}."))
            last_level = level
        if re.search(r"!\[\s*\]\(", line):
            findings.append(("ERROR", f"Línea {number}: imagen sin texto alternativo."))
        if re.search(r"\]\(/[^)]*\)", line):
            has_internal_link = True

    if not has_internal_link:
        findings.append(("AVISO", "No hay ningún enlace interno (que empiece por '/')."))
    return findings


def main():
    if len(sys.argv) != 2:
        print("Uso: python3 check_post.py ruta/al/post.md", file=sys.stderr)
        return 2
    path = Path(sys.argv[1])
    try:
        text = path.read_text(encoding="utf-8")
    except OSError as error:
        print(f"No se pudo leer {path}: {error}", file=sys.stderr)
        return 2
    front, body, first_line = split_front_matter(text)
    if front is None:
        print(f"{path} no tiene front matter entre líneas '---'.", file=sys.stderr)
        return 2

    findings = check(front, body, first_line)
    for level, message in findings:
        print(f"{level}: {message}")
    errors = sum(1 for level, _ in findings if level == "ERROR")
    print(f"Resumen: {errors} errores, {len(findings) - errors} avisos.")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main())

El script solo usa la biblioteca estándar de Python 3, así que no hay nada que instalar. Termina con código 0 si no hay errores, 1 si los hay y 2 si el archivo no se puede leer o no tiene front matter, y el agente puede reaccionar a cada caso.

Cómo se comprobó

Se hicieron tres comprobaciones, con resultados reales:

1. Validación de la estructura con skills-ref, la biblioteca de referencia del estándar:

skills-ref validate reviewing-post-seo
Valid skill: reviewing-post-seo

Esta herramienta verifica que el front matter sea válido y siga las reglas de nombres. La descripción de este ejemplo mide 274 caracteres (el máximo es 1.024) y SKILL.md tiene 32 líneas (el límite recomendado es 500).

2. Ejecución del script sobre un texto con fallos a propósito: un post de prueba con un título largo, una descripción corta, un slug con mayúsculas y guion bajo, un H1 en el cuerpo, un salto de H1 a H4 y una imagen sin texto alternativo:

python3 scripts/check_post.py sample-post.md
AVISO: Título de 67 caracteres (máx. recomendado 60).
AVISO: Descripción de 24 caracteres (rango recomendado 70-160).
ERROR: Slug no válido: 'Cafetera_Oficina' (usa minúsculas, números y guiones).
AVISO: Línea 7: hay un H1 en el cuerpo; la plantilla ya usa el título.
AVISO: Línea 11: salto de H1 a H4.
ERROR: Línea 13: imagen sin texto alternativo.
Resumen: 2 errores, 4 avisos.

El código de salida fue 1, porque hay errores.

3. Ejecución sobre un artículo real de este mismo sitio, la guía práctica de ingeniería de prompts:

AVISO: Título de 66 caracteres (máx. recomendado 60).
AVISO: Descripción de 163 caracteres (rango recomendado 70-160).
Resumen: 0 errores, 2 avisos.

Código de salida 0. Los avisos son legítimos según las reglas de la skill y sirven de ejemplo de lo que el agente resumiría y propondría corregir (acortar el título y recortar unos caracteres de la descripción).

Qué no se midió: que un agente concreto active la skill por sí solo con ciertas frases. Esa prueba requiere el protocolo de consultas de la recomendación 10 y depende de la herramienta y el modelo que uses, así que conviene hacerla en tu entorno antes de confiar en ella.

Cómo instalarla y probarla

  1. Copia la carpeta reviewing-post-seo a ~/.claude/skills/ (Claude Code, personal) o a .claude/skills/ de tu proyecto. En Codex, la ubicación equivalente es $HOME/.agents/skills o .agents/skills.
  2. Abre una sesión nueva y pide algo como “revisa este post antes de publicarlo: ruta/al/post.md”.
  3. Comprueba en el historial de la herramienta si el agente cargó la skill y ejecutó el script. Si no lo hizo, el primer sospechoso es la description.
  4. Adapta los umbrales y el idioma a tu caso editando references/umbrales.md y las constantes del script.

¿Y si usas un modelo por API en tu propia aplicación?

Las skills no son exclusivas de herramientas como Claude Code o Codex. Una skill es una carpeta con archivos de texto; lo que hacen esas herramientas es encontrarla y entregársela al modelo en el momento adecuado. Si desarrollas tu propia aplicación sobre un modelo por API, tienes dos caminos.

1. Usar el soporte de la API de Claude. La API de Claude admite skills de forma directa: subes la skill con los endpoints /v1/skills y la indicas por su skill_id en el parámetro container de la petición, junto con la herramienta de ejecución de código. Tiene límites claros: se ejecuta en un contenedor aislado sin acceso a internet y sin poder instalar paquetes durante la ejecución (solo están los que ya vienen preinstalados). Las skills subidas por API se comparten con todo el espacio de trabajo.

2. Implementarlo tú, con cualquier modelo. La documentación del estándar incluye una guía para añadir soporte de skills a tu propio agente. El esquema es el mismo de la divulgación progresiva, pero lo programas tú:

  1. Descubrir. Al arrancar, la aplicación busca carpetas con un SKILL.md y lee solo name y description.
  2. Catálogo. Esos nombres y descripciones van en el system prompt (unos 50-100 tokens por skill), con una instrucción breve del tipo “si la tarea coincide con una skill, cárgala antes de seguir”.
  3. Activar. Le das al modelo una herramienta, por ejemplo activate_skill(name), que devuelve el cuerpo de SKILL.md. La guía recomienda limitar el parámetro name a los nombres que existen, para que el modelo no invente skills.
  4. Recursos. Si las instrucciones mencionan archivos de references/ o scripts/, el modelo los pide cuando los necesita. Para ejecutar scripts, tu aplicación tiene que darle un entorno donde hacerlo; si no, solo aprovechas las instrucciones de texto.

Este segundo camino funciona con cualquier modelo que soporte tool calling, no solo con Claude. La guía añade dos consejos útiles si tu aplicación resume o recorta conversaciones largas: no borrar las instrucciones de una skill ya cargada (el modelo seguiría trabajando sin ellas y sin avisar) y no cargar dos veces la misma skill.

Errores comunes

  • Descripción vaga. Si no dice cuándo usarla, no se activará cuando la necesites.
  • Skill enciclopedia. Explicar lo que el agente ya sabe gasta contexto y puede distraerlo. Las guías indican que una skill concisa con un ejemplo funcional suele rendir más que una documentación exhaustiva.
  • Demasiadas opciones. Un menú sin valor por defecto confunde.
  • Nada que verificar. Sin script, lista de comprobación o plantilla, el resultado depende solo de la suerte.
  • Rutas con barras invertidas. Anthropic recomienda barras normales (scripts/helper.py) incluso en Windows; las otras fallan en sistemas Unix.
  • Instalar skills sin mirarlas. Son instrucciones y código que se ejecutan en tu equipo.

Tu primer paso

Piensa en la última tarea que le explicaste a un agente dos veces. Haz esa tarea una vez más, pero esta vez guarda tus correcciones: qué paso funcionó, qué tuviste que repetirle, qué formato esperabas. Con eso en la mano, crea una carpeta con un SKILL.md de unas 20 líneas: un name con minúsculas y guiones, una description que diga qué hace y cuándo usarla, y los pasos. Valídala con skills-ref validate y pruébala con tres peticiones reales. El resto (scripts, referencias, más pruebas) se añade cuando la práctica lo pida.

Fuentes

Consultadas el 26 de octubre de 2026.

Etiquetas#Skills#Agent Skills#SKILL.md#Agentes de IA#Claude Code#Codex#AGENTS.md#MCP#Inteligencia Artificial
RUTA DE LECTURA RECOMENDADA

Más allá del código: estrategia, escalabilidad e impacto

Lecturas clave para conectar la arquitectura técnica con el valor de negocio y rentabilidad.

EXPLORAR CATEGORÍA COMPLETA→