⚙️ Pasta scripts/: automação em shell
A subpasta scripts/ contém os executáveis que o agente invoca via Bash. Cada script é atômico: uma responsabilidade, uma saída clara.
#!/bin/bash
# check-deps.sh — verifica dependências antes de executar
# Uso: bash scripts/check-deps.sh
set -e
echo "Verificando dependências..."
# Verifica ffmpeg
if ! command -v ffmpeg &>/dev/null; then
echo "❌ ffmpeg não encontrado. Instale: brew install ffmpeg"
exit 1
fi
# Verifica .env
if [ ! -f .env ]; then
echo "❌ .env não encontrado. Copie .env.example e preencha."
exit 1
fi
echo "✅ Tudo pronto!"✓ Scripts bem escritos
- ✓Uma responsabilidade por arquivo
- ✓Nome com verbo-substantivo (check-deps, analyze-video)
- ✓Shebang na primeira linha
- ✓Saída clara com ✅/❌
- ✓set -e para falhar rápido
✗ Scripts problemáticos
- ✗Script monolítico de 500 linhas
- ✗Código inline no SKILL.md
- ✗API key hardcoded no script
- ✗Sem tratamento de erro
- ✗Nome genérico (script.sh, run.sh)
📚 Arquivos reference.md
References são os "manuais detalhados" da skill — contêm tudo que seria muito extenso para o SKILL.md principal. O agente os consulta sob demanda, quando precisa de informação profunda.
O que vai em references/
- • Especificações de API completas
- • Tabelas de parâmetros
- • Exemplos de response JSON
- • Códigos de erro e tratamento
- • Fórmulas de copywriting
- • Regras de análise de conteúdo
- • Lógica de roteamento
- • Templates de prompt
- • Templates HTML completos
- • Sistema de cores e tipografia
- • Componentes reutilizáveis
- • Checklists de revisão
## Referências
Sempre leia estes arquivos antes de criar ou editar qualquer página:
1. **`references/MASTER_COMPLETO.md`**
Templates HTML completos, CSS e JavaScript obrigatórios.
Contém tudo que você precisa para construir qualquer página.
2. **`references/CHECKLIST_REVISAO.md`**
Checklist para verificar a página antes de entregar.
3. **`references/SVG-FUTURISTA.md`**
Leia SEMPRE que for criar um módulo de conteúdo.
# O SKILL.md menciona, mas não duplica. Detalhes ficam nas refs.💡 Regra de ouro: mencionar, não duplicar
O SKILL.md deve apenas apontar para os references — nunca copiar o conteúdo deles. Duplicação cria inconsistência: quando você atualiza o reference, o SKILL.md fica desatualizado sem você perceber.
🔑 .env.example: segredos fora do código
O arquivo .env.example é o padrão da indústria para documentar variáveis de ambiente sem expor valores reais.
# .env.example — copie para .env e preencha com valores reais
# NUNCA faça commit do arquivo .env
# Arcads API
ARCADS_API_KEY=sua_chave_arcads_aqui
ARCADS_BASE_URL=https://api.arcads.ai/v1
# Configurações opcionais
ARCADS_DEFAULT_MODEL=seedance-2.0
ARCADS_TIMEOUT_SECONDS=300
# Diretórios de trabalho
WORK_DIR=./tmp/arcads
OUTPUT_DIR=./output⚠️ Hard rule de segurança
Uma chave de API exposta em um commit público pode gerar prejuízo em minutos. Siga estas regras sem exceção:
- ⚠️NUNCA faça commit do arquivo
.envreal - ⚠️NUNCA logue variáveis de ambiente em output ou debug
- ⚠️SEMPRE adicione
.envao .gitignore - ⚠️SEMPRE use
$VARIAVELnos scripts, nunca valor literal
Ciclo de setup para novos usuários
Clone / instale a skill
O .env.example já está na pasta. O usuário vê o que precisa configurar.
cp .env.example .env
Copia o template. O .env real nunca vai para o repositório.
Preenche os valores reais
Edita o .env com a API key real. O script check.sh verifica se está preenchido antes de usar a skill.
🔽 Progressive disclosure
Progressive disclosure é o princípio de mostrar primeiro o essencial e revelar detalhes sob demanda. Aplicado a skills: SKILL.md curto + references detalhados + scripts especializados.
Os 3 níveis de detalhe
💡 Por que a progressividade economiza tokens
Um SKILL.md de 500 linhas custa 5-10x mais em tokens do que um de 100 linhas — e é lido em TODA ativação. References de 500 linhas só custam tokens quando o agente precisa deles. A progressividade torna a skill escalável.
🚧 Hard rules: regras que nunca quebram
Hard rules são restrições absolutas — o sistema imune da skill. Diferem de guidelines (sugestões) porque são inegociáveis. Escritas em MAIÚSCULAS para impossível confusão.
## Hard Rules
# Estas regras são invioláveis — não há exceção.
- **NUNCA** parafrasear o transcript do vídeo original.
Usar verbatim (texto exato) para preservar timing e autenticidade.
- **SEMPRE** rodar o dialogue gate antes de gerar.
Confirmar todos os inputs com o usuário para evitar gasto de créditos.
- **NUNCA** logar a API key em qualquer output ou arquivo de log.
Usar $ARCADS_API_KEY; nunca imprimir ou expor o valor real.
- **SEMPRE** verificar .env antes de executar qualquer script.
Rodar scripts/check.sh como primeiro passo de toda geração.✓ Hard rules eficazes
- ✓3-7 regras (mais vira ruído)
- ✓Cada uma com justificativa curta
- ✓Verbo em maiúsculas (NUNCA, SEMPRE)
- ✓Testável com caso adversarial
- ✓Proteção contra os erros mais caros
✗ Hard rules problemáticas
- ✗20+ regras — ninguém lembra de todas
- ✗Sem justificativa — não se sabe por quê
- ✗Regras para situações raríssimas
- ✗Misturar hard rules com guidelines
- ✗Sem seção dedicada — perdidas no corpo
🔒 Gates de confirmação
Um gate é um checkpoint onde o agente para e pede confirmação antes de executar uma ação cara, irreversível ou de alto impacto. O custo de confirmar é zero; o de não confirmar pode ser enorme.
## Fluxo de Geração
1. Coletar inputs (imagem/áudio/vídeo/ator)
2. Detectar modelo recomendado (ver prompting/model-routing.md)
### DIALOGUE GATE — executar antes de qualquer chamada à API
Apresentar ao usuário:
```
📋 Resumo da geração:
Modelo: Seedance 2.0 (lip sync)
Ator: [nome]
Script: "[primeiros 50 chars...]"
Custo estimado: ~8 créditos Arcads
Duração: ~15 segundos
Confirma? (S/N)
```
NUNCA prosseguir sem confirmação explícita "S" ou "sim".
3. Executar scripts/arcads_generate.sh apenas após confirmação.📊 Quando usar gate
API calls que cobram por uso (vídeo, imagem, tokens)
deletar arquivos, publicar em produção, enviar emails
alterar banco de dados, modificar configurações do sistema
💡 Gate de qualidade, não de burocracia
Gates devem ser informativos, não irritantes. Um bom gate mostra o custo estimado, o resumo do que será feito e oferece uma saída clara. Um gate de "você confirma? (s/n)" sem contexto é tão ruim quanto não ter gate — o usuário vai confirmar sem entender o que está confirmando.
📂 Resumo do Módulo
Próximo Módulo:
3.4 — Case study: ads-skill (Arcads) — dissecar uma skill real de produção que aplica tudo que você aprendeu