alt — Legenda Automática
Executa um VLM local sobre cada imagem em input_dir e grava um arquivo JSON auxiliar em output_dir. Útil para gerar legendas automaticamente, entender o conteúdo de um lote de imagens sem revisão manual ou alimentar descrições em outras ferramentas.
O diretório da habilidade (onde este SKILL.md está localizado) é referido como $SKILL_DIR abaixo.
Quando Usar
Use esta habilidade quando o usuário quiser:
- Gerar legendas automáticas para Instagram a partir de fotos
- Entender o que há em um lote de imagens sem revisá-las manualmente
- Alimentar descrições de imagens em um pipeline de conteúdo ou ferramenta de agendamento
Configuração (apenas na primeira execução)
cd "$SKILL_DIR" && uv sync
Os pesos do moondream2 são baixados na primeira utilização (~4 GB do HuggingFace). Os pesos do Phi-4 são maiores (~8 GB) e exigem GPU.
Fluxo de Trabalho do Agente
1. Pergunte ao usuário
Antes de descrever as imagens, preciso saber:
🧠 Modelo
- moondream2 — 2B parâmetros, rápido, funciona em CPU (padrão)
- phi4 — 3.8B multimodal, maior qualidade, requer GPU
💬 Estilo da legenda (opcional — usarei um padrão sensato)
Ex.: "Casual e divertido com emojis" ou "Profissional e inspirador"
⚙️ Dispositivo
- auto — GPU se disponível, senão CPU (padrão)
- cpu — apenas moondream2; ~7s/imagem em uma CPU de desktop moderna
📁 Diretórios de entrada / saída (padrão: ./input e ./output)
2. Edite config.json
Se o usuário definir um estilo de legenda, incorpore-o em prompt_caption.
Exemplo: "Escreva uma legenda divertida e rica em emojis para Instagram para esta imagem. Inclua 3-5 hashtags."
Se o usuário solicitar visuais com marca, verifique skills/brand-manager/brand-assets/asset-manifest.json para fontes disponíveis e mencione a fonte da marca preferida na orientação da legenda gerada ou nas notas de transferência. Esta habilidade grava apenas JSON auxiliares, portanto não renderiza texto; renderizadores downstream como visual-hook, video-captioner e end-cta devem usar os arquivos de fonte da marca reais quando especificados e disponíveis.
3. Execute
cd "$SKILL_DIR" && uv run python scripts/describe.py --config config.json
A primeira execução baixa os pesos do modelo — avise o usuário que isso pode levar alguns minutos.
4. Relate os resultados
Mostre a descrição e a legenda para cada imagem. Informe ao usuário onde os arquivos JSON foram gravados.
Referência de Configuração
| Chave | Valores | Padrão | Descrição |
|---|---|---|---|
input_dir | caminho | ./input | Pasta de imagens de origem |
output_dir | caminho | ./output | Pasta de destino para JSON auxiliares |
model | moondream2, phi4 | moondream2 | Modelo de visão-linguagem |
prompt_description | string | "Descreva esta imagem em uma frase." | Prompt para o campo de descrição |
prompt_caption | string | "Escreva uma legenda envolvente para Instagram…" | Prompt para o campo de legenda |
device | auto, cpu, cuda | auto | Dispositivo de inferência |
Invocações Comuns
# Padrão (moondream2, dispositivo auto)
cd "$SKILL_DIR" && uv run python scripts/describe.py
# Qualidade superior (GPU necessária)
cd "$SKILL_DIR" && uv run python scripts/describe.py --model phi4
# Forçar CPU
cd "$SKILL_DIR" && uv run python scripts/describe.py --device cpu
# Prompt de legenda personalizado
cd "$SKILL_DIR" && uv run python scripts/describe.py \
--prompt-caption "Escreva uma legenda profissional para LinkedIn para esta imagem."
Saída
Para cada photo.jpg em input_dir, grava photo.json em output_dir:
{
"description": "Uma mulher em um café iluminado pelo sol segurando uma xícara de café.",
"caption": "Rituais matinais ☕✨ Começando o dia bem. #coffeetime #morningvibes #cafe",
"tags": ["retrato", "café", "interno", "luz quente"]
}
Quando fontes de marca forem relevantes, inclua o nome/tag da fonte nas instruções downstream em vez de incorporar um arquivo de fonte neste JSON. As habilidades de renderização são responsáveis por resolver o caminho do manifesto e aplicar a fonte.
Tratamento de Erros
phi4+cpu→ rejeitado na validação da configuração com uma mensagem clara- Falhas no download do modelo → exibidas com detalhes do erro do HuggingFace
- Erros individuais de imagem → registrados; outras imagens continuam
Inferência Remota
Esta habilidade suporta legendagem remota opcional preservando o mesmo formato de saída JSON auxiliar.
- O comportamento padrão continua sendo local
- Provedores remotos são opt-in apenas
- Provedores suportados:
huggingface,replicate
Chaves de Configuração
| Chave | Padrão | Notas |
|---|---|---|
provider | null | null, local ou none mantém o modo local |
remote_model | null | Opcional, substituição de modelo VLM específico do provedor |
hf_token_env | HF_TOKEN | Nome da variável de ambiente de autenticação do HuggingFace |
replicate_api_key_env | REPLICATE_API_TOKEN | Nome da variável de ambiente de autenticação do Replicate |
remote_timeout_seconds | 300 | Timeout da chamada remota |
Exemplos
# Legendagem remota via HuggingFace
export HF_TOKEN=hf_seu_token
uv run python scripts/describe.py --config config.json --provider huggingface
# Legendagem remota via Replicate
export REPLICATE_API_TOKEN=r8_seu_token
uv run python scripts/describe.py --config config.json --provider replicate --remote-model <slug-do-modelo-replicate>
Notas
- O modo remoto ainda grava o mesmo JSON auxiliar com
description/caption/tags - Credenciais ausentes falham rapidamente; não há fallback silencioso para o modo local
- O Replicate requer um slug de modelo explícito para legendagem remota
Padrões de Qualidade de Legenda
A legenda é tão importante quanto a imagem. Uma legenda fraca desperdiça um visual forte. Aplique estes princípios ao gerar ou solicitar legendas.
Regra do Um
Cada legenda deve transmitir uma ideia central clara. Se a legenda tentar fazer vários pontos, ela se torna difusa e perde impacto. As legendas mais fortes têm uma única ponta de lança: uma promessa, uma lição, uma observação, um ritmo de história.
Teste: você consegue dizer esta legenda em uma frase? Todas as linhas apoiam a mesma ideia? Se não, corte até que o núcleo esteja claro.
Gancho primeiro
A primeira linha de qualquer legenda é o gancho. No Instagram, apenas os primeiros ~125 caracteres são mostrados antes de "mais" — essa primeira linha deve merecer o toque. No LinkedIn, a primeira linha é o título.
Padrões de gancho que funcionam:
- Contrarian: "Pare de fazer X."
- Lacuna de curiosidade: "A maioria das pessoas não percebe..."
- Chamada de identidade: "Se você é [X], preste atenção."
- Autoridade/experiência: "Se eu tivesse que recomeçar, aqui está o que eu faria."
- Ponto de dor: "É por isso que você está preso em [X]."
Evite abrir com "Eu" ou com uma frase de aquecimento que não diz nada. A primeira linha deve merecer o resto da leitura.
Estrutura específica da plataforma
Instagram:
- Gancho primeiro (≤125 caracteres)
- Corpo: história, lição ou insight
- 3–5 hashtags relevantes no final
- Tom autêntico — evite linguagem de marketing polida
- Emojis são aceitáveis, mas devem reforçar o significado, não decorar
LinkedIn:
- 600–800 caracteres para melhor alcance; 100–150 para alta taxa de cliques quando necessário
- Gancho forte na primeira linha
- Sem links externos no corpo da postagem (o LinkedIn suprime o alcance para links externos)
- Estruturas que funcionam: Gancho → insight → detalhamento → CTA; ou História → lição → ação → pergunta de engajamento
- Clareza sobre criatividade — leitores escaneiam rapidamente
- Evite: excesso de emojis, espaçamento excessivo, mesmo formato consecutivo, fontes externas
Teste anti-genérico
Antes de aceitar uma legenda gerada, pergunte: isso soa como o especialista que tirou esta foto, ou soa como escrita genérica de IA? Se pudesse ter sido escrito por qualquer pessoa sobre qualquer coisa, falhou. A legenda deve refletir um ponto de vista específico, observação ou momento vivido.
Evite
- Abrir com "Eu" como primeira palavra
- Declarações inspiradoras vagas sem um ponto concreto
- Emojis usados como preenchimento visual em vez de reforçar o significado
- Mais de uma chamada para ação em uma única legenda
- Spam de hashtag (10+ hashtags) no LinkedIn