Communitygithub.com

Zuhair-01/claude-skills-and-systems

El contrato de composición HyperFrames: construye un proyecto renderizable. Útil para estructura de composición, atributos de temporización `data-*`, `class="clip"`, pistas, subcomposiciones, variables, reproducción de medios gestionada por el framework, reglas de render determinista y validación. Léelo antes de escribir HTML de composición.

¿Qué es claude-skills-and-systems?

Este skill define el contrato técnico completo para construir composiciones en HyperFrames, un framework que renderiza video a partir de HTML. Detalla desde la estructura básica (composición independiente vs subcomposición) hasta reglas no negociables de determinismo, pasando por la gestión de medios, variables y pistas de animación. Soporta múltiples plataformas (CLI, Studio) y runtimes de animación (GSAP, Lottie, Three.js). Incluye una tabla de referencias para profundizar en patrones de composición, atributos `data-*`, recetas de edición y reglas de render. Proporciona pautas críticas para evitar errores silenciosos, como conflictos con `transform` CSS y GSAP, anidamiento incorrecto de `data-start`, o la falta de un timeline pausado único. También cubre la validación mediante `npx hyperframes check` y el flujo de trabajo completo (storyboard, revisión, render). Esencial para cualquier desarrollador que quiera crear proyectos renderizables con HyperFrames sin caer en trampas comunes.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Zuhair-01/claude-skills-and-systems/tree/HEAD/skills/hyperframes-core

Preguntar en tu IA favorita

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

Documentación

HyperFrames Core

Trampas para agentes (léase primero):

  • Centrar con flex/inset, no con CSS transform: translate(-50%,-50%) en un nodo al que luego se aplique GSAP x/y. Lint: gsap_css_transform_conflict. Usa fromTo o xPercent/yPercent.
  • No añadas un tl.set(..., {visibility:"hidden"}) de salida de escena. El runtime ya oculta los clips temporizados. Los fundidos de opacidad en nodos internos (o opacity en .clip) son suficientes. Las eliminaciones forzadas de subtítulos siguen otra regla.
  • window.__timelines["id"] debe coincidir con el data-composition-id raíz.
  • Después de render, lee la segunda línea del resumen: beginframe vs screenshot, modo GPU, tiempos de etapa. screenshot + software gpu en Linux es la ruta lenta.

HyperFrames renderiza video a partir de HTML. Una composición es un archivo HTML cuyo DOM declara la temporización con atributos data-*, cuyo runtime de animación es buscable, y cuya reproducción de medios es gestionada por el framework.

Este skill es el contrato técnico — cómo construir un proyecto HyperFrames. El cuerpo siguiente es la guía de construcción; los detalles por tema viven en references/ (índice a continuación), léelos bajo demanda. Los documentos de proceso (brief, storyboard, revisión, producción, despacho, frame-worker) viven en /hyperframes → references/. Otros temas viven en los skills de dominio hermanos — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. El mapa de capacidades en /hyperframes detalla lo que cubre cada uno.

Referencias

ArchivoLéelo para…
references/minimal-composition.mdempezar con el esqueleto de composición renderizable más pequeño
references/composition-patterns.mdelegir entre monolítico vs modular; estructurar un index.html modular; escoger un arquetipo de subcomposición
references/data-attributes.mdbuscar cualquier data-* (raíz / clip / host de subcomp / alias legacy); usar class="clip"
references/tracks-and-clips.mdentender qué controla data-track-index (y qué no), z-index, temporizar un clip relativo a otro; lista cada pista y clip con npx hyperframes timeline
references/creator-editing-recipes.mdcopiar recetas veraces de cortar/recortar/reordenar/retemporizar/congelar/cámara/máscara/encadenamiento/edición de audio y sus límites
references/sub-compositions.mdcablear una subcomposición (atributos de host, <template>, variables por instancia) y animar dentro de ella
references/variables-and-media.mddeclarar variables; colocar <video>/<audio>, ajustar volumen, recortar
references/determinism-rules.mdconstruir una línea de tiempo buscable; prohibiciones de determinismo; diseño / ajuste de texto
references/full-screen-motion.mdcrear movimiento a pantalla completa con fondos compartidos
references/tailwind.mdtrabajar en un proyecto Tailwind v4 (init --tailwind; el contrato en tiempo de ejecución difiere del v3 de Studio)

Para detalles específicos del runtime de animación (API de GSAP, Lottie, Three.js, etc.) ve a hyperframes-animation → adapters/<runtime>.md.

Construir una composición

Dos formas raíz (no intercambiables)

  • Independiente (index.html de nivel superior): el <div data-composition-id="…"> raíz va directamente en <body>, sin envoltorio <template>. Envolver una raíz independiente oculta todo el contenido y lint lo rechaza (standalone_composition_wrapped_in_template, error).
  • Subcomposición (cargada vía data-composition-src): envuelve la raíz en <template>. Esta es la forma a escribir: el cargador también acepta un documento completo y recurre a su <body>, pero la forma con template es la que asumen los ejemplos y las herramientas.

⚠ Regla de transporte: para una subcomposición con template, el ensamblador descarta el <head> <style>/<script> del archivo (packages/core/src/compiler/compositionAssembly.ts, por la puerta hasTemplate), así que coloca <style>/<script> dentro del template. <link> se eleva de cualquier forma. ⚠ Convención de id de host: dale al slot del host, al template interno y a la clave window.__timelines["<id>"] el mismo id. Se soporta un id local diferente (el ensamblador recurre a la primera raíz en el archivo), pero el desajuste es silencioso, así que hazlos coincidir a menos que tengas una razón para no hacerlo.

Forma del archivo, cableado del host y lista de verificación previa al render → references/sub-compositions.md.

La raíz debe tener tamaño (bug de diseño silencioso)

La raíz independiente usa width/height: 100%. El tamaño del lienzo es data-width/data-height. El runtime imprime esos píxeles en la raíz de la composición. No codifiques 1920px/1080px en #root. Esqueleto → references/minimal-composition.md.

Una línea de tiempo pausada

Cada composición registra exactamente una gsap.timeline({ paused: true }) en window.__timelines["<id>"] (clave = data-composition-id raíz). Se permite construirla dentro de un callback asíncrono (document.fonts.ready); lo importante es que registres solo después de que la construcción termine. La duración del render es el data-duration raíz, no la longitud de la línea de tiempo: una línea de tiempo que se extiende más allá se corta, y una que termina antes mantiene su último fotograma. Omite el data-duration raíz y la duración se infiere (línea de tiempo, ventana de medios o adaptador). No necesitas window.__timelines = window.__timelines || {}: el runtime crea el registro antes de que se ejecuten tus scripts en línea, y lint ya no lo pide. No anides manualmente subtl en el host; el runtime anida automáticamente las líneas de tiempo hijas registradas. Contrato completo (incl. runtimes no GSAP) → references/determinism-rules.md + hyperframes-animation/adapters/.

Errores de lint de primera pasada (fallo garantizado en el primer build)

Reglas que lint sí detecta, pero solo después de los hechos. Escríbelas correctamente la primera vez:

  • Nunca combines un transform CSS inicial con un tween de GSAP en la misma propiedad — el valor CSS y el inicio del tween entran en conflicto y lint lo rechaza con gsap_css_transform_conflict. Establece el estado inicial dentro del tween con gsap.fromTo(el, { x: -40 }, { x: 0 }) en lugar de un CSS transform: translateX(-40px).
  • Nunca pongas crossorigin en <video>/<audio>. lint lo rechaza incondicionalmente con media_crossorigin_breaks_preview (error), incluso para lectura de canvas/WebGL/WebAudio. No hay supresión.
  • Nunca des a un <video data-start> un ancestro que también tenga data-start. lint lo rechaza con video_nested_in_timed_element (error). Temporiza el envoltorio o el video, no ambos.
  • Cada <audio> necesita un id. lint lo rechaza con media_missing_id, y un <audio> sin id nunca es recogido por el mezclador, por lo que el render es silencioso.
  • Nunca hagas tween a un .clip con autoAlpha o visibility — lint lo rechaza con gsap_animates_clip_element. Anima un elemento hijo en su lugar.
  • Una font-family CSS con nombre necesita un @font-face en el archivo que apunte a un archivo local enviado, o lint dispara font_family_without_font_face.
  • La #root de una subcomposición usa width/height: 100% (o inset: 0), no valores fijos 1920px/1080px. El tamaño del lienzo es data-width/data-height.

Un error de lint también desactiva las auditorías de diseño y contraste: check entonces informa 0 sample(s) y 0/0 text checks, que se lee como un archivo limpio pero significa que no se ejecutó nada. Limpia los errores de lint antes de confiar en esos números.

Reglas no negociables (errores silenciosos que las puertas automáticas pueden pasar por alto)

Se exponen aquí; la justificación completa está en la referencia enlazada. No violes:

  • Sin relojes en tiempo de render / Math.random sin semilla / red / estado de entrada; sin repeat: -1 (usa un recuento finito). → determinism-rules.md
  • Nunca hagas tween a display, visibility o autoAlpha en un elemento .clip. El framework es dueño de la visibilidad del clip, y lint lo rechaza (gsap_animates_clip_element). Anima un hijo. → determinism-rules.md
  • Sin <br> en el texto del cuerpo; los elementos transformados deben ser de nivel de bloque + con tamaño; los elementos decorativos absolutos pulsantes necesitan espacio máximo. → determinism-rules.md
  • <video>/<audio> se encuentran mediante una consulta plana del documento, por lo que el framework los busca y decodifica a cualquier profundidad de anidamiento (incluyendo dentro del <template> o envoltorio de una subcomp). Un límite firme: lint da error si un <video data-start> está dentro de otro elemento simple que también tiene data-start, y el fallo es real (fotogramas fuente incorrectos, luego el clip desaparece a medio slot), así que pon la temporización en el envoltorio o en el video, nunca en ambos. Los hosts de subcomposición están exentos: los medios dentro de una subcomposición se renderizan correctamente. La otra advertencia son las líneas de tiempo, no la colocación: una línea de tiempo de subcomp no puede animar elementos raíz del host. → variables-and-media.md
  • Mantén cada id único en toda la página ensamblada (prefija los ids de subcomp con el id de la composición, #<id>-hero) para que tus propios CSS #id y llamadas getElementById resuelvan. La inyección de fotogramas ya no depende de ello: el compilador imprime un data-hf-render-id único en el documento en cada video[src]/audio[src]/img[src]. Los medios que usan hijos <source> en lugar de un atributo src no reciben la marca, por lo que los ids únicos siguen siendo importantes allí. → composition-patterns.md
  • Un relleno a pantalla completa en la raíz de la composición está bien en un render normal. Solo se elimina en la ruta de composición en capas (contenido HDR, o una composición que usa transiciones de shader), donde el motor fuerza transparente cada raíz de composición para que la capa inferior se vea. Si tu composición usa transiciones de shader o medios HDR, pon el relleno en un hijo a sangre (position:absolute; inset:0). → composition-patterns.md

Editar composiciones existentes

  • Lee primero los archivos. Preserva la temporización, pistas, IDs, variables y rutas de medios no relacionados.
  • Para saber qué hay en la línea de tiempo de un proyecto (pistas, clips, inicios, fines, qué se reproduce), ejecuta npx hyperframes timeline [--json] en lugar de leer index.html y cada archivo de subcomposición.
  • Coincide con los IDs de composición y las claves de línea de tiempo existentes.
  • Al añadir un clip: establece data-start/data-duration intencionadamente en relación con los clips circundantes. data-track-index es un carril de visualización de Studio, no una restricción de temporización, por lo que no necesita estar libre.
  • data-hidden en cualquier elemento de la composición lo oculta tanto en la vista previa como en el render, anulando su ventana de tiempo; es no destructivo/reversible y se activa/desactiva mediante el icono de ojo de la línea de tiempo de Studio.
  • Al añadir una subcomposición: verifica su data-composition-id interno antes de cablear el host.

Validación

Usa hyperframes-cli para detalles de comandos

  • npx hyperframes check pasa (0 hallazgos en lint, runtime, diseño, movimiento y contraste)
  • Proyectos con subcomposiciones: npx hyperframes snapshot --at <midpoints> y revisa visualmente cada fotograma
  • npx hyperframes preview --background para revisión (el usuario puede editar cualquier cosa en la línea de tiempo de Studio, y el servidor sobrevive al comando invocador)
  • npx hyperframes render solo después de la aprobación del usuario

Individual skills in this repo

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

Zuhair-01/claude-skills-and-systems

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Zuhair-01/claude-skills-and-systems

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Zuhair-01/claude-skills-and-systems

Edit existing videos using AI — remix style, upscale, remove background, and add audio via fal.ai's hosted video models.

Zuhair-01/claude-skills-and-systems

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Zuhair-01/claude-skills-and-systems

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

Zuhair-01/claude-skills-and-systems

Read-only queue dashboard for workspace-aware ship. (gstack)

Zuhair-01/claude-skills-and-systems

Generate HeyGen presenter videos via the v3 Video Agent pipeline — handles Frame Check (aspect ratio correction), prompt engineering, avatar resolution, and voice selection. Required for any HeyGen video generation. Replaces deprecated endpoints with v3. Use when: (1) generating any HeyGen video (via API or otherwise), (2) sending a personalized video message (outreach, update, announcement, pitch, knowledge), (3) creating a HeyGen presenter-led explainer, tutorial, or product demo with a human face, (4) "make a video of me saying...", "send a video to my leads", "record an update for my team", "create a video pitch", "make a loom-style message", "I want to appear in this video", "generate a HeyGen video", "make a talking head video". Accepts avatar_id from heygen-avatar for identity-first HeyGen videos, or uses a stock presenter. Returns video share URL + HeyGen session URL for iteration. Chain signal: when the user wants to create/design an avatar AND make a video in the same request, run heygen-avatar f...

Zuhair-01/claude-skills-and-systems

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Zuhair-01/claude-skills-and-systems

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

Skills relacionados