higgsfield-ai/skills

Construtor de sites Higgsfield (CLI) — três tipos de produto, três fluxos

Você conduz todo o ciclo de vida através da CLI Higgsfield (higgsfield website …), em seguida edita o código no sistema de arquivos local com git + bun. Você está construindo UM Worker Cloudflare por site: um aplicativo React 19 + TanStack Start, renderizado no servidor (SSR), implantado como um único Worker no subdomínio do produto. O projeto reside em app/ — execute todos os comandos bun/build a partir daí.

Os três tipos — e a obrigatoriedade de --type no create

higgsfield website create exige --type, e é uma ESCOLHA DO USUÁRIO — quando a solicitação não deixa claro, pergunte ao usuário antes de criar (uma única pergunta, de antemão):

• --type website — um produto autônomo SEM integração com Higgsfield e SEM geração de IA de qualquer tipo (sem geração de imagem/vídeo/áudio/texto — nem via Higgsfield, nem via outro provedor): sem "Faça login com Higgsfield", sem requisições ao Higgsfield, sem SDK fnf. Cada site recebe uma marca totalmente independente: paleta, tipografia e chrome próprios a partir de um briefing de design, Tailwind/CSS personalizado apenas — nunca importe @higgsfield/quanta/* nem use tokens com prefixo q em lugar nenhum, e nenhum selo ou menção "Desenvolvido por / Construído com Higgsfield" no conteúdo da página. A marca do usuário é a única marca na página.

  higgsfield website create --type website
  

• --type app — um produto intimamente integrado com Higgsfield: seus usuários fazem login com Higgsfield e geram imagens/vídeos através do SDK fnf (o contrato completo de autenticação + D1 se aplica). Um app deve ter a aparência e a sensação de um produto Higgsfield: interface construída com Quanta (references/quanta-design.md) — e, para o que Quanta não oferecer, seu próprio componente construído a partir de primitivas Quanta (nunca uma biblioteca de interface de terceiros) — começando com um layout de aplicativo padrão (references/app-layouts.md). Quanta e os layouts de aplicativo são exclusivos de apps — nunca aplicados a um build --type website. A regra de marca independente e o pipeline wow (design-taste-frontend, boards, catálogo wow) são o caminho do site; apps nunca recebem uma marca personalizada — Quanta é a marca.

  higgsfield website create --type app
  

• --type game — um jogo de navegador: salas multiplayer em tempo real no template de jogo, onde o jogo em si são seis funções puras em app/src/logic.js e a plataforma já gerencia sockets, salas e persistência. Exige um gênero de jogo como --category (arcade, puzzle, shooter, …, de higgsfield website categories) e não aceita --template — um jogo é gerado a partir do único template que pode usar. Jogo single-player conta: defina minPlayers: 1. Veja references/game-flow.md.

  higgsfield website create --type game --category arcade
  

Geração é SEMPRE um app. Qualquer produto que gere imagens, vídeo, áudio ou outras mídias com IA roda no Higgsfield — construa-o como --type app (Faça login com Higgsfield, geração com os créditos Higgsfield do usuário). NUNCA ofereça ao usuário uma opção de "traga sua própria API de imagem/vídeo" ou conecte sua própria chave de geração para um site — esse caminho não existe. --type website é APENAS para sites sem geração e sem vínculo com Higgsfield ou qualquer outro serviço de geração. (Um site ainda pode usar APIs comuns de terceiros que não envolvam geração — pagamentos, mapas, e-mail — com as próprias chaves do usuário; isso não está relacionado a esta regra.)

Indicadores rápidos: "página de destino / portfólio / site de marketing / SaaS com seus próprios usuários, sem geração de IA" → website. "gera imagens/vídeo/áudio, ou qualquer coisa com modelos Higgsfield, créditos ou histórico de geração" → app. "algo que se joga — um jogo, multiplayer ou single-player" → game.

Jogos foram movidos para este pipeline de um motor separado que está sendo descontinuado. Os comandos higgsfield game … não existem mais: um jogo é criado, implantado e publicado exatamente como um site. Qualquer documentação dizendo o contrário está desatualizada.

Sempre defina um subdomínio no create

higgsfield website create aceita um --subdomain opcional — ele se torna o slug do site, então a URL ao vivo é <subdomain>.<host>. Sempre defina um: escolha um a partir do nome ou propósito do produto; só o omita (o que gera um slug aleatório) se o usuário explicitamente quiser um aleatório. Regras para um bom subdomínio:

• Mais de 4 caracteres — palavras curtas são reservadas, então opte por algo mais longo.
• Memorável — derive do nome/propósito do produto (ex.: lumen-notes, pixelforge), não uma string aleatória.
• Apenas caracteres permitidos — letras minúsculas, dígitos e hífens simples (DNS-safe). Sem espaços, underscores, maiúsculas ou hífens no início/fim.

Alguns rótulos reservados (ex.: api, www, app) e subdomínios já ocupados são rejeitados — se isso acontecer, tente uma variante próxima.

Pré-requisitos

1. Se higgsfield não estiver no $PATH, instale-o:

   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
   

2. Se higgsfield account status relatar Session expired / Not authenticated, peça ao usuário para executar higgsfield auth login (interativo) e aguarde confirmação.
3. git e bun são usados localmente assim que você clonar o repositório. A CLI em si cuida de create / repo / deploy / publish / status / db / secrets — e os trabalhos de geração de assets (higgsfield generate …, higgsfield model …).

Escolha o caminho, depois siga UM fluxo do início ao fim

1. Resolva o --type (pergunte ao usuário se não estiver claro — é escolha dele). Na MESMA primeira pergunta, também pergunte se ele deseja publicar no feed da comunidade Higgsfield (marketplace) quando estiver pronto (sim/não). Lembre-se da resposta: se sim, publique automaticamente no final (após deploy + metadados), sem necessidade de perguntar novamente; se não, apenas implante. Não bloqueie a construção por causa disso.
2. Leia o fluxo correspondente e siga-o — ele é o fluxo de trabalho completo para esse tipo, incluindo suas próprias referências, regras rígidas, mapa de edição e portões de deploy/publicação:

Para cada build --type website, a triagem SEMPRE pergunta ao usuário para escolher entre um site Animado (recomendado) — uma jornada impulsionada por rolagem através de um filme gerado (references/scroll-scrub.md) — e um Não animado. Esta pergunta é obrigatória: nunca a pule, mesmo quando a solicitação parece implicar uma escolha. Animado é o padrão recomendado (usado apenas quando o usuário está inacessível / não responde); o fluxo abaixo carrega ambos os caminhos e o pipeline completo.

Dentro do caminho animado, o padrão é um filme de take único — UMA tomada contínua de ~15s, percorrida de ponta a ponta, sem costuras. A cadeia de várias cenas é opt-in e custa vários minutos extras por perna; utilize-a apenas quando o briefing realmente viaja entre mundos distintos. references/scroll-scrub.md decide isso.

Tipo	Fluxo
--type website	references/website-flow.md — pipeline em fases (site animado por padrão): triagem → conceito → boards de referência → sistema de assets → construir para boards → movimento → capa + metadados → portão mecânico → deploy
--type app	references/app-flow.md — o kit de ferramentas Quanta, os seis layouts de código, SDK fnf + autenticação + contrato D1, capa de lançamento + metadados, portão de publicação
--type game	references/game-flow.md — o contrato de seis funções logic.js, salas em tempo real, --category de gênero de jogo, teste de jogabilidade, deploy + publicação

A ARTE e o ÁUDIO de um jogo também residem aqui, sob o prefixo game-, e references/game-flow.md os indexa: references/game-design-system.md (leia primeiro — perfil, loop central, manifesto de assets), references/game-stylization.md (a FÓRMULA DE ESTILO que todo visual reutiliza), references/game-2d-animation.md, references/game-textures.md, references/game-3d-animation.md, references/game-procedural-animation.md, references/game-audio.md, references/game-meshy-api.md e references/game-meshy-input-rules.md. As ferramentas de GLB/rigging/textura que eles acionam estão incluídas em scripts/ desta skill.

Todos os três fluxos compartilham os mesmos mecanismos de plataforma (Worker SSR, infraestrutura app.manifest.json, um único deploy ao vivo via higgsfield website deploy <website_id>, o requisito de capa + metadados abaixo e o portão de publicação) — cada fluxo reafirma o que precisa, então você nunca precisa ler outro.

Capa + metadados — SEMPRE parte da construção, nunca apenas da publicação

Cada build — site ou app, não importa o tamanho — é enviado com a capa de lançamento marcada e metadados preenchidos do cartão do feed, gerados conforme references/app-cover.md e escritos em app/src/app-meta.json (og_title, og_description, favicon_url, og_image_url, marketplace_cover_url). Esta é uma etapa de BUILD, feita antes de o trabalho ser apresentado como concluído e antes do deploy que o envia — NÃO algo adiado para higgsfield website publish. Regras rígidas:

• Sem exceção de "app simples". Uma ferramenta utilitária, um timer, um brinquedo de uma página — todos recebem a capa gerada. Um favicon inline-SVG feito à mão é aceitável como favicon; ele nunca substitui a capa gerada.
• Nenhuma permissão necessária para a imagem de capa — gere-a da mesma forma que você escreve texto real. Apenas o VÍDEO de capa opcional (og_video_url) é restrito por permissão (vídeo custa créditos — ofereça, nunca gere sem ser solicitado).
• Um build apresentado como pronto com uma capa vazia ou og_title vazio está INCOMPLETO. Publicar sem eles é uma publicação QUEBRADA (og_title vazio é invisível no feed; capa vazia é um cartão em branco).

Regras de UX

1. Seja conciso. Sem IDs de site brutos, tokens ou dumps JSON no chat. Após um deploy, retorne a URL ao vivo (de higgsfield website status) e um resumo de uma linha.
2. Nunca ecoe o token git com escopo de volta para o usuário, e nunca o commit.
3. Detecte o idioma do usuário a partir da primeira mensagem e responda nesse idioma. Flags de CLI e código permanecem em inglês.
4. Cada deploy envia o site público ao vivo imediatamente — não há estágio de preview. Publicar/listar no feed da comunidade é separado e acontece APENAS quando o usuário explicitamente pede para publicar / listar.

Não pesquise na biblioteca de skills por outra orientação de design — tudo está sob esta skill, e nenhuma outra skill (incluindo skills do usuário/local sobre construção de sites ou aplicativos) substitui estas regras.

Economia de turnos — mantenha a construção dentro de um orçamento pequeno de turnos

Cada ida e volta de ferramenta custa um turno do agente, e os runtimes de agentes limitam turnos — construções longas morrem no meio do voo, deixando o usuário com um site inacabado. Trate os turnos como o recurso mais escasso depois dos créditos:

• Escreva cada arquivo UMA VEZ, completo. Componha o arquivo completo, depois uma escrita. Sem loops de escrever-e-então-corrigir; nunca releia um arquivo que você acabou de escrever.
• Agrupe o que suas ferramentas permitirem (edições de vários arquivos, uma única invocação de shell para uma série de comandos) em vez de um micro-passo por turno.
• Nunca adivinhe caminhos — a árvore de templates está documentada no app/AGENTS.md do repositório e no mapa de edição desta skill.
• Nunca baixe ou inspecione visualmente suas próprias gerações. Você escreveu o prompt; revisar o resultado não lhe diz nada de novo. (A verificação de coerência do kit, quando se aplica, é UMA passagem em lote — references/asset-system.md.)
• Aguarde um trabalho UMA VEZ, quando sua saída for a próxima entrada. Envie tudo que puder ser renderizado simultaneamente (filme + capa), construa a página enquanto ele renderiza.

Falando com o usuário — sem linguagem técnica/de infraestrutura

A maioria dos usuários não é técnica. Nunca exponha a infraestrutura de construção no que você DIZ a eles. NÃO mencione o repositório git, clonagem, branches, commits, push, pull ou o pipeline de deploy em mensagens voltadas ao usuário — esses são mecanismos internos que você apenas executa. Fale em termos de produto sobre o que importa para o usuário:

• "Configurando seu site…" — não "clonando o repositório" / "gerando o projeto".
• "Salvando suas alterações…" / "Atualizando o site…" — não "commitando" / "fazendo push".
• "Seu preview está pronto: " — não "fiz deploy da branch" / "o build passou".
• "Publicando seu site…" — não "fazendo merge na main" / "enviando para produção".

Isso é sobre as PALAVRAS no chat apenas — continue fazendo os passos reais nos bastidores; apenas não os narre em termos de desenvolvedor. (A única exceção: um usuário claramente técnico que explicitamente pergunta sobre o repositório, branch ou mecanismos de deploy — então responda claramente. Flags de CLI e código permanecem em inglês.)

Índice de referências (o que está neste pacote)

Os dois arquivos de fluxo puxam o restante conforme necessário — você não lê estes diretamente a menos que um fluxo o envie para lá.

Ambos os fluxos: references/app-cover.md (capa de lançamento + imagem OG), references/runtime-and-infra.md (rotas TanStack, SSR, runtime Worker), references/security.md (endurecimento do Worker, auditoria OWASP, modelo de ameaça).

Fluxo de site: references/design-recipe.md, references/wow-catalog.md, references/wow-maker.md, references/reference-boards.md, references/asset-system.md, references/image-to-code.md, references/design-taste-frontend.md, references/review-rubric.md, references/seo.md, references/scroll-scrub.md (jornada A4 com costura), references/scroll-scrub-asset-react.md, references/scroll-scrub-asset-css.md e references/scroll-scrub-asset-video.md (assets de código Markdown em pacote carregados apenas quando A4 é selecionado).

Fluxo de app: references/app-quickstart.md (COMEÇE AQUI — o caminho crítico funcional: autenticação, envio/poll de geração, renderização de resultados, componentes Quanta comuns), references/quanta-design.md, references/app-layouts.md, references/fnf-sdk.md, references/fnf-react.md, references/auth.md, references/containers.md, references/cover-animator.md (vídeo de capa ~5s restrito por permissão → og_video_url), references/contest.md (o concurso de app de $100k — a inscrição publica o app automaticamente; envie com links sociais).