Communitygithub.com

sandeshrajbhandari/hyperframes-instruct

Pesquise, instale e conecte blocos e componentes do registry em composições HyperFrames. Use antes de criar manualmente qualquer visual nomeado — sempre que um briefing, usuário ou storyboard mencionar um efeito, transição ou tratamento como scanlines CRT, glitch, aberração cromática, granulação, brilho suave, gráfico, janela de código/terminal, mapa ou explosão de confete — porque aproximadamente 400 itens hospedados já cobrem muitos deles e a busca os classifica sem precisar instalar nada, sem projeto e sem conta.

O que é hyperframes-instruct?

Esta skill capacita o agente a atuar como um gateway inteligente para o Registry HyperFrames, eliminando a necessidade de construir efeitos visuais do zero na maioria dos casos. Ela permite que o agente pesquise em um catálogo com cerca de 400 blocos e componentes usando consultas em linguagem natural (como 'scanlines CRT' ou 'gráfico de barras'), classifique os resultados localmente sem enviar dados, e instale os itens escolhidos. Após a instalação, a skill fornece snippets de código para conectar o item a uma composição hospedeira, incluindo atributos cruciais como `data-composition-src`, `data-composition-id`, `data-start` e `data-duration`. A skill também orienta o agente a relatar lacunas no catálogo (`hyperframes feedback --search-miss`) quando nenhum item encontrado atende à necessidade, melhorando o catálogo ao longo do tempo. Ela suporta os workflows da CLI `hyperframes`, incluindo `add`, `catalog` e `feedback`, e funciona em projetos independentes ou dentro de plugins HyperFrames.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sandeshrajbhandari/hyperframes-instruct/tree/HEAD/.agents/skills/hyperframes-registry

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Instalação do plugin: Antes de comandos de configuração ou atualização, siga as regras de execução do plugin quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.

Registry HyperFrames

O registry fornece blocos e componentes reutilizáveis instaláveis via hyperframes add <nome>.

  • Blocos — sub-composições independentes (com suas próprias dimensões, duração, timeline). Incluídos via data-composition-src em uma composição hospedeira.
  • Componentes — snippets de efeito (sem dimensões próprias). Colados diretamente no HTML de uma composição hospedeira.

Referência rápida

hyperframes add data-chart              # instalar um bloco
hyperframes add grain-overlay           # instalar um componente
hyperframes add captions                # instalar todos os blocos com a tag captions
hyperframes add shimmer-sweep --dir .   # direcionar um projeto específico
hyperframes add data-chart --json       # saída legível por máquina
hyperframes add data-chart --no-clipboard  # pular área de transferência (CI/headless)

Após a instalação, a CLI imprime quais arquivos foram escritos e um snippet para colar na sua composição hospedeira. O snippet é um ponto de partida — você precisará adicionar os atributos data-composition-id (deve corresponder ao ID interno da composição do bloco), data-start e data-track-index ao conectar blocos.

O valor posicional é resolvido primeiro como um nome exato de item. Se nenhum item corresponder e o valor for uma tag, o comando instala todos os blocos com essa tag. As dependências do registry são instaladas antes do item solicitado. hyperframes add funciona apenas para blocos e componentes; para exemplos, use hyperframes init <dir> --example <nome>.

Locais de instalação

Blocos são instalados em compositions/<nome>.html por padrão. Componentes são instalados em compositions/components/<nome>.html por padrão.

Esses caminhos são configuráveis em hyperframes.json:

{
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

Consulte install-locations.md para detalhes completos.

Conectando blocos

Blocos são composições independentes — inclua-os via data-composition-src no seu index.html hospedeiro:

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

Atributos principais:

  • data-composition-src — caminho para o arquivo HTML do bloco
  • data-composition-id — deve corresponder ao ID interno do bloco
  • data-start — quando o bloco aparece na timeline hospedeira (segundos)
  • data-duration — quanto tempo o bloco é reproduzido
  • data-width / data-height — dimensões do canvas do bloco
  • data-track-index — linha da timeline do Studio; apenas exibição. Use CSS z-index para camadas

Consulte wiring-blocks.md para detalhes completos.

Conectando componentes

Componentes são snippets — cole seu HTML na marcação da sua composição, seu CSS no bloco de estilo e seu JS no script (se houver):

  1. Leia o arquivo instalado (ex.: compositions/components/grain-overlay.html)
  2. Copie os elementos HTML para dentro da <div data-composition-id="..."> da sua composição
  3. Copie o bloco <style> para os estilos da sua composição
  4. Copie qualquer conteúdo <script> para o script da sua composição (antes do código da sua timeline)
  5. Se o componente expuser integração com timeline GSAP (veja o bloco de comentários no snippet), adicione essas chamadas à sua timeline

Consulte wiring-components.md para detalhes completos.

Descoberta

Use a CLI como superfície de descoberta principal. Pesquise por intenção antes de navegar: o registry contém mais itens do que você pode escanear visualmente, então listá-los e combiná-los por nomes ou tags é o caminho lento, e falha sempre que a escolha de palavras do autor difere da sua.

# Classificar todo o catálogo contra o que o beat deve fazer
npx hyperframes catalog --query "revelar um título uma linha por vez"
npx hyperframes add caption-clip-wipe

A pesquisa é local e não envia nada. Por padrão, classifica com base no vocabulário compartilhado com o nome, título e descrição do item, então só encontra itens que reutilizam suas palavras; --on-device classifica por significado, após um download único do modelo. Com --json, o envelope informa qual camada respondeu, então verifique isso em vez de assumir que uma classificação ocorreu.

Sempre consulte em inglês, independentemente do idioma do vídeo. O catálogo está escrito em inglês e ambas as camadas o indexam assim (o modelo on-device também é apenas em inglês). Uma consulta em outro script não produz termos pesquisáveis e não retorna nada. É fácil errar isso em um projeto japonês ou chinês, onde o briefing, as legendas e a narração estão todos nesse idioma e a consulta segue naturalmente: descreva o movimento em inglês, depois escreva o texto na tela no idioma que o vídeo precisar. Se uma consulta retornar Nenhuma palavra pesquisável na consulta, esta é a regra, não um componente faltando, e não vale um relatório de lacuna.

A instalabilidade é aplicada após a classificação, não antes: um nome que os vetores carregam mas que este registry não pode servir é removido dos resultados e contado em dropped, então um dropped diferente de zero significa que os dois são de gerações diferentes. Consulte /hyperframes-cli para a camada offline, os portões de consentimento e como atualizar um índice desatualizado.

Para navegar ou filtrar em vez de pesquisar:

npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly

O modo de tabela normal e --json apenas listam correspondências; instale um nome selecionado com hyperframes add <nome>. --human-friendly abre um seletor interativo e instala o item selecionado imediatamente. Em workflows CI ou de agente, prefira --json seguido de um add explícito.

Relatar o que o catálogo não tem

Quando a pesquisa retornar e nada nela atender à necessidade, informe antes de criar o movimento manualmente:

npx hyperframes feedback --search-miss "<a consulta que você executou>" --wanted "<o movimento que você precisava>" --tier <a camada que respondeu>

catalog --query imprime esta linha para você, pré-preenchida, e --json a carrega como report_gap — então ela já está em mãos no momento em que você decide que nada se encaixa.

Relate sempre que nada nos resultados atender à necessidade, em qualquer camada. Não espere que a camada on-device tenha respondido: ela precisa de um download consentido de 33 MB, então uma execução de agente está em words a menos que tenha optado explicitamente, e condicionar a on-device silenciaria quase todos os relatos. O valor --tier acompanha para que uma falha de vocabulário permaneça distinguível de uma falha de significado quando forem lidos. Descreva o efeito que você queria, não o nome do item que imaginou: o que retorna é uma lista de movimentos que valem a pena construir, e um relatório nomeando um item inexistente não ensina nada. Este é o único caminho que envia uma consulta para qualquer lugar, que é exatamente por que é um comando deliberado separado, em vez de algo que a pesquisa faz sozinha. Ele não carrega classificação e nunca entra na métrica de classificação.

Este é o único sinal de demanda para o catálogo. Pulá-lo significa que a lacuna que você encontrou será adivinhada a partir de contagens de instalação, que não podem ver um movimento que ninguém conseguiu instalar.

Se a CLI não conseguir alcançar o registry configurado, inspecione o manifesto bruto como fallback:

curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

Um registry que a CLI não consegue alcançar não esvazia o catálogo para descoberta: um manifesto buscado anteriormente continua servindo por mais 24h além da janela de atualização sempre que a revalidação falha, então catalog e catalog --query ainda listam e classificam com base na última cópia em disco.

add ainda precisa da rede, mesmo para um item que você instalou ontem. Apenas manifestos são armazenados em cache; os arquivos reais do item são buscados a cada instalação. Então offline você pode pesquisar e ver o que um item é, mas instalá-lo falha na busca do arquivo. Não prometa a um usuário uma instalação offline.

Cada registry-item.json contém: nome, tipo, título, descrição, tags, dimensões (apenas blocos), duração (apenas blocos) e lista de arquivos.

Consulte discovery.md para detalhes sobre filtragem por tipo e tags.

Contribuindo com um novo bloco ou componente

Para criar UM NOVO item do registry (estilo de legenda, bloco VFX, transição, terço inferior, ou um componente reutilizável) e enviá-lo como um PR upstream — não instalar um existente — siga o fluxo completo ideia → scaffold → construir → validar → pré-visualizar → enviar em contributing.md. Modelos iniciais copiáveis (legenda / VFX / componente / registry-item.json) estão em templates.md.

Individual skills in this repo

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

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

sandeshrajbhandari/hyperframes-instruct

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, history, clean, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

sandeshrajbhandari/hyperframes-instruct

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

sandeshrajbhandari/hyperframes-instruct

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

sandeshrajbhandari/hyperframes-instruct

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

sandeshrajbhandari/hyperframes-instruct

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

sandeshrajbhandari/hyperframes-instruct

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

sandeshrajbhandari/hyperframes-instruct

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

sandeshrajbhandari/hyperframes-instruct

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

Habilidades Relacionadas