Requisitos y puesta en marcha de crowdar-qa-skills

Esta guía está pensada para cualquier persona, sin conocimientos técnicos ni de programación, que necesite dejar su computadora lista para trabajar con crowdar-qa-skills. Al terminar de leerla vas a poder responder:

¿Qué necesito tener instalado en mi computadora para poder usar crowdar-qa-skills?
¿Cómo hago para que Claude Code "vea" las skills de este proyecto y cómo las uso una vez disponibles?
¿Cómo dejo configurado Playwright, el motor que usan las skills para manejar el navegador?

¡IMPORTANTE! Esta guía es de instalación y puesta en marcha (se hace una sola vez por computadora, o cada vez que empezás en un proyecto nuevo). Para entender qué es una skill o un playbook, o cómo elegir entre los distintos modelos de trabajo, mirá las guías Playbooks vs Skills y Modelos.

1. La idea en una sola frase

crowdar-qa-skills no es un programa que se instala y listo — es una carpeta con instrucciones escritas ("skills") que un asistente de IA (Claude, dentro de un editor llamado VSCode) sabe leer y ejecutar. Para que funcione necesitás tres cosas: el editor (VSCode), el asistente (Claude Code) y las herramientas que las skills usan por detrás (Node.js, Playwright, y opcionalmente Java/Maven).

Con eso instalado una sola vez, todo lo demás (leer una historia, armar un plan de pruebas, generar y correr tests) se lo pedís a Claude en lenguaje natural.

2. Stack técnico necesario — de un vistazo

Esta tabla resume todo lo que hace falta tener instalado. Los puntos 3 a 5 explican, paso a paso, cómo conseguir cada cosa.

Necesitás	¿Para qué sirve?	¿Es obligatorio?
Una computadora con Windows, Mac o Linux	Donde corre todo lo demás	Sí
VSCode (Visual Studio Code)	El editor donde vas a trabajar junto con Claude	Sí
Extensión "Claude Code" para VSCode (o el Claude Code de terminal)	El asistente de IA que lee y ejecuta las skills	Sí
Una cuenta de Claude/Anthropic habilitada	Sin login, Claude Code no puede responderte nada	Sí
Git	Para descargar (clonar) el repositorio `crowdar-qa-skills` y el del proyecto bajo test	Sí
Node.js + npm	El motor que corre Playwright (el framework de tests más usado en este proyecto)	Sí, si el proyecto usa Playwright
Playwright + sus navegadores	Es quien realmente "maneja" el navegador para explorar la app y correr los tests	Sí, si el proyecto usa Playwright
Conexión a internet / VPN de la empresa	Para bajar el repo, los navegadores de Playwright y conectar con Jira/Azure DevOps si corresponde	Sí
Java (JDK 8+) y Apache Maven	Solo si el proyecto usa `Lippia` (Java + Cucumber) en vez de Playwright	No — solo para stack Lippia
Google Chrome instalado	Solo si el proyecto usa `Lippia` (necesita un Chrome real del sistema, no alcanza con el que descarga Playwright)	No — solo para stack Lippia

El resto de esta guía asume el caso más común: un proyecto que usa Playwright (JavaScript/TypeScript). Si tu proyecto usa Lippia, al final de la sección 6 hay una nota con los requisitos extra.

3. Paso a paso: instalar lo básico

3.1 Instalar VSCode

Descargalo desde code.visualstudio.com y seguí el instalador (siguiente, siguiente, finalizar).
Abrilo una vez instalado para confirmar que arranca bien.

3.2 Instalar la extensión de Claude Code

En VSCode, abrí el panel de extensiones (ícono de cuadraditos en el margen izquierdo, o Ctrl+Shift+X).
Buscá "Claude Code" e instalala.
Al abrirla por primera vez te va a pedir iniciar sesión con tu cuenta de Claude/Anthropic — seguí el flujo de login que te propone (se abre el navegador, confirmás y volvés a VSCode).
Si tu usuario todavía no tiene acceso habilitado, pedilo al equipo técnico antes de seguir — sin login no hay forma de usar el asistente.

3.3 Instalar Git

Git es lo que te permite descargar ("clonar") los repositorios del proyecto.

Windows: descargalo de git-scm.com e instalalo con las opciones por defecto (esto también instala Git Bash, una terminal que vas a necesitar más adelante).
Mac: suele venir preinstalado; si no, xcode-select --install desde la Terminal, o git-scm.com.

Verificar que quedó instalado: abrí una terminal (en Windows, buscá "Git Bash") y escribí:

git --version

Si te devuelve un número de versión, está listo.

3.4 Clonar los repositorios que vas a necesitar

Vas a trabajar con dos carpetas en VSCode:

crowdar-qa-skills — donde viven las skills y los playbooks.
El repo del proyecto bajo test (por ejemplo, TechStore) — donde vas a generar y correr los tests.

Para clonar cada uno: en VSCode, Ctrl+Shift+P → escribí "Git: Clone" → pegá la URL del repositorio → elegí una carpeta en tu computadora → Open cuando termine. (El mismo procedimiento que se explica con más detalle en last_version.md, sección 6.)

3.5 Instalar Node.js y npm

Node.js es el motor que necesita Playwright para correr. npm (Node Package Manager) viene incluido con Node.js — no se instala aparte.

Descargá la versión LTS (la recomendada, no la "Current") desde nodejs.org.
Instalala con las opciones por defecto.

Verificar:

node --version
npm --version

Ambos comandos tienen que devolver un número de versión.

4. Cómo disponibilizar las skills para Claude

Con VSCode, Claude Code, Git y Node ya instalados, el paso que falta es decirle a Claude dónde están las skills de crowdar-qa-skills. Claude no las "adivina" — necesita encontrarlas en una carpeta específica de tu sistema.

4.1 Cómo funciona (en criollo)

Cada skill es una carpeta con un archivo SKILL.md adentro: instrucciones escritas para que Claude sepa hacer una tarea puntual (leer una historia, armar un plan de pruebas, generar tests, etc.). Claude Code, al arrancar una sesión, revisa dos ubicaciones:

Ubicación	Qué significa	Alcance
`~/.claude/skills/` (carpeta del usuario)	Skills disponibles en todos tus proyectos, sin importar en cuál estés parado	Global
`<repo>/.claude/skills/` (carpeta del proyecto)	Skills que viajan con ese repositorio puntual — cualquiera que lo clone las tiene disponibles	Solo ese proyecto

No hace falta copiar los archivos a mano: se usa un acceso directo (symlink) que apunta a la carpeta real dentro de crowdar-qa-skills. Así, cuando el equipo técnico actualiza una skill y vos hacés pull sobre crowdar-qa-skills (ver last_version.md), el cambio se refleja solo, sin repetir ningún paso.

4.2 Opción A — Disponibilizarlas globalmente (recomendado)

Recomendada si vas a usar las mismas skills en varios proyectos. Se hace una sola vez por computadora.

Abrí Git Bash (en Windows) o una terminal (Mac/Linux).
Pará en la carpeta donde clonaste crowdar-qa-skills: bash cd /ruta/a/crowdar-qa-skills
Ejecutá: ```bash mkdir -p ~/.claude/skills

for skill in skills/*/; do name=$(basename "$skill") ln -sfn "$(pwd)/$skill" ~/.claude/skills/"$name" done 4. Verificá que se crearon los accesos directos:bash ls -l ~/.claude/skills/ `` Tenés que ver una lista con el nombre de cada skill, apuntando hacia la carpeta decrowdar-qa-skills`.

4.3 Opción B — Disponibilizarlas solo para un proyecto puntual

Recomendada cuando querés que las skills viajen versionadas junto con el repo del proyecto bajo test (por ejemplo, para fijar una versión específica).

Parate en la carpeta del proyecto bajo test (no en crowdar-qa-skills): bash cd /ruta/al/proyecto-bajo-test mkdir -p .claude/skills
Si clonaste crowdar-qa-skills al lado de ese proyecto, corré: bash for skill in ../crowdar-qa-skills/skills/*/; do name=$(basename "$skill") ln -sfn "$(cd "$skill" && pwd)" .claude/skills/"$name" done El repo trae este mismo bloque guardado en el archivo link-claude-skills.sh, así que también podés simplemente correr bash ../crowdar-qa-skills/link-claude-skills.sh.

Las skills a nivel proyecto tienen prioridad sobre las globales cuando coinciden los nombres.

4.4 Verificar que Claude ya las ve

Abrí una sesión de Claude Code sobre el proyecto bajo test y escribile, en lenguaje natural:

Listá las skills de QA disponibles

Si la instalación salió bien, Claude va a responder con la lista de skills (qa-read-user-story, qa-create-test-plan, qa-workflow-e2e, etc.).

4.5 Desinstalar (si hace falta)

Como son accesos directos, borrarlos no toca el repositorio original:

# Global
for skill in skills/*/; do rm -f ~/.claude/skills/"$(basename "$skill")"; done

# A nivel de un proyecto puntual
rm -rf .claude/skills

5. Cómo configurar Playwright

Playwright es la herramienta que efectivamente abre un navegador (Chrome, Firefox, etc.), navega por la app bajo test, hace clics, completa formularios y verifica resultados — es el "brazo ejecutor" detrás de las skills cuando el proyecto está configurado con este framework.

5.1 Instalar las dependencias del proyecto

Parate en la carpeta raíz del proyecto bajo test (donde está su package.json, no en crowdar-qa-skills) y corré, en una terminal:

npm install

Esto descarga las librerías necesarias (entre ellas, @playwright/test).

5.2 Instalar los navegadores de Playwright

Playwright necesita sus propias copias de los navegadores (no usa el Chrome que ya tenés instalado en la computadora):

npx playwright install

Este paso descarga los binarios de Chromium, Firefox y WebKit. Solo hace falta correrlo una vez por computadora (o cuando cambia la versión de Playwright del proyecto).

5.3 Instalar el navegador para la etapa de exploración (MCP)

Además de correr los tests, Claude usa Playwright para explorar la app manualmente antes de generar los tests (la skill qa-exploratory-test / qa-scripted-execution). Para eso necesita su propio navegador vía MCP:

npx @playwright/mcp install-browser chrome-for-testing

5.4 Qué es el archivo `.mcp.json` (no hace falta tocarlo)

El repositorio crowdar-qa-skills ya trae un archivo .mcp.json con la configuración del servidor MCP de Playwright:

"playwright": {
  "type": "stdio",
  "command": "mcp-server-playwright",
  "args": ["--browser", "chromium"],
  "env": {}
}

No necesitás editar esto — ya viene configurado. Es simplemente la forma en la que Claude Code sabe cómo arrancar el navegador de Playwright cuando una skill lo necesita.

Si al usar una skill que depende del MCP (por ejemplo qa-exploratory-test) te aparece un error de conexión, mirá el instructivo playwright-mcp-setup — cubre los incidentes más comunes de configuración del MCP de Playwright y cómo resolverlos.

5.5 Datos del ambiente bajo test (URL y credenciales)

Las skills necesitan saber contra qué URL probar y con qué usuario. Esto vive en un archivo .env (que nunca se sube al repositorio — está en .gitignore), en la raíz del proyecto bajo test:

# .env
APP_BASE_URL=https://tu-app-bajo-test.com
APP_USERNAME=usuario-de-prueba
APP_PASSWORD=contraseña-de-prueba

Si no tenés este archivo todavía, la skill qa-bootstrap-stack te lo puede armar, preguntándote estos datos la primera vez que configura el proyecto.

5.6 El archivo `qa-stack.yaml`

Es la "ficha técnica" del proyecto: le dice a las skills que el framework es playwright, en qué carpeta están los tests, dónde se guardan los reportes, etc. No hace falta escribirlo a mano.

Para entender qué hace este playbook paso a paso antes de correrlo, leé el instructivo new-project-bootstrap.

5.7 Checklist rápido de Playwright

node --version && npm --version    # Node y npm instalados
npm install                        # dependencias del proyecto
npx playwright install             # navegadores de Playwright
npx @playwright/mcp install-browser chrome-for-testing   # navegador para exploración

Si los cuatro comandos corren sin error, Playwright está listo para que las skills generen y ejecuten tests.

¿Tu proyecto usa Lippia (Java + Cucumber) en vez de Playwright? Entonces en lugar de esta sección necesitás: un JDK 8+, Apache Maven 3.6+, acceso a los repositorios Nexus de Crowdar, y un Google Chrome real instalado en el sistema (no alcanza con el que descarga Playwright). El detalle completo de este caso está en INSTALL.md del repo crowdar-qa-skills.

6. Resumen visual del flujo completo

Instalar VSCode + extensión Claude Code (login con tu cuenta)
            │
            ▼
Instalar Git → clonar crowdar-qa-skills y el proyecto bajo test
            │
            ▼
Instalar Node.js + npm
            │
            ▼
Disponibilizar las skills (symlink global o por proyecto)
            │
            ▼
Verificar: pedirle a Claude "listá las skills disponibles"
            │
            ▼
Configurar Playwright: npm install → playwright install → mcp install-browser
            │
            ▼
Generar qa-stack.yaml y .env (o pedirle a Claude que los arme con qa-bootstrap-stack)
            │
            ▼
Ya se puede pedir, en lenguaje natural, cualquier trabajo de QA

7. Problemas comunes (y qué hacer)

Lo que ves	Por qué puede pasar	Qué hacer
Claude responde que no encuentra ninguna skill	El symlink no se creó, o se creó en la carpeta equivocada	Repetí el paso 4.2 o 4.3 y verificá con `ls -l ~/.claude/skills/` (o `.claude/skills/` del proyecto)
Los comandos de symlink (`ln -sfn`, `for ... in`) tiran error en la terminal	Estás en la terminal de Windows (`cmd.exe` o PowerShell) en vez de Git Bash	Abrí específicamente Git Bash (se instaló junto con Git) y volvé a correr los comandos ahí
`npx playwright install` tarda mucho o falla	Está descargando los navegadores por primera vez y depende de tu conexión	Esperá a que termine; si falla por red, verificá tu conexión/VPN y reintentá
Un test falla con error de navegador no encontrado	Falta correr `npx playwright install` o `npx @playwright/mcp install-browser`	Corré ambos comandos (secciones 6.2 y 6.3)
Una skill con adapter (`qa-generate-test-suite`, `qa-run-and-heal`) dice que falta configuración	No existe `qa-stack.yaml` en la raíz del proyecto bajo test	Pedile a Claude: "usá qa-bootstrap-stack para generar qa-stack.yaml"
Los tests no encuentran la URL o las credenciales de la app	Falta el archivo `.env` o le faltan variables	Creá/completá `.env` en la raíz del proyecto con `APP_BASE_URL`, `APP_USERNAME`, `APP_PASSWORD` (sección 6.5)
Claude Code no responde nada / pide iniciar sesión todo el tiempo	La cuenta de Claude/Anthropic no quedó logueada, o no tiene acceso habilitado	Repetí el login desde la extensión (paso 3.2); si el problema persiste, consultá al equipo técnico por el acceso