Playbooks vs. Skills — Guía para entender la diferencia

Esta guía está pensada para cualquier persona, sin conocimientos técnicos ni de programación, que necesite entender dos palabras que va a escuchar todo el tiempo trabajando con el asistente QA (Claude): "skill" y "playbook".

Al terminar de leerla vas a poder responder, sin dudar:

¿Qué es una skill?
¿Qué es un playbook?
¿En qué se parecen y en qué se diferencian?
¿Cuál uso yo en cada situación?

1. La idea en una sola frase

Una skill es una herramienta. Un playbook es la receta que dice en qué orden usar varias herramientas para resolver un trabajo completo.

Si esa frase ya te cerró, con eso alcanza para el 80% del día a día. El resto de la guía es para que te quede clarísimo con ejemplos reales del proyecto.

2. La analogía de la cocina

Pensá en un/a cocinero/a preparando un plato.

En la cocina	En nuestro proyecto
Un utensilio o técnica individual: cortar, batir, hornear	Una skill: una tarea puntual y especializada
Una receta completa: "Torta de chocolate — paso a paso"	Un playbook: una guía que encadena varias skills en orden, para un objetivo de punta a punta
El/la cocinero/a elige la receta según lo que quiere lograr (un cumpleaños, una cena rápida)	Vos elegís el playbook según la situación (una historia nueva, un bug, un PR de frontend)
La receta te dice "primero cortá, después batís, después horneás"	El playbook te dice "primero leé la historia, después planificá, después probá, después reportá"

Nadie usa "cortar" como si fuera el plato entero. Y nadie sigue una receta sin, en el fondo, estar cortando, batiendo y horneando en algún paso. Un playbook no reemplaza a las skills — las organiza.

3. ¿Qué es una skill?

Una skill es una tarea puntual y especializada que el asistente sabe hacer muy bien. Hace una sola cosa, la hace bien, y devuelve un resultado concreto.

Características de una skill

Resuelve un solo paso de un trabajo más grande (no un proceso completo).
Se invoca con un comando específico, por ejemplo /qa-read-user-story.
Recibe algunos datos de entrada (por ejemplo, la ruta de un archivo) y entrega un resultado concreto (por ejemplo, un resumen).
No decide "qué viene después" — eso es trabajo del playbook o de quien la invoca.

Ejemplo real: la skill `qa-read-user-story`

Es la skill que lee una historia de usuario (el documento que describe una funcionalidad a probar) y extrae de ahí lo esencial:

Un resumen en lenguaje simple.
La lista de criterios de aceptación (qué tiene que cumplir la funcionalidad para considerarse correcta).
La URL de la aplicación y las credenciales de prueba, si están mencionadas.
Las funcionalidades clave a probar.

Vos le pasás un archivo o un link a un ticket (Jira / Azure DevOps), y ella te devuelve esa información ya ordenada. No planifica pruebas, no explora la app, no genera tests — eso lo hacen otras skills, después.

Otros ejemplos de skills del proyecto

Skill	Qué hace, en una frase simple
`qa-read-user-story`	Lee una historia de usuario y saca lo esencial (resumen, criterios, URL, credenciales)
`qa-create-test-plan`	A partir de esa historia, arma un plan de pruebas paso a paso
`qa-scripted-execution`	Navega la aplicación real (como lo haría una persona) y prueba manualmente los escenarios del plan
`qa-generate-test-suite`	Convierte el plan en tests automáticos, escritos en el lenguaje/framework del proyecto
`qa-run-and-heal`	Corre los tests automáticos y repara los que fallan por motivos menores (por ejemplo, un botón que cambió de nombre)
`qa-write-test-report`	Junta todos los resultados anteriores y escribe el reporte final
`qa-bootstrap-stack`	Analiza un proyecto nuevo y detecta con qué herramientas de testing trabaja
`qa-fetch-jira-user-story` / `qa-fetch-azure-user-story`	Trae una historia de usuario directamente desde Jira o Azure DevOps

Cada fila de esta tabla es una sola skill, una sola responsabilidad. Ninguna de ellas, por sí sola, hace "todo el trabajo de QA" — para eso están los playbooks.

4. ¿Qué es un playbook?

Un playbook es una guía paso a paso para una situación concreta del día a día (una historia nueva, un bug reportado, un PR de frontend, un hotfix urgente). Encadena varias skills, en un orden específico, y define además:

Cuándo usar ese playbook (en qué situación aplica).
Qué precondiciones tiene que cumplirse antes de arrancar (por ejemplo, tener cierto archivo listo).
En qué momentos hay que pausar y pedirle a una persona (vos) que decida algo — esto se llama un checkpoint humano.
Qué se entrega al final (reportes, archivos de test, evidencia).

En otras palabras: el playbook es el mapa del camino completo, mientras que cada skill es una parada del camino.

Ejemplo real: el playbook "Frontend UI Change PR"

Se usa cuando alguien del equipo de desarrollo sube un PR que modifica la interfaz (botones, formularios, pantallas nuevas) y hay que validarlo antes de aprobarlo. El playbook encadena así las skills:

1. qa-read-user-story        → lee el ticket y entiende qué cambió
2. qa-scripted-execution      → recorre la app nueva y detecta qué se rompió o qué es nuevo
        │
        ▼
  ⏸ PAUSA: te pregunta si aparecieron pantallas/flujos totalmente nuevos
        │
3. qa-run-and-heal            → repara los tests viejos que dejaron de funcionar por cambios menores
        │
        ▼
  ⏸ PAUSA: te avisa si se reparó "demasiado" (señal de que el cambio fue más grande de lo declarado)
        │
4. qa-generate-test-suite     → (solo si hubo flujos nuevos) crea tests para lo nuevo
5. qa-run-and-heal            → corre todo junto y confirma que quede todo en verde
6. qa-write-test-report       → arma el reporte final, con el detalle de qué se cambió y por qué

Fijate que cada número de la lista es una skill distinta. El playbook no "hace" nada por sí mismo — es el instructivo que dice en qué orden usarlas, y en qué momentos frenar a preguntarte algo a vos.

Otros ejemplos de playbooks del proyecto

Playbook	Para qué situación se usa
`feature-new-end-to-end`	Una historia de usuario totalmente nueva: arma todo el proceso de QA desde cero
`frontend-ui-change-pr`	Un PR que cambia la interfaz visual de la aplicación
`bug-reproduction`	Alguien reportó un bug y hay que documentar cómo reproducirlo, con evidencia
`bug-tdd-fix`	Un bug que se va a corregir: primero se genera el test que falla, después el developer arregla, y se confirma que quedó bien
`business-rule-change`	Cambió una regla de negocio (por ejemplo, una condición de facturación) y hay que actualizar las pruebas afectadas
`hotfix-fast-track`	Un arreglo urgente que hay que validar rápido, sin frenar el proceso de emergencia
`regression-on-module`	Se quiere volver a probar solo un módulo puntual del sistema, no toda la aplicación
`smoke-test-post-deploy`	Se acaba de desplegar una nueva versión y hay que confirmar que nada crítico se rompió
`new-project-bootstrap`	Un proyecto que todavía no tiene nada de QA configurado, y hay que arrancar de cero
`demo-walkthrough`	Mostrar en una demo, con pausas explicativas, cómo funciona todo el proceso de punta a punta

5. La diferencia, lado a lado

	Skill	Playbook
¿Qué es?	Una tarea puntual y especializada	Una guía paso a paso para una situación completa
¿Cuánto abarca?	Un solo paso	Un proceso de principio a fin (varios pasos)
¿Cómo se compone?	No usa otras skills — es la unidad más chica	Encadena varias skills, en un orden definido
¿Decide algo por su cuenta?	No — solo hace su tarea y devuelve un resultado	Sí — decide cuándo pasar al siguiente paso y cuándo pausar a preguntarte algo
¿Tiene pausas para que decida una persona?	No	Sí, en los llamados checkpoints humanos
¿Cómo se invoca?	Con su propio comando, ej. `/qa-read-user-story`	Con su propio comando o con una frase natural, ej. "corré el flujo completo para esta historia"
Ejemplo	`qa-run-and-heal` (corre y repara tests)	`frontend-ui-change-pr` (usa `qa-run-and-heal` como uno de sus pasos)
Analogía	Un utensilio de cocina (batidora, cuchillo)	Una receta completa (torta de chocolate)

6. Cómo se relacionan entre sí (resumen visual)

                    PLAYBOOK
        "Frontend UI Change PR" (la receta)
                       │
   ┌───────────────────┼────────────────────┐
   │                   │                    │
   ▼                   ▼                    ▼
qa-read-user-story  qa-scripted-execution  qa-run-and-heal   ...
  (skill)              (skill)               (skill)

   Cada una de estas skills es una "herramienta" que el playbook
   va tomando y usando, en el orden que la situación necesita.

Un playbook siempre está hecho de skills. Una skill nunca contiene un playbook adentro. El flujo va en un solo sentido: playbook → orquesta → skills.

7. ¿Cuál elijo yo?

Guía rápida de decisión:

Tu situación	Qué usar
Sabés exactamente qué paso puntual necesitás (ej: "solo quiero que me lean esta historia")	Una skill directamente, ej. `/qa-read-user-story`
Tenés una situación completa que resolver (un PR, un bug, un deploy, una historia nueva)	Un playbook, que ya sabe qué skills usar y en qué orden
No estás seguro/a de cuál playbook aplica	Contale a Claude la situación en lenguaje natural — el asistente puede ayudarte a identificar el playbook correcto
Es la primera vez que el proyecto usa este flujo de QA	El playbook `new-project-bootstrap`, que configura todo desde cero

En caso de duda: arrancá siempre por el playbook. Si tu caso no encaja en ninguno, ahí sí tiene sentido pedir una skill puntual o preguntar al equipo técnico cuál conviene armar.

8. Para no quedarte con ninguna duda: preguntas frecuentes

¿Puedo usar una skill sin pasar por un playbook? Sí. Por ejemplo, si solo necesitás que te resuman una historia de usuario, podés pedir directamente /qa-read-user-story sin correr un playbook completo.

¿Un playbook reemplaza a las skills? No, las usa. Un playbook sin skills no puede hacer nada — es solo el instructivo. Las skills son las que efectivamente ejecutan el trabajo.

¿Los checkpoints humanos son obligatorios? Sí, cuando el playbook los define. Son el momento en el que el asistente frena y te pide una decisión a vos antes de seguir (por ejemplo: "¿este cambio de UI agrega una pantalla nueva o no?"). Las skills, en cambio, no tienen checkpoints — hacen su tarea de punta a punta sin pausas.

¿Cómo sé si algo es un playbook o una skill? Preguntate: "¿esto resuelve un paso, o resuelve toda una situación?" Si es un paso puntual (leer, generar, correr, reportar), es una skill. Si es "la situación completa que tengo que resolver hoy" (un PR, un bug, un deploy), es un playbook.

9. Resumen final

Situación real de trabajo (PR, bug, historia nueva, deploy...)
                    │
                    ▼
          Elegís el PLAYBOOK adecuado
       (la receta para esa situación)
                    │
                    ▼
   El playbook va llamando, una por una,
   a las SKILLS que necesita, en orden
    (qa-read-user-story, qa-run-and-heal, ...)
                    │
                    ▼
     En el medio, te pregunta en los
        CHECKPOINTS HUMANOS definidos
                    │
                    ▼
        Resultado final: tests, reportes
           y evidencia, listos para vos

Skill = la herramienta puntual. Playbook = la receta que las ordena. Con eso, ya no hay margen para la duda.