run

Inicia un sitio o aplicación local y lo visualiza en un navegador real. Detecta la pila tecnológica desde package.json, archivos de configuración o un index.html simple, elige un puerto libre, inicia el servidor de desarrollo o un servidor estático, espera hasta que responda, lo captura en pantalla o lo abre, y lo detiene con una sola bandera. Úsalo cuando el usuario pida ejecutar, servir, lanzar, previsualizar, iniciar o abrir un proyecto localmente, comprobar una página en el navegador, tomar una captura de pantalla de un sitio, o cuando una compilación necesite ser vista antes de poder ser evaluada.

¿Qué es run?

El skill `run` proporciona el camino más corto entre una carpeta de proyecto y una página renderizada en el navegador. Detecta automáticamente el stack del proyecto (por ejemplo, desde package.json, index.html o configuraciones de frameworks), inicia un servidor de desarrollo o estático en un puerto libre, y opcionalmente abre el navegador o toma una captura de pantalla usando Playwright a 1440 px de ancho. Está diseñado para agentes como Claude Code o Cursor, y se ejecuta mediante un script Node.js (`serve.mjs`) que escribe el estado en `.run/state.json` y el registro en `.run/server.log`, permitiendo una gestión clara del ciclo de vida: iniciar, visualizar, detener. El skill impone reglas estrictas: nunca dejar un servidor corriendo sin reportarlo, leer el registro de errores antes de adivinar, e informar siempre la URL real. Incluye una lista de verificación para asegurar que el agente detecte correctamente el stack, informe la URL exacta, revise una captura de pantalla y detenga el servidor, o comunique claramente si sigue activo.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/itsdanylol/claude-sitecraft/tree/HEAD/skills/run

Installed? Explore more Productividad y colaboración skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace run?

Un sitio no está terminado hasta que se ha visto en ejecución. El código fuente dice lo que alguien pretendía; el navegador dice lo que una persona recibe. Este skill es el camino más corto entre una carpeta y una página renderizada.

Ejecútalo

node <carpeta del skill>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
  • --detect imprime lo que encontró y no inicia nada. Hazlo primero cuando la carpeta no sea familiar.
  • --port empieza a buscar ahí y toma el siguiente puerto libre, así dos proyectos pueden ejecutarse a la vez.
  • --open abre el navegador predeterminado.
  • --shot out.png renderiza la página a 1440 de ancho, altura completa, mediante Playwright.
  • --stop mata el árbol de procesos desde .run/state.json.

Escribe .run/state.json (pid, puerto, url, comando) y .run/server.log junto al proyecto. Esos dos archivos son toda la transferencia entre el inicio y la parada.

Lo que detecta

EncuentraEjecuta
package.json con dev, start, serve o previewnpm run <ese script> en un puerto libre, con PORT establecido
index.html en la raízpython -m http.server en esa carpeta
public/index.html, dist/index.html, build/index.htmlun servidor estático enraizado en la salida de la compilación
Un archivo de configuración pero sin scriptslo reporta y se detiene: el proyecto necesita su propio comando
go.mod, Cargo.toml, pubspec.yamllo reporta y se detiene: usa el comando de ejecución del proyecto

Detalles específicos del framework, puertos predeterminados y los modos de fallo que vale la pena conocer: references/stacks.md.

Leyendo el resultado

El script prueba tres cosas y nada más: un proceso inició, un puerto respondió, una página se renderizó. Lo que no puede decirte:

  • si el diseño es correcto a 375, 768 y 1440 (usa sitecraft/scripts/verify.mjs para eso)
  • si la consola está limpia (no se captura aquí; verify.mjs la captura)
  • si la página de la que tomó captura es la página que el usuario quería (verifica la URL contra la ruta que solicitaste)

Así que el bucle es: serve.mjs --shot, mira la imagen con tus propios ojos, corrige, vuelve a tomar captura. Tres renderizados es el límite por pasada; más allá, el problema es el plan, no el CSS.

Reglas

  • Nunca dejes un servidor corriendo. Detenlo cuando la verificación esté hecha, o di claramente que sigue activo y en qué puerto. Un servidor de desarrollo perdido en la máquina del usuario es un lío que tienen que limpiar.
  • No empieces lo que no puedas detener. Si el proyecto necesita Docker, una base de datos o una clave de API de pago, dilo antes de iniciar cualquier cosa.
  • Reporta la URL real. localhost:4173, no "la aplicación". Si el puerto se movió porque el 4173 estaba ocupado, di el nuevo.
  • Lee el registro antes de adivinar. Un inicio fallido casi siempre es una dependencia faltante, una variable de entorno faltante o un puerto ya ocupado. .run/server.log tiene la respuesta, y citar el error real es mejor que una teoría.
  • Nada de instalaciones sin decirlo. Si falta node_modules, npm install suele ser lo correcto, y también es una mutación de su proyecto. Hazlo, luego di que se ejecutó, o pregunta una vez cuando la instalación sea grande.
  • Estático antes que framework. Cuando existe una salida de compilación y está actualizada, servir dist/ es más rápido y fiable que el servidor de desarrollo.

Cuando no iniciará

  1. Lee .run/server.log y cita el primer error real, no la última línea.
  2. Dependencias faltantes: npm install en el proyecto, luego reintenta.
  3. Variables de entorno faltantes: busca .env.example, nombra lo que es necesario, y detente si un valor es secreto y está ausente.
  4. Puerto ya ocupado: el script ya avanza al siguiente puerto libre; un puerto fijo en la configuración del framework suele ser la causa cuando aún falla.
  5. Paso de compilación requerido: ejecuta npm run build primero, luego sirve dist/.
  6. Nativo o contenedorizado: devuelve el comando que el proyecto documenta. No todos los stacks son un script.

Lista de verificación

  • Detectó la pila en lugar de asumir una
  • Lo inició y vio una respuesta HTTP real, no solo un proceso iniciado
  • Reportó la URL y el puerto exactos
  • Miró una captura de pantalla, no solo el registro
  • Verificó que la ruta coincida con la página que se quería
  • Lo detuvo, o dijo que sigue corriendo y dónde
  • Citó el error real cuando falló

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills relacionados