La Línea Más Importante de tu Claude Skill No es Código — es una Descripción YAML
Vas a escribir probablemente cero líneas de código para tu primer Claude Skill. Y ese es el punto.
Claude no "instala" skills. *Las lee y decide si aplican.* El componente que determina si tu skill se usa nunca es el script que escribas: es la descripción en YAML que Claude lee en tiempo de inferencia y usa para decidir si el skill es relevante para la tarea actual.
Los equipos que construyen skills como si fuesen API tools las verán acumular polvo. Los equipos que las tratan como entradas de índice de búsqueda las verán ejecutarse solas.
El patrón se llama *El Índice de Búsqueda en SKILL.md*: cada skill es una entrada de índice optimizada para que Claude la clasifique correctamente cuando llega la tarea correcta.
---
El Error: Tratáis las Skills Como Código Cuando Son Documentación
La sabiduría convencional dice que los añadidos agénticos son código: plugins, API tools, servidores MCP con esquemas que registras.
Claude Skills invierte esa premisa. Mira lo que es un skill a nivel de fichero:
```markdown
my-skill/SKILL.md
---
name: pr_reviewer
description: Revisa pull requests por seguridad, rendimiento y
legibilidad. Se invoca para revisión de PR, comprobaciones de
merge y hallazgos de lint.
---
Instrucciones: cuando se te pida revisar un PR, sigue estos pasos...
```
Eso es todo. Una carpeta con un `SKILL.md`. Sin código. Sin compilación. Sin registro en ningún sitio.
El routing funciona por lectura: Claude lee la descripción como texto y decide en tiempo de inferencia si el skill aplica a la tarea actual. No registras un esquema de tool. No haces deploy de nada. El skill existe en tu repo, y Claude decide usarlo o ignorarlo.
Esto significa que la artesanía que determina si tu skill se usa nunca es la sofisticación del código. Es la calidad de la documentación: una descripción precisa y rica en keywords, y un cuerpo de instrucciones claro.
Tratar un skill como una librería te da skills que nadie dispara. Tratarlo como una página de conocimiento bien indexada te da skills que se invocan automáticamente.
---
❌ Así NO Se Escribe una Descripción de Skill
```yaml
---
name: web_crawler
description: Handle web crawling
---
```
¿Cuándo va a disparar Claude esto? Una descripción como "Handle web crawling" es tan genérica que compite contra el comportamiento por defecto de Claude y pierde.
El skill de compite contra dos adversarios por cada tarea:
1. Otros skills con descripciones más específicas.
2. El comportamiento por defecto de Claude, que siempre gana si tu descripción no le da razones para saltarse la respuesta genérica.
Una descripción que solapa con una respuesta genérica pierde. Una descripción que nombra verbos de tarea concretos gana.
---
✅ Así Se Escribe: Como un Índice de Búsqueda
```yaml
---
name: pr_reviewer
description: Revisa pull requests por seguridad, rendimiento y
legibilidad. Se invoca para revisión de PR, comprobaciones de
merge, hallazgos de lint, análisis de código comentado y
patrones de fuga de secretos en diffs.
---
```
Fíjate en qué cambió:
Enumera verbos de tarea: "revisa", "analiza", "comprueba".
Enumera escenarios de disparo: "revisión de PR", "comprobaciones de merge", "hallazgos de lint".
Nomina dominios concretos: "seguridad", "rendimiento", "legibilidad", "fuga de secretos".
Esto no es SEO. *Es clasificación.* Claude tiene que decidir en milisegundos si este skill o su respuesta genérica le sirve mejor a tu petición. La descripción es el único input que tiene para decidirlo.
---
Skills y MCP: No Son Rivales. Se Componen
Mucha gente confunde Skills con MCP servers. Son capas complementarias.
MCP conecta Claude a sistemas externos — APIs, bases de datos, servicios de ficheros — con esquemas declarados. Un Skill es un paquete de conocimiento procedimental: instrucciones más scripts opcionales que viven en tu repo y se cargan contextualmente.
Se componen: un Skill puede instruir a Claude para que llame a una tool MCP. O un servidor MCP puede ser el "script" al que apunta un Skill.
La regla de decisión es simple:
¿Necesitas llamar a un sistema externo con un contrato explícito? → MCP server.
¿Necesitas inyectar conocimiento y procedimiento que se active contextualmente? → Skill.
¿Ambos? → Un Skill que referencia tu MCP server.
No es un "either/or". Es arquitectura en capas.
---
Skills y Archivos: La Anatomía Mínima
Un skill vive en una carpeta. Eso es todo. No hay más magia.
Existen dos ubicaciones:
`.claude/skills/` — skills de proyecto, commiteados en version control y compartidos con el repo.
`~/.claude/skills/` — skills personales, disponibles en todos tus proyectos.
Un skill con script de soporte se ve así:
```markdown
my-skill/SKILL.md
---
name: ipa_normalizer
description: Normaliza datos masivos desde CSV de exportación.
Se invoca para limpieza de datos, transformaciones de formato,
deduplicación de registros y parsing de ficheros de exportación.
---
cuando necesites normalizar un CSV de más de 200 filas,
ejecuta scripts/normalize.py sobre el fichero de origen.
El script ya maneja deduplicación y transformación de fechas.
```
```python
my-skill/scripts/normalize.py
import csv, sys
reader = csv.DictReader(open(sys.argv[1]))
rows = []
seen = set()
for row in reader:
key = (row.get("email", "") or "").lower()
if key in seen:
continue
seen.add(key)
rows.append(row)
writer = csv.DictWriter(sys.stdout, fieldnames=reader.fieldnames)
writer.writeheader()
writer.writerows(rows)
```
¿Cuándo extraes lógica a código? Cuando el paso necesita determinismo: formato exacto, parsing, validación sin ambigüedad. El lenguaje natural es brillante para procedimientos, terrible para transformaciones que exigen exactitud.
El script no es el skill. El skill es el paquete: instrucciones + routing + scripts donde hacen falta.
---
La Trampa del Conocimiento Just-In-Time
Un skill solo se carga cuando Claude decide que es relevante. Eso mantiene la ventana de contexto limpia comparado con meter todas tus reglas en `CLAUDE.md`.
Pero ese beneficio solo se materializa si la selección es fiable. Un skill que falla al dispararse obliga a Claude a un fallback lento y caro: reinventar el procedimiento sin la skill.
La válvula de escape para capacidades críticas existe. Se llama referencia explícita.
```markdown
CLAUDE.md
Este proyecto usa el skill @pr_reviewer siempre que revises
cambios. También aplica @security_scanning en todo el código
de entrada de usuarios.
```
La sintaxis `@skill` en `CLAUDE.md` fija el skill para el proyecto, sin depender del matching automático.
Mi regla en producción:
Capacidades críticas que deben ejecutarse siempre → referencia `@skill` en `CLAUDE.md`.
Capacidades auxiliares que aplican a veces → descripción optimizada y matching automático.
La selección en tiempo de inferencia es el trade-off deliberado por flexibilidad. Para lo que no puede fallar, usa la referencia explícita. No hay incertidumbre en producción.
---
Documentation-as-Code: El Skill Como Contribución de Dominio
Este es el detalle que cambia la organización entera.
Un `SKILL.md` es Markdown. La persona que escribió el procedimiento no necesita saber programar. Un responsable de procesos puede codificar los checklists de su departamento — reglas de estilo, heurísticas de dominio — sin abrir un pull request a un generador de código.
Eso baja la barrera de "contribución de capacidad" de ingenieros a expertos de dominio.
El trabajo de la persona que escribe la skill no es el código. Es traducir conocimiento de proceso a instrucciones que Claude pueda clasificar y seguir sin ambigüedad. Eso cambia quién puede extender un sistema de IA dentro de tu empresa.
No es solo una pregunta técnica. Es governance.
---
El Marco de 5 Pasos: El Índice de Búsqueda en SKILL.md
Aquí va el método que uso en cada skill que envío a producción:
Paso 1: Empieza por un fallo real recurrente
Elige una tarea que tu equipo re-explica a Claude una y otra vez. Captura las instrucciones exactas que repites. No inventes capacidades hipotéticas — documenta un dolor real.
Paso 2: Escribe la descripción como un índice de búsqueda
Enumera sinónimos, verbos de tarea y escenarios de disparo. Después prueba si Claude selecciona el skill cuando le das prompts realistas. Iterar aquí paga más que iterar en el script.
Paso 3: Markdown primero
Envía la versión solo-`SKILL.md` y mide utilidad antes de añadir código. Añade scripts solo para los pasos que necesitan determinismo: formato, parsing, validación exacta.
Paso 4: Loop de evaluación de skills
Ejecuta 5–10 prompts realistas. Inspecciona si Claude seleccionó el skill y si el output mejoró. Itera sobre descripción y cuerpo. No despliegues a ciegas.
Paso 5: Versiona y comparte
Los skills son ficheros planos. Son versionables por diseño. Los skills de proyecto van en `.claude/skills/` commiteados al repo. Usa el campo `version` cuando cambie el comportamiento. Promueve los skills demostrados a tu librería personal en `~/.claude/skills/`.
---
Antes de Empezar a Escribir Scripts, Piensa en el Rendimiento de la Descripción
Vamos a ser honestos: la selección de skills no es determinista. Eso asusta en producción.
Pero el mismo Claude que lee tu descripción es el que ejecuta la tarea. Si le escribes una descripción que refleje cómo Claude clasificaría las tareas entrantes — verbos de tarea, dominios, escenarios de disparo — la fiabilidad sube de forma drástica.
*El problema de distribución del ecosistema no es la calidad del código. Es la discoverability de la descripción.* Los skills se comparten como carpetas planas por GitHub y colecciones de comunidad. El "marketplace" de skills no compite en sofisticación de código: compite en disciplina de descripción.
Los mejores practices van a converger en convenciones de naming, disciplina de keywords y versionado — el mismo camino de maduración que recorrieron las librerías de prompts y los registries MCP.
La restricción vinculante es la calidad de la documentación.
---
Conclusión: Tu Primer Skill No Va a Tener Código
Tu primer skill va a ser un fichero Markdown en una carpeta. Y eso va a ser tu mejor skill.
El que se usa no es el que tiene el script más elegante: es el que Claude clasifica correctamente cuando llega la tarea. Escribir una descripción que nombre verbos, dominios y escenarios de disparo es más valioso que cualquier función de Python que escribas después.
El valor real de una skill está en el empaquetado y el routing, no en el código. Y eso es una noticia increíble para los equipos pequeños: puedes empezar hoy, sin infraestructura, con un fichero Markdown y un análisis honesto de qué tareas repites cada semana.
El futuro de los custom agents no se construye con más código. Se indexa mejor.
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