Agent Mentor Learn
Claude Code Skills: crea tus propios flujos de trabajo con IA · Lección 4 de 6

Lección 4: Pruebas y depuración: asegurar que tu Skill se comporte

Objetivos de aprendizaje:

  • Conocer las formas básicas de probar una Skill
  • Diagnosticar las fallas que realmente vas a encontrar
  • Entender el ciclo de iteración
  • Saber cómo verificar si una Skill vale la pena de verdad

Requisitos: << Lección 3 | Siguiente: Lección 5 >>

Tu primera Skill no va a salir bien

Escribiste tu primera Skill, la ejecutaste y notaste cosas como estas:

  • Algunas tareas no se reconocieron en absoluto
  • Las prioridades salieron mal
  • El formato de salida fue un desastre
  • O Claude nunca cargó la Skill

Eso es normal.

Las Skills son como el código: lograr que corra una vez es la línea de salida, no la de llegada. Toda Skill que realmente resulta útil llegó ahí después de varias rondas de revisión.1

Esta lección te da una manera repetible de encontrar y arreglar esos problemas.

Método de prueba 1: invocarla directamente

La prueba más simple es la invocación directa: la llamas una vez con /skill-name y observas qué sale.2

Prepara tus casos de prueba

Antes de invocar nada, anota entre tres y cinco entradas.

Casos normales:

Terminar el reporte trimestralRevisar el PR #234, antes del viernesArreglar el bug de login mañana

Casos límite:

(entrada vacía)

Casos basura:

Este es un párrafo de prosa completamente ajena que no contiene ninguna tareaasldfkjasldfj!@#$%

Ejecuta las pruebas

En Claude Code, pásalas de una en una:

/task-organizer
Terminar el reporte trimestralRevisar el PR #234, antes del viernesArreglar el bug de login mañana

Observa tres cosas:

  1. ¿Claude cargó la Skill? (Si no, el problema está en la description.)
  2. ¿El formato de salida es correcto? (Si está desordenado, el problema está en tu sección de formato de salida.)
  3. ¿El contenido es el que esperabas? (Si las categorías están mal, el problema está en tus pasos de procesamiento.)

Anota lo que pasó

Basta con una tabla chica:

EntradaEsperadoObtenidoProblema
"Terminar el reporte\nArreglar el bug mañana"2 tareas; el bug es urgenteSolo encontró 1 tareaLos saltos de línea no se tratan como separadores

Método de prueba 2: observar el comportamiento de carga

A veces el problema no está en las instrucciones, sino en el frontmatter.

Problema: Claude no carga la Skill por su cuenta

Lo que ves: dices "ayúdame a organizar estas tareas" y Claude ignora tu Skill task-organizer.

Causas probables:

  1. La description es demasiado genérica

    Arreglo: mete las palabras disparadoras.

  2. La description no contiene las palabras que en realidad dices

    Si dices "ayúdame a ordenar estos pendientes" pero la palabra "pendiente" no aparece por ningún lado en la description, puede que Claude nunca piense en la Skill.3

    Arreglo: escribe en la description las palabras que un usuario diría de forma plausible.

Problema: Claude carga la Skill equivocada

Lo que ves: querías task-organizer, pero Claude tomó otra.

Causa probable: la description de la otra Skill se parece más a tu entrada.

Arreglo: fuerza la llamada con /task-organizer, o afina tu description para que sea más específica que la de la otra Skill.

Diagnosticar las fallas más comunes

Problema 1: el formato de salida está mal

Lo que ves: la Skill corre, pero el formato no cuadra.

Ejemplo:

Urgente: Arreglar el bug de login - mañanaImportante: Revisar el PR #234 - viernes

Querías secciones agrupadas con emoji y encabezados; Claude te dio una lista de texto plano.

Causa: la sección de formato de salida no es lo bastante específica, o no tiene ejemplo.

Arreglo: pon un ejemplo completo en la sección "Formato de salida" de tu SKILL.md:

Di "debe seguir este formato exactamente" y luego muestra la cosa completa.

Problema 2: el reconocimiento es impreciso

Lo que ves: algunas tareas se pierden, o caen en la categoría equivocada.

Ejemplo:

Entrada:

Hay que arreglar ese bug mañanaDejar lista la demo antes del viernes

Salida:

### ⚪ Normal- Hay que arreglar ese bug mañana - sin fecha límite declarada- Dejar lista la demo antes del viernes - sin fecha límite declarada

Ambas tienen una fecha límite clara y ambas quedaron marcadas como si no la tuvieran.

Causa: las reglas de reconocimiento de tiempo en tus pasos de procesamiento no cubren suficientes casos.

Arreglo: complétalas.

La idea: deja por escrito todas las formulaciones que se te ocurran.

Problema 3: los casos límite se cuelan

Lo que ves: la entrada normal funciona bien, pero una entrada inusual hace que la Skill se comporte raro.

Ejemplo:

Entrada: una cadena vacía

Salida: Claude se traba, o produce una pila de texto sin sentido.

Causa: tu sección "Notas" nunca dijo qué hacer con una entrada vacía.

Arreglo:

El ciclo de iteración

Las buenas Skills no se escriben de una sola vez. Salen de un ciclo probar-arreglar-probar:1

1. Escribe la primera versión (solo el comportamiento central)2. Córrela contra 3-5 casos de prueba3. Anota qué salió mal4. Edita SKILL.md5. Prueba de nuevo6. Repite 3-5 hasta que pasen todos los casos de prueba7. Úsala en serio durante una semana8. Encuentra problemas nuevos9. Vuelve al paso 4

No esperes que la versión uno salga bien. Haz que corra, después que sea correcta, después que sea buena.

¿La Skill sirve de verdad?

Una vez que corre correctamente, queda una pregunta mayor: ¿esta Skill realmente te está ahorrando tiempo?1

Compáralo A/B

La comparación es simple: corre la misma tarea varias veces con y sin la Skill, y toma el tiempo en ambos casos.

Sin la Skill:

Toma el tiempo. Explicas el proceso a mano, Claude ejecuta — ¿cuánto tarda eso en promedio?

Con la Skill:

Toma el tiempo. Invocas la Skill, Claude ejecuta — ¿cuánto en promedio?

Si la versión con Skill no es más rápida, o la calidad es peor, a la Skill todavía le falta trabajo.

Úsala durante una semana

La prueba de verdad es el uso real.4

Lleva la cuenta de estos números:

  • Cuántas veces la invocaste
  • Cuántas veces el resultado sirvió tal cual, sin ediciones manuales
  • Cuántas veces tuviste que volver a correrla o arreglar la salida a mano
  • Cuánto tiempo te ahorró

Si la invocaste menos de tres veces en una semana, probablemente la tarea no es lo bastante repetitiva como para justificar una Skill.

Guía rápida de depuración

Cuando una Skill no funciona, arranca por una revisión de falla de carga: recorre la tabla de abajo y descarta la ruta del archivo, el formato del frontmatter y las palabras clave disparadoras, en ese orden.

ProblemaCómo diagnosticarloDónde arreglarlo
Claude no carga la Skill automáticamenteRevisa si la description contiene las palabras que efectivamente dijisteAgrega palabras disparadoras, deja explícito el caso de uso
El formato de salida está desordenadoRevisa si diste un ejemplo de salida completoAgrega el ejemplo, agrega "debe seguir este formato exactamente"
El reconocimiento es imprecisoRevisa si los pasos de procesamiento enumeran todos los casosAgrega reglas, agrega más criterios de decisión
Los casos límite se comportan malRevisa si "Notas" cubre ese casoAgrega manejo explícito para el caso especial
La Skill existe pero no se invocaRevisa la ruta del archivo, revisa el formato del frontmatterConfirma que los marcadores --- estén en el lugar correcto y que la indentación YAML sea válida

Resumen

  • Tu primera Skill no va a salir bien — llegar ahí toma un ciclo probar-arreglar-probar
  • Métodos de prueba: invocarla directamente, observar el comportamiento de carga, preparar casos de prueba de antemano
  • Fallas comunes: description demasiado genérica, formato de salida poco especificado, reglas de reconocimiento incompletas, casos límite sin manejar
  • Flujo de depuración: registrar esperado contra obtenido, diagnosticar, editar SKILL.md, volver a probar
  • Demostrar que vale la pena: comparar tiempo, calidad y consistencia con y sin la Skill, después usarla una semana y contar las invocaciones

En la próxima lección vamos a recorrer una Skill completa de revisión de código y ver cómo manejar un flujo de trabajo más involucrado.

>> Lección 5: Caso práctico: construir una Skill de revisión de código

Footnotes

  1. Claude Code skills: flujos de trabajo .NET y prompts reutilizables — https://codewithmukesh.com/blog/skills-claude-code/ ↩ ↩2 ↩3

  2. Documentación oficial de Claude Code: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩

  3. Building skills for Claude, en la práctica: frontmatter YAML y pruebas — https://sjramblings.io/building-skills-for-claude-part-2/ ↩

  4. Las skills de Claude como runbooks autodocumentados — https://zackproser.com/blog/claude-skills-internal-training ↩

Ejercicios

01

Toma la Skill que construiste en la Lección 3 y pásala por una ronda completa de pruebas:

Nivel 1: Depura tu propio Skill
  1. Prepara 3 casos de prueba (uno normal, uno límite, uno basura)
  2. Registra la salida esperada y la obtenida para cada uno
  3. Encuentra al menos un problema concreto
  4. Edita SKILL.md
  5. Vuelve a probar y confirma que el problema desapareció
Criterios de finalización · marcado local
02

Haz la misma tarea dos veces: una con tu Skill, otra describiéndole directamente a Claude lo que quieres. Después compara:

Nivel 2: Compara contra no usar Skill
  1. Cuál fue más rápida
  2. Cuál produjo mejores resultados
  3. Cuál fue más consistente (misma forma de salida entre corridas repetidas)
Criterios de finalización · marcado local