wangjs-jacky/jacky-skills

HyperFrames Ops

Antes de responder preguntas relacionadas con el entorno, primero lee experience.local.md en el mismo directorio para obtener los hechos más recientes de esta máquina (comandos de proxy, instantáneas de versiones, historial de QA).

Cero: Por qué es necesaria una capa de Ops independiente

Las Skills de terceros suelen describir capacidades genéricas, sin poder prever la red, el proxy, las versiones de Node/FFmpeg, la caché de fuentes, el estado de inicio de sesión y la combinación de herramientas de cada máquina. Modificar directamente la Skill oficial provoca conflictos de actualización y mezcla los hechos locales con las instrucciones genéricas del upstream.

Por lo tanto, se separan las dos capas:

• Las Skills oficiales son la fuente de capacidad, que se mantienen actualizables y reemplazables.
• hyperframes-ops es la capa de adaptación local, que registra las mejores prácticas, las diferencias de compatibilidad, los modos de fallo y las soluciones verificadas.
• Ante problemas de creación: primero lee la Skill oficial; ante problemas de entorno, combinación, versión o adaptación local, lee esta skill.
• Cuando una actualización del upstream invalide una experiencia antigua, márcala como obsoleta en la experiencia local y vuelve a verificarla; no uses la experiencia antigua para sobrescribir el nuevo comportamiento.

Uno: Identidad del proyecto (hechos generalizados)

• HyperFrames es el proyecto oficial de código abierto de HeyGen: github.com/heygen-com/hyperframes, paquete npm hyperframes
• Posicionamiento: CLI que escribe composiciones de video en HTML, las renderiza a mp4 mediante headless Chrome (npx hyperframes)
• Requisitos del entorno: Node.js >= 22, FFmpeg

Dos: Mecanismo de distribución de las skills oficiales

• Las skills oficiales se mantienen y versionan junto con el CLI en el mismo repositorio; el manifest se encuentra en la raíz del repositorio: https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json
• Composición: conjunto principal (hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes) + conjunto de flujos de trabajo (general-video, slideshow, motion-graphics, music-to-video, pr-to-video, product-launch-video, website-to-video, faceless-explainer, talking-head-recut, embedded-captions, media-use, figma). La salida real de skills check es la referencia.
• Comandos de gestión:
  • npx hyperframes skills check — Compara versiones con el manifest
  • npx hyperframes skills update — Actualiza todas las skills instaladas y limpia las que han sido dadas de baja oficialmente
  • npx hyperframes init — Forza la sincronización de skills a la última versión (--skip-skills está actualmente deshabilitado oficialmente)
• Ubicación de instalación: global ~/.claude/skills/ (el CLI detecta automáticamente claude-code)
• Seguridad de nombres: La lógica de limpieza de skills update se basa en el archivo lock y determina el origen de pertenencia; solo elimina skills que provengan del repositorio oficial y hayan sido dadas de baja. Aunque esta skill comienza con hyperframes-, no pertenece al lock oficial, por lo que no será eliminada erróneamente por el actualizador oficial

Tres: Rutas de resolución de problemas

Síntoma	Ruta
skills check/update/init lanzan AbortError (fetchManifest timeout)	Problema de red: el CLI usa fetch nativo de Node para acceder a raw.githubusercontent.com; si la conexión directa falla, debe usar proxy. Lee experience.local.md para obtener el comando directo de esta máquina
Otros fallos de red de npx hyperframes	Igual que arriba; ten en cuenta que el fetch nativo de Node (undici) no lee por defecto la variable de entorno HTTP_PROXY; en Node 24+ se debe añadir NODE_USE_ENV_PROXY=1 (o --use-env-proxy)
Entorno de renderizado/vista previa anormal	npx hyperframes doctor, npx hyperframes browser para autodiagnóstico; verifica Node >= 22 y FFmpeg disponible
El comportamiento de la skill parece de una versión antigua	skills check para ver la diferencia de versión, skills update para igualar
Intercambio de token OAuth de heygen auth login --oauth falla (api2.heygen.com connection refused) o timeout de la biblioteca de canciones	el CLI de heyGen es un programa Go, reconoce las variables de entorno HTTP(S)_PROXY (al contrario que el fetch de Node, no requiere un interruptor adicional); en redes restringidas, todos los comandos de heyGen deben usar proxy. El servicio de callback OAuth solo vive 5 minutos y necesita un shell interactivo (si se lanza en segundo plano/nohup, fallará por no recibir callback). Los comandos de esta máquina están en experience.local.md
La fuente renderizada es incorrecta (el título se ensancha, se desborda del contenedor, lint/inspect da todo verde)	Las 18 fuentes integradas se descargan dinámicamente de la red en tiempo de ejecución (@fontsource → ~/.cache/hyperframes/fonts); si la descarga falla, se utiliza silenciosamente la fuente del sistema. Solución para redes restringidas: descargar woff2 dentro del proyecto y usar explícitamente @font-face autoalojado
Problemas de creación (cómo hacer composiciones, animaciones, parámetros de renderizado)	No es competencia de esta skill; ve a la tabla de rutas de la skill oficial hyperframes

Cuatro: Protocolo de escritura de experiencia

• Escribir en experience.local.md (privado de esta máquina, ignorado por .gitignore en este directorio): nuevos problemas encontrados y soluciones verificadas, instantáneas de versiones/estado de instalación (con fecha), comandos específicos de la máquina, hechos de proxy y red, historial de QA
• Escribir en este SKILL.md (con seguimiento en git, compartible): cambios en el mecanismo oficial (forma de distribución, semántica de comandos, lógica de limpieza), nuevas rutas de resolución de problemas generalizadas
• Criterio de decisión: si es válido en otra máquina → SKILL.md; si solo es válido en esta máquina → experience.local.md
• Cada vez que se invoca y se resuelve un problema relacionado con el entorno de HyperFrames, registra la conclusión según las capas anteriores, indicando la fecha.