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:
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
¿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:
- Otros skills con descripciones más específicas.
- 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
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í:
¿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.
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
@skillenCLAUDE.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.
Artículos relacionados
- Claude Skills: Cómo Construir Custom Agents que Realmente Funcionan en Producción
- Claude Skills Avanzados: Cómo Construir Custom Agents con Herramientas Reales
- Claude Skills: El 90% de los Desarrolladores los Usa Como Prompts del Sistema (y Así Es Como se Rompen)
- Claude Skills Custom Agents: El 90% los Usa Como Prompts de Sistema y Está Dejando un 80% de Productividad sobre la Mesa
- Claude Skills Custom Agents: El 80% de tu Prompt de Sistema Debería Ser una Skill, y No lo Sabes
---
¿Quieres recibir contenido como este cada semana? Suscríbete a mi newsletter
