La Línea Más Importante de tu Claude Skill es la Descripción de Tres Frases que Casi Nadie Escribe con Cuidado
No es documentación. Es la query string de un sistema de recuperación que decide si tu skill se usa alguna vez.
Claude no carga tu skill porque esté en la carpeta. La carga solo cuando la descripción coincide con la tarea del usuario. Escribes una descripción vaga, y tu skill es un zombi: existe, pesa cero en el contexto, pero jamás se dispara.
Y los equipos que copian sus system prompts en un SKILL.md van a ver cero beneficio y van a concluir que la feature no funciona.
Casi nadie lo analiza así, así que vamos a destriparlo: *el fichero SKILL.md es la parte menos importante de la skill*. El valor real vive en tres capas que nadie menciona.
---
No es un Prompt de Sistema con Carpeta. Es un Sistema de Recuperación
El argumento que oyes en cada oficina: "¿Para qué complicarme? Lo hago con un prompt de sistema personalizado."
Ahí está el error conceptual.
Un prompt de sistema está siempre en contexto. Cada instrucción que añades paga token en cada llamada, compite con la tarea real del modelo y degrada la calidad cuando acumulas contenido. Con 50 system prompts encima, tienes un agente lento, caro y confuso.
La skill invierte ese tradeoff.
Puedes tener 50 skills para 50 dominios y pagar coste base cero, porque solo entra en contexto la que coincide. Eso convierte a las skills en una primitiva de escalado, no en un detalle de formateo.
Es la diferencia entre un bundle de prompts de 200KB y un agente limpio que tira de conocimiento experto exactamente cuando lo necesita.
Mirad el formato real. Una skill es una carpeta con un SKILL.md que tiene frontmatter YAML y un cuerpo en Markdown:
```markdown
---
name: normalizador-csv
description: >
Usa cuando el usuario pida fusionar, limpiar, convertir o reformatear
datos CSV, hojas de cálculo o ficheros exportados desde Excel o Google
Sheets. También si pega una tabla con columnas inconsistentes o fechas
en formatos mixtos.
---
Normalizador CSV
Normaliza ficheros CSV a un esquema consistente:
Columna `id` siempre primera.
Fechas en ISO 8601 (YYYY-MM-DD).
Eliminar filas duplicadas.
Solo conservar las columnas definidas en `schemas/template.json`.
```
Fijaos en la descripción. No es un resumen de producto. Es un índice de intenciones de usuario. Dice en qué situaciones dispararse, qué frases la activan y qué tipo de inputs acepta.
Eso no lo escribe casi nadie. Y es la diferencia entre una skill que funciona y una skill invisible.
---
Las Skills-Versus-MCP: Donde la Arquitectura de Casi Todos se Va al Carajo
Desde el anuncio, la reacción en dos bandos:
❌ "Es un prompt de sistema con pasos extra"
❌ "Necesito montar un servidor MCP para cada capacidad"
Ambas están mal.
Los servidores MCP son para integraciones con estado, externas, del lado del servidor: bases de datos vivas, APIs de terceros, herramientas que mantienen sesiones.
Las skills son para capacidad *stateless* y autocontenida: transformación de ficheros, formateo específico de dominio, heurísticas empaquetadas.
Los ejemplos oficiales de Anthropic — decodificar un QR y convertir PDF a Markdown — son problemas de script-en-una-carpeta. Y aun así, los equipos montan un servidor MCP completo para cada uno, pagando infraestructura y mantenimiento por algo que resuelve una carpeta versionada.
El test es brutalmente simple: ¿la capacidad necesita estado compartido o un server-side runtime? Si la respuesta es no, es una skill.
Aquí está el patrón de paquete de capacidad: texto que instruye + asset que ejecuta.
```markdown
---
name: extraer-metadatos-imagen
description: >
Usa cuando el usuario pida extraer metadatos de imágenes (EXIF, GPS,
fecha de captura, cámara) o ordenar una carpeta de fotos por estos datos.
---
Extracción de Metadatos
Ejecuta el script incluido con el fichero a analizar:
```
python scripts/extract_exif.py <ruta-al-fichero>
```
Muestra solo: fecha, cámara, coordenadas GPS si existen.
Si no existe el script, pídele al usuario que lo reinstale.
```
Y en la carpeta, junto al SKILL.md:
```python
scripts/extract_exif.py
import sys
from PIL import Image
from PIL.ExifTags import TAGS, GPSTAGS
def main(path):
img = Image.open(path)
exif = img._getexif() or {}
data = {}
for tag_id, value in exif.items():
tag = TAGS.get(tag_id, tag_id)
if tag == "GPSInfo":
data["gps"] = {GPSTAGS.get(k, k): v for k, v in value.items()}
else:
data[tag] = value
print({k: v for k, v in data.items()
if k in ("DateTime", "Model", "Make", "gps")})
if __name__ == "__main__":
main(sys.argv[1])
```
Una skill que solo contiene prosa es una skill a medias. El asset empaquetado es lo que la convierte en capacidad, no en sugerencia.
---
El Patrón de las 3 Capas del Paquete de Capacidad
Tras construir varias en producción, este es el marco que funciona. No es teoría: es el orden en que escribo cada skill nueva.
1. Encuentra las 3–5 tareas que tu equipo repite y que el modelo base hace mal
No busques demos impresionantes. Busca el trabajo real repetido a diario: "formatear nuestros partes de incidencias" o "convertir los PDF de proveedores a markdown". Esas, no las demostraciones, son los candidatos reales.
2. Crea la estructura de carpeta y escribe la descripción AL FINAL
Crea `.claude/skills/<nombre-de-skill>/SKILL.md`. Escribe primero el cuerpo. Luego la descripción, como una búsqueda: enumera frases disparadoras, intenciones de usuario y tipos de input para que la capa de recuperación pueda hacer match.
Si la skill nunca se dispara, el bug es la descripción. Si se dispara pero hace algo incorrecto, el bug es el cuerpo. Apunta a ambos por separado.
3. Mueve TODO lo ejecutable fuera de la prosa y dentro de assets
Cualquier script, lista de regex, plantilla o ejemplo few-shot va como fichero en la carpeta, referenciado desde el cuerpo. Mantén el cuerpo lo suficientemente corto para que cargue barato.
Mirad la diferencia entre la v1 y la v2 de la misma skill:
❌ v1: un ensayo de 400 palabras de instrucciones sobre cómo normalizar datos, con ejemplos inline, edge cases enterrados en prosa y reglas que el modelo debe recordar.
✅ v2: 60 palabras de cuerpo + un script ejecutable + una plantilla JSON referenciada. El contexto que entra es mínimo. La lógica vive en código testable, no en memoria del modelo.
4. Testea con tareas reales del paso 1, e itera sobre la descripción (no solo las instrucciones)
Si la skill no se dispara, reescribe la descripción como índice de intención de usuario. Trátala como SEO y haz A/B tests. Una skill que nunca se dispara es invisible por muy bueno que sea su cuerpo.
5. Empaqueta y distribuye como código
Haz commit en un repo de git, añade un manifiesto de plugin y trata el SKILL.md como código fuente: code review los cambios, versiona, haz rollback.
Así se ve el empaquetado para distribución:
```json
{
"name": "normalizador-csv",
"version": "1.2.0",
"description": "Normaliza CSV y hojas de cálculo a un esquema consistente.",
"skills": ["./skills/normalizador-csv"]
}
```
Esa capa de distribución es la feature dormida del ecosistema. Convierte la capacidad de un agente en un artefacto de software con versionado, revisión y rollback. Es la misma progresión que vivió el mundo de los package managers con las librerías.
---
Los Assets, no el Prompt, son el Producto
Cuando Anthropic lanzó Agent Skills en octubre de 2025, los ejemplos oficiales no eran prosa elegante. Eran un decodificador QR (script basado en OpenCV) y un conversor de PDF a Markdown (script con Amazon Textract).
*Un skill es un mini-paquete de capacidad: instrucciones + assets ejecutables. * No una plantilla.
La consecuencia práctica: el acto de escribir un SKILL.md fuerza a tu equipo a externalizar conocimiento tribal que vive en cabezas de seniors y hilos de Slack. "Aquí está exactamente cómo normalizamos los datos de cliente." Ese valor documentado compone antes de que la automatización sea perfecta.
Y es revisable, diffable y responsable de una forma que un prompt de sistema de pared de texto jamás será.
---
Cómo Responder a las Objeciones
"Es un prompt de sistema en una carpeta."
Un prompt de sistema está siempre en contexto y paga token en cada llamada. No puede empaquetar assets ejecutables. No se versiona ni se distribuye limpio. La carga bajo demanda, el empaquetado de assets y el distributable son el producto real.
"Las skills son poco fiables, no disparan la mía."
Eso es casi siempre un fallo de recuperación por la descripción, no del modelo. La solución es reescribir la descripción como un índice de intención de usuario y testearla. La fiabilidad es disciplina de diseño, no un regalo.
"Esto me ata a Claude y Claude Code."
El formato SKILL.md es Markdown plano + YAML, y los assets son ficheros ordinarios. El artefacto es portable; el conocimiento sobrevive aunque cambie el runtime. Lo que se ata es el comportamiento de recuperación, no el contenido. Sé honesto: el marketplace y el ecosistema son específicos de Claude, pero el formato no es profundamente propietario.
---
El Futuro del "Prompt Engineering" es Mantenimiento de Software
Los equipos que adopten este workflow pronto están construyendo activos organizacionales reutilizables, no automatizaciones de usar y tirar.
La diferencia entre escalar con 50 skills bien descritas y versionadas, o ahogarse con un system prompt monolítico de 200KB, es la misma que separa a un equipo que mantiene librerías de uno que copia código en Slack. Construye el activo. La descripción conviértela en query string, los assets en código, y la distribución en tu estándar de calidad.
Porque el que trata las skills como prompts de sistema ya está pagando el impuesto. Solo que todavía no lo nota.
Lee el artículo completo en brianmenagomez.com
Más sobre mis servicios en brianmenagomez.com
Herramientas: Conversor IAE CNAE · Gestorias cerca de ti · Calculadora IRPF