10 Consejos para crear skills para Claude Code
Claude CodeSkills IAProductividad

10 Consejos para Crear Skills para Claude Code que Realmente Funcionan

Los 10 errores más comunes al crear skills para Claude Code y cómo solucionarlos: triggers, estructura, ejemplos y versionado.

🤖
Ruva IA
2 de junio de 2026
·⏱ 8 min de lectura

Llevas tiempo construyendo tu workflow perfecto, documentas todo en un SKILL.md impecable, y cuando lo necesitas… Claude improvisa como si el skill no existiera. Estos son los 10 problemas y sus soluciones.

10
Consejos accionables
5
Errores de trigger
8
Min de lectura

Los 10 Consejos

Ordenados de mayor a menor impacto en la tasa de activación

⚡
#01

Empieza por el trigger, no por el contenido

La descripción del skill (campo description en el frontmatter YAML) es el mecanismo de activación. Claude la lee para decidir si el skill es relevante. Si es genérica, el skill no se activa.

✗ Mal
description: Ayuda a editar documentos de Word.
✓ Bien
description: Activa este skill cuando el usuario mencione archivos .docx, 'editar Word', 'documento Word', 'abrir documento' o cualquier tarea que involucre crear, modificar o leer archivos de Microsoft Word.
📖
#02

Instrúyele a Claude que lea el skill antes de ejecutar

Que el SKILL.md exista no garantiza que Claude lo consulte. Debes decirlo explícitamente al inicio del cuerpo del skill.

✓ Bien
## Instrucción crítica

Antes de escribir cualquier línea de código, crear archivos o ejecutar comandos, lee este SKILL.md completo. Esta instrucción es obligatoria.
🗂️
#03

Estructura el SKILL.md con secciones claras

Claude escanea los documentos, no los lee linealmente. Los encabezados H2/H3 funcionan como índice — Claude salta a la sección relevante.

✓ Bien
## Cuándo usar este skill
## Qué hace este skill
## Fuera de scope
## Proceso paso a paso
## Ejemplos
## Errores comunes
🚫
#04

Incluye explícitamente qué NO hace el skill

Sin la sección 'Fuera de scope', Claude intenta resolver con el skill tareas para las que no fue diseñado, generando resultados impredecibles.

✓ Bien
## Fuera de scope

- Archivos PDF (usa el skill `pdf`)
- Google Docs (requiere integración Drive)
- Presentaciones PowerPoint (usa `pptx`)
💡
#05

Pon ejemplos reales de input → output

Un ejemplo concreto vale más que diez líneas de instrucción abstracta. Claude aprende por demostración.

✓ Bien
**Input:** "Arregla los errores de gramática en mi documento"
**Output esperado:** Claude lee el .docx, corrige errores, guarda la versión editada en /mnt/user-data/outputs/

**Qué NO hacer:** No devolver el texto en el chat — siempre modificar el archivo directamente.
🏷️
#06

Nombra el skill con la acción o el formato

El nombre del skill influye en cómo Claude lo busca y referencia. Un nombre ambiguo genera confusión.

✗ Mal
word-handler · document-processor · slide-maker · data-tool
✓ Bien
docx · pdf · pptx · xlsx · markdown-article
🎯
#07

Un skill, una responsabilidad

Un 'super-skill' que maneje todo se activa de forma impredecible. Señal de alerta: más de 5 contextos distintos en 'Cuándo usar este skill'.

✓ Bien
## Skills relacionados

- Para PDFs → usa el skill `pdf`
- Para presentaciones → usa el skill `pptx`
- Para hojas de cálculo → usa el skill `xlsx`
🧪
#08

Prueba con casos límite antes de dar el skill por terminado

Un skill que funciona solo con el caso ideal es un skill frágil. Prueba estos escenarios.

✓ Bien
✓ Peticiones ambiguas: "arregla esto" (sin especificar archivo)
✓ Inglés mezclado: "fix my documento de Word"
✓ Typos: "crear un docuemnto"
✓ Conversación larga con contexto acumulado
✓ Arranque desde cero con pedido directo
🔖
#09

Versiona tu SKILL.md como si fuera código

Sin versionado, cuando algo deja de funcionar no sabes qué cambió. Tres líneas de contexto histórico pueden ahorrarte horas de debugging.

✓ Bien
---
name: docx
version: 1.3
last_updated: 2025-06
---

## Changelog
- v1.3 — Agregada instrucción para imágenes en base64
- v1.2 — Corregido trigger para rutas de red
- v1.0 — Versión inicial
📝
#10

Documenta el 'por qué' de tus decisiones

El SKILL.md no es solo instrucción para Claude — es documentación para ti en el futuro. Cuando edites el skill tres meses después, necesitarás entender por qué tomaste ciertas decisiones.

✓ Bien
1. Lee el archivo con `view` antes de modificar
   *(razón: evita sobreescribir contenido existente relevante)*

2. Guarda en /mnt/user-data/outputs/, nunca en /tmp/
   *(razón: /tmp/ no persiste entre sesiones)*

Checklist de 10 Puntos

Verifica esto antes de dar un skill por terminado

La description menciona palabras clave, tipos de archivo y contextos específicos
El SKILL.md instruye a Claude a leerlo antes de ejecutar
Hay secciones claras con H2/H3
Existe una sección 'Fuera de scope'
Hay al menos 2-3 ejemplos de input → output esperado
El nombre refleja la acción o formato, no la función interna
El skill tiene una sola responsabilidad bien definida
Lo probaste con peticiones ambiguas, en inglés y con typos
El frontmatter incluye versión y fecha
Las decisiones no obvias tienen comentarios explicativos

Preguntas Frecuentes

🤖

¿Tienes un skill que no funciona como esperas?

El siguiente nivel es aprender a usar la skill-creator — la skill de Claude Code para crear y optimizar otras skills con evals automatizados.