Skills para agentes de IA: SKILL.md, no un prompt eterno

Si pegas el mismo checklist en cada chat, no tienes un agente: tienes un copy-paste. Un skill es ese procedimiento empaquetado en un archivo (SKILL.md) que el modelo carga solo cuando aplica. No es un system prompt más largo. No es CLAUDE.md. Anthropic lo documenta como capacidad modular: instrucciones + metadata + recursos opcionales (scripts, plantillas), con carga progresiva.

Esta guía cubre el contrato oficial de Agent Skills (API/Claude.ai) y de Claude Code, cuándo crear uno y cómo no convertir el repo en 40 skills muertos. Fuentes verificadas el 3 de septiembre de 2026.

Si todavía no tienes un cerebro corto y estable, empieza por system prompts para agentes. El skill no sustituye el rol; lo especializa.

Prompt vs CLAUDE.md vs skill

	Vive en	Se carga	Para qué
System prompt	Cada request	Siempre	Rol, límites, formato
CLAUDE.md / AGENTS.md	Repo, contexto del coding agent	Casi siempre (hechos del proyecto)	“usamos pnpm”, “nunca push a main”
Skill (SKILL.md)	Filesystem / API	Metadata siempre; el cuerpo on demand	Procedimiento: cómo extraer un PDF, cómo hacer un deploy, cómo armar un PR

Claude Code lo dice claro: crea un skill cuando sigues pegando las mismas instrucciones, o cuando una sección de CLAUDE.md creció a procedimiento en vez de hecho. El cuerpo del skill no entra al contexto hasta que se usa; el material largo casi no cuesta hasta ese momento.

Un system prompt de 4.000 palabras “por si acaso” es context rot con extra steps. El skill es la vía de escape.

Progressive disclosure (el truco que importa)

Anthropic documenta tres niveles:

1. Metadata (siempre). YAML frontmatter: name + description. Claude lo mete al system prompt al arrancar. La description es lo que dispara el skill: tiene que decir qué hace y cuándo usarlo.
2. Cuerpo (SKILL.md). Procedimientos, ejemplos, “quick start”. Claude lo lee del filesystem (vía bash en el diseño documentado) cuando el request matchea la description. Recién ahí entra al contexto.
3. Recursos extra. FORMS.md, scripts, templates. Se cargan si el cuerpo los apunta. No al inicio.

Eso es lo contrario de un prompt gordo: el modelo ve un índice corto y abre el capítulo justo.

Frontmatter mínimo (docs de Anthropic):

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

Si la description dice solo “PDF tools”, el modelo no sabe cuándo abrirlo. Si dice el trigger (“when the user mentions PDFs, forms…”), deja de adivinar.

Claude Code: /nombre y el estándar

En Claude Code, un skill es un SKILL.md. Claude lo usa cuando aplica, o lo invocas con /skill-name. Los custom commands se fusionaron en skills: .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md ambos crean /deploy. Los commands viejos siguen; los skills suman carpeta de archivos, frontmatter de quién invoca (tú vs el modelo) y carga automática.

Claude Code sigue el estándar abierto Agent Skills y añade extras (control de invocación, subagent, context injection). Si escribes el skill para un solo IDE, estás dejando compatibilidad en la mesa.

disable-model-invocation: true (o override en settings) = solo el humano con /nombre. Úsalo para deploys y cualquier procedimiento que no quieres que el modelo dispare solo.

Anatomía mínima que sí se usa

Un skill útil cabe en una pantalla:

1. Frontmatter con trigger explícito.
2. Quick start de 10–20 líneas (el 80 % de los usos).
3. Un “si falla, haz X” — no un tratado.
4. Links a archivos extra solo para el 20 % raro (FORMS.md, un script).
5. Nada de secretos. El skill se commitea.

Anti-patrones:

• Skill que duplica CLAUDE.md (“este repo usa TypeScript”). Eso es un hecho, no un procedimiento.
• Skill de 2.000 líneas “completo”. El modelo no lo va a seguir; parte en quick start + extras.
• Description vaga (“utilidades internas”). Nunca dispara, o dispara siempre.
• 30 skills el primer día. Empieza con uno que ya pegas tres veces por semana.

Skills no son tools

Una tool / function calling hace algo (HTTP, SQL, filesystem). Un skill explica cómo usar tools, convenciones y pasos. El skill de PDF de Anthropic enseña a usar pdfplumber; no es el binario.

Si el agente necesita un botón, haz una tool. Si necesita un recetario, haz un skill. Mezclarlos (“la tool run ejecuta el markdown”) es cómo vuelves al prompt injection con extra filesystem. Ver defensas de injection: un skill en el repo es texto que el modelo lee; no es un permission layer.

Checklist

• Description = qué + cuándo. Si no hay “use when…”, reescribe.
• Cuerpo < ~150 líneas; el resto en archivos enlazados.
• Un skill por intención, no un “kitchen sink”.
• Procedimientos peligrosos con invocación solo humana.
• Sin secretos, sin PII, sin “copia esta API key”.
• Probado: un request que debe dispararlo y uno que no.
• Si vive en Claude Code, ruta .claude/skills/<nombre>/SKILL.md (o el equivalente del estándar).
• CLAUDE.md se quedó en hechos; el procedimiento se mudó al skill.

FAQ

¿Puedo usar skills fuera de Claude? El estándar agentskills.io está pensado para varios tools. El runtime tiene que implementar la carga. Sin eso, es un markdown más.

¿Skill vs MCP? MCP expone herramientas y datos. El skill enseña el workflow encima. Suelen ir juntos: MCP para el API, skill para “cómo hacemos un deploy aquí”.

¿Cuántos skills? Los que ya pegas. Cero skills inventados “por si el agente los necesita”.

¿El modelo ignora el skill? Casi siempre es la description. Afina el trigger; no alargues el cuerpo.

Empieza por el procedimiento que hoy está en un gist o en un mensaje de Slack. Un SKILL.md de 40 líneas gana a un system prompt de 400.