Communitygithub.com

kitfunso/claude-config

Instale, descubra e conecte blocos/componentes do registro HyperFrames. Use para hyperframes add, catalog, index.html wiring, hyperframes.json.

O que é claude-config?

Esta skill capacita agentes de IA a interagir com o registro HyperFrames, um catálogo de blocos e componentes reutilizáveis para composições de vídeo. Ela permite que agentes instalem estes itens via CLI, descubram o que está disponível através de pesquisa semântica ou filtragem, e conectem corretamente os blocos e componentes em arquivos index.html de composições hospedeiras. A skill suporta a estrutura completa do HyperFrames: blocos (sub-composições independentes) e componentes (trechos de efeito), com tratamento adequado de atributos como data-composition-src, data-start e data-track-index. Projetada para plataformas como Claude Code, Cursor e Codex, ela automatiza todo o fluxo de trabalho, desde a descoberta de itens relevantes até a instalação e integração no HTML, garantindo que agentes possam montar cenas de vídeo de forma eficiente sem intervenção manual.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kitfunso/claude-config/tree/HEAD/skills/hyperframes-registry

Perguntar na sua IA favorita

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

Documentação

HyperFrames Registry

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

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

Referência rápida

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

Após a instalação, a CLI imprime quais arquivos foram gravados e um trecho para colar na sua composição hospedeira. O trecho é 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 registro 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"
  }
}

Veja 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 — por quanto tempo o bloco é reproduzido
  • data-width / data-height — dimensões do canvas do bloco
  • data-track-index — ordenação de camadas (maior = na frente)

Veja wiring-blocks.md para detalhes completos.

Conectando componentes

Componentes são trechos — cole seu HTML na marcação da 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 do <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 timeline)
  5. Se o componente expõe integração com timeline GSAP (veja o bloco de comentário no trecho), adicione essas chamadas à sua timeline

Veja wiring-components.md para detalhes completos.

Descoberta

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

# Classifique todo o catálogo contra o que o beat deve fazer
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe

A pesquisa é local e não envia nada. Por padrão, ela classifica pelo 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 pelo significado, após um download único do modelo. Com --json, os envelopes indicam qual nível 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á em inglês e ambos os níveis o indexam dessa forma (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. Isso é fácil de errar 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 naturalmente o segue: 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, isso é esta regra, não um componente faltando, e não vale a pena um relatório de lacuna.

A instalabilidade é aplicada após a classificação, não antes: um nome que os vetores carregam mas este registro não pode servir é removido dos resultados e contado em dropped, então dropped diferente de zero significa que os dois são de gerações diferentes. Veja /hyperframes-cli para o nível offline, as portas 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

A tabela normal e os modos --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 fluxos de trabalho CI ou de agente, prefira --json seguido por um add explícito.

Relate o que o catálogo não possui

Quando a pesquisa retornar e nada nela fizer o trabalho, diga isso antes de criar manualmente o movimento:

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

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 fizer o trabalho, em qualquer nível. Não espere o nível on-device ter respondido: ele 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 depender de 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 estes 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 por conta própria. Ele não carrega nenhuma classificação e nunca chega à métrica de avaliação.

Este é o sinal de demanda completo 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 conseguem ver um movimento que ninguém pôde instalar.

Se a CLI não conseguir acessar o registro configurado, inspecione o manifesto bruto como fallback:

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

Um registro que a CLI não consegue acessar não esvazia o catálogo para descoberta: um manifesto previamente buscado continua servindo além de sua janela de atualização de 24h 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 de um item contém: nome, tipo, título, descrição, tags, dimensões (apenas blocos), duração (apenas blocos) e lista de arquivos.

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

Contribuindo com um novo bloco ou componente

Para criar um NOVO item de registro (estilo de legenda, bloco VFX, transição, lower third, ou um componente reutilizável) e enviá-lo como um PR upstream — não instalar um existente — siga o fluxo de trabalho completo de ideia → scaffold → construção → validação → pré-visualização → envio em contributing.md. Modelos iniciais copiáveis (legenda / VFX / componente / registry-item.json) estão em templates.md.

Habilidades Relacionadas