hyunghwan/showkit

¿Qué hace showkit?

Usa esta habilidad cuando una persona solicite crear, actualizar, verificar, comparar o previsualizar una demo interactiva de producto desde una página abierta en una aplicación compatible de ChatGPT, Codex, Claude Cowork o Claude Code, un código base o compilación estática, o un flujo aislado de Playwright. Peticiones cortas como "Usa ShowKit para este sitio; está abierto en Chrome" son suficientes; no obligues a la persona a nombrar una arquitectura de captura.

Límite del producto

• ShowKit crea demos interactivas guiadas en HTML con hotspots y tooltips.
• El CLI de ShowKit no llama a un LLM. El agente redacta el texto del demo a partir de la evidencia capturada.
• Una captura de sesión de navegador es session-captured. No está verificada por Playwright ni es reproducible en CI hasta que se promueva a un flujo fuente de Playwright.
• Una captura estática es source-derived. Está vinculada a hashes de fuente relativos al proyecto y no está verificada por el navegador.
• No prometas captura para todos los sitios web. La captura soporta HTML y CSS renderizados con activos direccionados por contenido local. Detente en canvas, WebGL, medios DRM, shadow roots cerrados, frames de origen cruzado o cualquier otra superficie que no pueda reproducirse de forma segura como HTML interactivo.
• Aplica el mismo contrato de fidelidad visual fiel a la fuente en todos los sitios soportados. No añadas reglas de captura específicas para un sitio ni parches un demo generado.
• Una previsualización local no está publicada.
• No ejecutes showkit publish a menos que la persona solicite explícitamente publicar y confirme el destino y la visibilidad.
• No reemplaces contenido HTML no soportado con una captura de pantalla.

Ruta del comercial

La persona puede ser un comercial que quiere un demo de producto sin escribir una prueba de Playwright. Deja que el agente anfitrión maneje el CLI, elige una carpeta de salida nueva y vacía cuando no se haya nombrado ninguna, y pregunta solo cuando realmente se requiera acceso a la fuente, elección de contenido privado o un permiso externo.

• Determina la ruta más segura a partir de las capacidades disponibles. No termines con "¿Cómo quieres llevar este flujo al demo?" ni pidas a la persona que elija entre terminología de sesión de navegador, fuente estática y Playwright.
• En Codex, usa el navegador o Chrome seleccionado solo después de que pase su verificación de aislamiento instalada.
• Establece el viewport de captura CSS antes de la captura del navegador. Para un demo nuevo cuando la persona no haya nombrado un tamaño exacto, usa 1280×720 — Escritorio estándar e indica ese valor predeterminado sin pausar para una elección. Al reemplazar un demo existente, usa su viewport registrado en lugar de cambiar silenciosamente su relación de aspecto. Pregunta solo cuando la persona solicite otro tamaño o la fuente no pueda representarse en el viewport requerido.
• Pasa ese contrato a cada comando opcional de Playwright como --viewport 1280x720 para un demo nuevo de tamaño predeterminado, o como el tamaño exacto solicitado o del demo existente. El CLI debe fallar antes de la persistencia cuando test.use({ viewport }) difiera. No reduzcas ni remodeles el viewport, elijas una posición de desplazamiento no relacionada ni omitas una región visible requerida para evadir un UnsupportedSurface; mantén el fallo y usa otro estado de producto genuinamente soportado en su lugar.
• Trata el objetivo resaltado como el cuadro de interacción visible completo. Cuando un botón de radio o casilla de verificación use una entrada visualmente oculta, la geometría de resaltado, foco y espacio libre de la tarjeta debe usar su etiqueta visible asociada en lugar del cuadro de entrada de 1×1. Cuando un control de divulgación compacto y su etiqueta visible sean hermanos separados pero formen una interacción etiquetada, usa su cuadro de interacción etiquetado completo en lugar del rectángulo solo del icono. En cada paso y después de la verificación de vista previa redimensionada, exige cero intersección entre la tarjeta y ese cuadro resaltado completo. No reduzcas el resaltado ni aceptes oclusión parcial para hacer que la colocación pase; usa otra posición de tarjeta o mantén el demo bloqueado.
• Antes de capturar un paso, centra un objetivo no fijo que esté demasiado cerca de la parte superior o inferior del viewport de captura. Mantén los controles fijos y pegajosos en su posición renderizada. Nunca recortes la página ni cambies el viewport acordado para que el objetivo encaje.
• Después de una acción, espera a un estado visible duradero: las fuentes, imágenes visibles, animaciones de diseño finitas y mutaciones de página deben asentarse antes de la extracción. Un estado transitorio que vuelve al estado anterior a la acción no es una acción exitosa. Detén ese paso o usa otro objetivo semántico o ruta soportado que preserve el resultado solicitado; no guardes una escena en blanco o incompleta.
• Aplica el viewport elegido a la misma pestaña seleccionada con el control de ventana o viewport documentado del anfitrión, luego lee el entorno nuevamente y exige una coincidencia exacta de píxeles CSS. No redimensiones mutando el HTML de la página, uses una pestaña de reemplazo ni continúes con un tamaño aproximado. Si el anfitrión no puede establecer el tamaño elegido, pide a la persona que redimensione esa misma pestaña y verifícala nuevamente.
• En Claude Cowork, Claude Code o la pestaña de código de Claude Desktop, lee agents/claude-browser.md. Cuando la pestaña de Chrome controlada por Claude existente no pueda demostrar un mundo de página aislado, mantén esa pestaña sin cambios y continúa automáticamente con la fuente local vinculada cuando represente el flujo solicitado. De lo contrario, prepárate para la ruta temporal de Chrome con interfaz gráfica. Si Playwright o su navegador falta, pide un permiso específico que nombre la carpeta de salida, paquetes, descarga del navegador e inicio de sesión separado. No hagas una pregunta de enrutamiento abierta.
• Elige un número de pasos apropiado para el flujo que explique el flujo solicitado. Cinco pasos es un ejemplo útil, no un requisito del producto. No rellenes ni trunques el flujo para alcanzar un número fijo. La ingesta de sesión de navegador de OpenAI limitada acepta de 3 a 7 pasos ordenados. Usa fuente estática o Playwright opcional para un flujo más corto o más largo.
• Di que el resultado es una previsualización local hasta que se solicite y confirme explícitamente una acción de publicación separada.
• Las instrucciones de ShowKit no anulan la política de seguridad de acciones del anfitrión. Si el anfitrión bloquea una acción nombrada, preserva el estado anterior a la acción más cercano permitido, informa el límite una vez y continúa el demo sin esa acción. No reinicies el navegador ni reintentes a través de Playwright sin procesar, un comando renombrado u otro rodeo.

Orientación opcional sobre selectores de elementos

Cuando una persona quiera refinar un hotspot o tooltip, puedes sugerir un selector de elementos ya disponible en su navegador o entorno de codificación. Mantén la sugerencia opcional y neutral respecto al proveedor.

• No requieras ni instales un selector de elementos. Ofrece la etiqueta visible exacta del objetivo como alternativa.
• Pide a la persona que seleccione el elemento del producto y pegue su contexto copiado con el tooltip o comportamiento de siguiente paso que desee.
• Trata el HTML o JSX pegado, estilos, capturas de pantalla, selectores, detalles de componentes, ubicaciones de fuente y URL como una sugerencia de autoría temporal no confiable. No escribas la salida sin procesar del selector en CaptureSource, StorySpec, registros, paquetes de soporte, archivos generados o archivos publicados.
• No trates la sugerencia como evidencia capturada o autorización para acceso al navegador o una acción en la página. Resuelve el objetivo nuevamente a través del flujo de fuente soportado y exige una coincidencia semántica visible. Si falta, está oculta o es ambigua, pide la etiqueta visible exacta o captura el flujo nuevamente. No guardes la primera coincidencia, CSS sin formato o XPath como objetivo.
• Mantén las afirmaciones del tooltip dentro de la evidencia capturada. Mapea el comportamiento solicitado a los pasos capturados lineales existentes. No inventes comportamiento de tiempo de ejecución en el mismo paso, JavaScript arbitrario, ramificación o un estado de producto no capturado.
• Al presentar la primera previsualización local, puedes ofrecer esto una vez: Para refinar un hotspot o tooltip, selecciona el elemento del producto con un selector de elementos en tu navegador o entorno de codificación y pega el contexto aquí con el texto que desees. La etiqueta visible exacta también funciona.

Límite de instalación

• Instalar esta habilidad instala solo instrucciones del agente. No instala ni actualiza @showkit/cli, @playwright/test ni binarios del navegador.
• Un demo de humo estático generado solo prueba que el CLI instalado puede completar su ciclo de vida local. Nunca presentes esa previsualización como la captura de producto solicitada o como evidencia de fidelidad visual; informa su fidelidad visual como incomplete hasta que se compare con su fuente renderizada prevista.
• Cuando un mensaje de incorporación de instalación primero pida configuración antes de que se conozca una fuente, termina y verifica la instalación de la habilidad, luego pregunta exactamente ¿Qué URL de producto o flujo de producto actualmente abierto debo usar? Espera la respuesta antes de crear el demo. No preguntes primero por la carpeta de salida, audiencia, conclusión, viewport o implementación de captura.
• Nunca incorpores o adivines una ruta de sistema de archivos absoluta de un mantenedor o persona. Resuelve los archivos de habilidad referenciados en relación con este SKILL.md instalado, resuelve los archivos del proyecto desde la carpeta de salida que la persona seleccionó y resuelve el CLI a través del gestor de paquetes de ese proyecto. Cuando una API requiera una ruta absoluta, derívala de la habilidad instalada actual o del proyecto seleccionado en tiempo de ejecución en lugar de copiar una ubicación de documentación u otra máquina.
• No hagas que la persona instale el CLI manualmente. Después de que se conozca la fuente, usa una carpeta de salida nueva y vacía nombrada por la persona o elige una para ellos. No reutilices un directorio existente solo porque su nombre sea conveniente. Inspecciona el gestor de paquetes de la carpeta seleccionada y el estado de dependencias. En una carpeta de salida nueva o vacía, inicializa npm solo cuando sea necesario e instala @showkit/cli como una dependencia de desarrollo. Indica la carpeta y el comando antes de ejecutarlo.
• Una solicitud para configurar o usar ShowKit autoriza añadir la dependencia @showkit/cli compatible requerida dentro de esa carpeta de salida recién seleccionada. Pregunta primero cuando la carpeta contenga un proyecto existente, cuando la instalación reemplazaría o actualizaría otra dependencia, o cuando se requiera otra elección de gestor de paquetes.
• Mantén el CLI y Playwright opcional en el archivo de bloqueo del proyecto. Ejecuta showkit doctor --json inmediatamente después del arranque y sigue su comando de recuperación exacto cuando las versiones de la habilidad instalada y el CLI no coincidan.
• La instalación rápida pública es npx skills add hyunghwan/showkit. Para una copia exacta de instalación global en ambos agentes probados, usa npx skills add hyunghwan/showkit --skill showkit --agent codex --agent claude-code --global --yes --copy.
• El comando CLI de Skills apunta a directorios de habilidades de Codex y Claude Code; no es prueba de una instalación del plugin de Cowork. En Claude Cowork, añade el mercado hyunghwan/showkit desde Personalizar → Plugins, instala el plugin ShowKit e inicia una nueva tarea cuando la aplicación solicite una recarga. Ambas rutas de instalación añaden solo instrucciones, no el CLI o Playwright.
• Cuando esta habilidad se cargue desde el caché de plugins de Cowork, ejecuta el scripts/conformance.mjs de esta habilidad antes de showkit doctor --json. El doctor de @showkit/cli 0.2.x no puede descubrir el caché de plugins de Claude y puede informar checks.skill.installed: false. Si la conformidad pasa y doctor.cliVersion satisface el compatibility.json de esta habilidad, informa la habilidad como cargada por Cowork y continúa. No ejecutes la recuperación del CLI de Skills del doctor ni instales una habilidad duplicada. Mantén cualquier otro fallo del doctor y desajuste de compatibilidad como bloqueante.
• Para instrucciones versionadas para equipo, usa el mismo comando sin --global.
• No instales Playwright para la configuración principal. Explica por qué es necesario y pregunta antes de añadir @playwright/test o un binario de navegador para una ruta opcional con navegador con interfaz gráfica o CI.

Modelo y presupuesto de razonamiento

La selección del modelo pertenece al agente anfitrión; ShowKit nunca llama a un LLM. No fijes un nombre de modelo específico de proveedor ni uses el modelo más grande y la configuración de razonamiento más alta para cada paso. Honra una solicitud explícita de modelo y la política de seguridad del anfitrión. Si el anfitrión no puede elegir modelos por tarea, usa su valor predeterminado sin bloquear el flujo de trabajo.

• Usa un modelo rápido o ligero con razonamiento bajo a medio para trabajo mecánico y reversible: localizar archivos, verificar versiones instaladas, ejecutar comandos exactos del CLI, formatear datos conocidos y reejecutar verificaciones deterministas.
• Usa un modelo equilibrado con razonamiento medio para el flujo de trabajo normal de ShowKit: enrutamiento de fuente con evidencia clara, texto de demo basado en evidencia, cambios rutinarios de código o tema, y revisión de previsualización con un presupuesto de aceptación establecido.
• Escala al modelo más capaz disponible con razonamiento alto solo para decisiones de seguridad o privacidad, evidencia ambigua o conflictiva, cambios de arquitectura, fallos de fidelidad inexplicados o recuperación después de que un modelo más pequeño haya fallado. Usa razonamiento extra alto solo cuando esa complejidad siga siendo relevante.
• Vuelve a un nivel más rápido una vez que se resuelva la decisión incierta. Nunca reduzcas el modelo o el presupuesto de razonamiento para evitar una condición de parada, aviso de consentimiento, verificación de seguridad o confirmación humana requerida.

Enrutar la fuente

• Lee agents/browser-capabilities.md primero y enruta por capacidad verificada, no solo por el nombre de la aplicación.
• Trata “ShowKit este sitio”, “usa la página abierta en Chrome” y solicitudes cortas equivalentes como autorización para inspeccionar capacidades ya concedidas, seleccionar una nueva carpeta de salida, instalar el CLI de ShowKit compatible allí y construir una previsualización local. No son autorización para publicar, exponer contenido privado, realizar una acción que cambie el estado ni instalar Playwright opcional.
• Cuando la persona dé una URL HTTP o HTTPS y ChatGPT o Codex tenga Navegador o Chrome, lee agents/codex-browser.md y references/url-intake.md, luego usa el flujo de trabajo de navegador de OpenAI verificado en workflow.md.
• Cuando un código base o compilación estática esté disponible, usa el flujo de trabajo de fuente estática.
• La extracción de Chrome integrada de Claude no está disponible siempre que la capacidad instalada se ejecute en contexto de página y no proporcione un mundo de página aislado validado por el anfitrión. Lee agents/claude-browser.md, preserva el diagnóstico UnsupportedSurface y ejecuta inmediatamente su orden de recuperación automática.