⚙️ Carpeta scripts/: automatización con shell
La subcarpeta scripts/ contiene los ejecutables que el agente invoca mediante Bash. Cada script es atómico: una responsabilidad, una salida 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 bien redactados
- ✓Una responsabilidad por archivo
- ✓Nombre con verbo-sustantivo (check-deps, analyze-video)
- ✓Shebang en la primera línea
- ✓Salida clara con ✅/❌
- ✓set -e para fallar rápido
✗ Scripts problemáticos
- ✗Script monolítico de 500 líneas
- ✗Código inline en SKILL.md
- ✗API key hardcodeada en el script
- ✗Sin manejo de errores
- ✗Nombre genérico (script.sh, run.sh)
📚 Archivos reference.md
References son los "manuales detallados" de la skill — contienen todo lo que sería demasiado extenso para el SKILL.md principal. El agente los consulta bajo demanda, cuando necesita información detallada.
Qué va en references/
- • Especificaciones completas de la API
- • Tablas de parámetros
- • Ejemplos de response JSON
- • Códigos de error y manejo
- • Fórmulas de copywriting
- • Reglas de análisis de contenido
- • Lógica de enrutamiento
- • Templates de prompt
- • Templates HTML completos
- • Sistema de colores y tipografía
- • Componentes reutilizables
- • Listas de verificación de revisión
## 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.💡 Regla de oro: mencionar, no duplicar
El SKILL.md solo debe apuntar para los references — nunca copies su contenido. La duplicación crea inconsistencias: cuando actualizas el reference, el SKILL.md queda desactualizado sin que te des cuenta.
🔑 .env.example: secretos fuera del código
El archivo .env.example es el estándar de la industria para documentar variables de entorno sin exponer valores reales.
# .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⚠️ Regla estricta de seguridad
Una clave de API expuesta en un commit público puede generar pérdidas en minutos. Sigue estas reglas sin excepción:
- ⚠️NUNCA haz commit del archivo
.envreal - ⚠️NUNCA registra las variables de entorno en la salida o en la depuración
- ⚠️SIEMPRE agrega
.enval .gitignore - ⚠️SIEMPRE usa
$VARIAVELen los scripts, nunca como valor literal
Ciclo de configuración para nuevos usuarios
Clona / instala la skill
El .env.example ya está en la carpeta. El usuario ve lo que necesita configurar.
cp .env.example .env
Copia la plantilla. El .env real nunca va al repositorio.
Completa los valores reales
Edita el .env con la API key real. El script check.sh verifica que esté completo antes de usar la skill.
🔽 Divulgación progresiva
Progressive disclosure es el principio de mostrar primero lo esencial y revelar detalles a pedido. Aplicado a las skills: SKILL.md breve + references detallados + scripts especializados.
Los 3 niveles de detalle
💡 Por qué la progresividad ahorra tokens
Un SKILL.md de 500 líneas cuesta entre 5 y 10 veces más tokens que uno de 100 líneas, y se lee en CADA activación. Las referencias de 500 líneas solo consumen tokens cuando el agente las necesita. La divulgación progresiva hace que la skill sea escalable.
🚧 Reglas estrictas: reglas que nunca se rompen
Las hard rules son restricciones absolutas: el sistema inmunitario de la skill. Se diferencian de las guidelines (sugerencias) porque no son negociables. Escritas en MAYÚSCULAS para evitar cualquier confusión.
## 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.✓ Reglas estrictas eficaces
- ✓3-7 reglas (más se vuelve ruido)
- ✓Cada una con una justificación breve
- ✓Verbo en mayúsculas (NUNCA, SIEMPRE)
- ✓Probable con un caso adversarial
- ✓Protección contra los errores más costosos
✗ Hard rules problemáticas
- ✗20+ reglas — nadie las recuerda todas
- ✗Sin justificación: no se sabe por qué
- ✗Reglas para situaciones muy poco frecuentes
- ✗Mezclar reglas estrictas con pautas
- ✗Sin sección dedicada, se pierden en el cuerpo
🔒 Gates de confirmación
Uno gate es un punto de control en el que el agente se detiene y pide confirmación antes de ejecutar una acción costosa, irreversible o de alto impacto. Confirmar no cuesta nada; no hacerlo puede costar muchísimo.
## 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.📊 Cuándo usar gate
Llamadas a API que cobran por uso (video, imagen, tokens)
eliminar archivos, publicar en producción, enviar correos electrónicos
modificar la base de datos, cambiar la configuración del sistema
💡 Puerta de calidad, no de burocracia
Los gates deben ser informativos, no molestos. Un buen gate muestra el costo estimado, un resumen de lo que se hará y ofrece una salida clara. Un gate de "¿confirmas? (s/n)" sin contexto es tan malo como no tener un gate: el usuario confirmará sin entender qué está confirmando.
📂 Resumen del módulo
Siguiente módulo:
3.4 — Caso de estudio: ads-skill (Arcads) — analizar una skill real de producción que aplica todo lo que aprendiste