🔬 The Two Powers of the ads-skill
The ads-skill is a rare case of a skill with two complementary powers: analysis and generation. They are inseparable in the workflow—analysis feeds generation.
🔬 Power 1: Analysis
- →Receives a UGC video URL or file
- →Extracts frames at 2fps via ffmpeg
- →Transcribes audio with Whisper
- →Identifies HOOK/SHOW/PROOF/CTA segments
- →Generates a viral analysis report
🎬 Power 2: Generation
- →Receives 4 inputs: image/audio/video/actor
- →Routes to the ideal model (4 options)
- →Runs the dialogue gate (confirms cost)
- →Calls the Arcads API and polls for status
- →Returns the generated video URL
🤖 Smart Routing Across 4 Models
Instead of making the user choose the model, the skill abstracts that decision with clear routing logic. The decision table is in prompting/model-routing.md.
Routing table
| Model | When to use | Feature |
|---|---|---|
| Seedance 2.0 (default) | UGC with speech, lip sync required | Best lip sync |
| Veo 3.1 | Specific opening frame, visual consistency | Locked reference frame |
| Sora 2 | Videos over 30s or in a cinematic style | Long / cinematic |
| Kling 3.0 | Visual content without speech | Quiet / aesthetic |
# Model Routing — ads-skill
## Árvore de decisão
if has_speech AND needs_lip_sync:
→ Seedance 2.0 # padrão para UGC com ator
elif has_reference_frame AND visual_consistency_critical:
→ Veo 3.1 # frame inicial travado
elif duration_seconds > 30 OR cinematic_style:
→ Sora 2 # longo / cinematográfico
elif silent AND visual_only:
→ Kling 3.0 # silencioso / estético
else:
→ Seedance 2.0 # fallback padrão
## Rationale
Seedance: único com lip sync confiável para português
Veo: quando frame 0 é crítico (ex.: unboxing específico)
Sora: quando a narrativa precisa de mais de 30 segundos
Kling: produto sem locutor (ex.: product shots, natureza)💡 Abstraction = power for the user
The user doesn’t need to know there are 4 models. They describe what they want (“I need a UGC video with the actor João talking about the product”), and the skill chooses the right model. That’s the real value of a well-designed skill: hidden complexity, accessible power.
📁 Complete ads-skill structure
The ads-skill has 12 files distributed across 4 layers. Each file has a single, well-defined responsibility.
ads-skill/
├── SKILL.md # frontmatter + fluxo + hard rules
├── .env.example # ARCADS_API_KEY, ARCADS_BASE_URL
├── reference.md # docs API Arcads, endpoints, parâmetros
│
├── scripts/
│ ├── arcads_check.sh # verifica ffmpeg + .env + deps
│ ├── arcads_analyze.sh # extrai frames+áudio, gera relatório UGC
│ ├── arcads_actors.sh # lista atores disponíveis na conta
│ ├── arcads_upload.sh # faz upload de mídia para Arcads storage
│ ├── arcads_generate.sh # cria job de geração (retorna job_id)
│ ├── arcads_talking.sh # variante: talking head com script
│ └── arcads_status.sh # polling de status até concluir
│
└── prompting/
├── viral-analysis.md # fórmulas para análise UGC viral
├── ugc-formulas.md # templates HOOK/SHOW/PROOF/CTA
└── model-routing.md # árvore de decisão de modeloThe lifecycle of a generation
arcads_check.sh: checks ffmpeg, .env, API connectivityarcads_analyze.sh: extracts the structure of the reference UGCarcads_actors.sh: lists available actors; the user choosesjob_id)arcads_status.sh: polling until completed⚠️ ads-skill hard rules
Three hard rules protect the three most important things: content integrity, budget, and credential security.
NEVER paraphrase the transcript — verbatim only
The UGC video transcript is extracted word for word. The skill can’t rewrite, summarize, or “improve” the text.
Viral UGC ads have specific timing: a pause at 1.3s, a change in inflection at 2.7s. A paraphrase changes how long the words take to say and breaks sync with the frame. What works in 2 seconds can become 3.2s and lose the viewer.
ALWAYS run the dialogue gate before generating
Before any Arcads API call, present a complete summary: chosen actor, model, estimated cost in credits, estimated duration.
A 15-second generation in Seedance costs ~8 Arcads credits. An accidental loop or incorrect input can consume 100 credits ($50-200) in seconds. The gate is the only safeguard before real spending.
NEVER log the API key in any output
The scripts read $ARCADS_API_KEY from the environment. The key never appears in logs, terminal output, debug files, or any other output.
API keys exposed in logs are found by scrapers within minutes. A compromised Arcads key lets third parties generate videos on your account — with unlimited charges until you notice.
⏱️ The 15-second UGC framework
Every viral 15-second UGC ad follows the same 5-segment structure. The ads-skill automatically identifies and extracts each one.
✓ Each segment in practice
- HOOK (0-2s): surprise, provocative question, contradiction, something weird happening
- SHOW (2-6s): real product demonstration, visible benefit in action
- PROOF (6-11s): specific number ("3kg in 7 days"), testimonial, before/after
- CTA (11-14s): a single action — "click the link in the bio," "buy now"
✗ Fatal errors by segment
- Weak HOOK: product logo in the first 2s (immediate scroll)
- Wrong SHOW: stock image, not a real demo
- Vague PROOF: "works really well" without a number
- Multiple CTAs: two action verbs ("click AND share")
🔗 The ads-skill as a Mirror of Modules 3.1–3.3
Every design decision in the ads-skill was made according to the same principles you learned in the previous three modules. Here, theory becomes code.
Theory → implementation mapping
SKILL.md in the root with YAML frontmatterscripts/ + prompting/ads-skill, name: ads-skillarcads_*.sh💡 Your next skill: copy the structure, adapt the domain
The ads-skill is a reference template for any skill that integrates an external API with multiple models. The structure check → analyze → gate → upload → generate → status works for:
- • Image generation (DALL-E, Midjourney, Stable Diffusion)
- • Audio synthesis (ElevenLabs, Murf, Play.ht)
- • Document processing (contract analysis, data extraction)
- • Any API with asynchronous polling
Download the skill ads-skill complete · ~26 KB
All the code in this case study: SKILL.md, the scripts arcads_*.sh, the prompting/ e o reference.md. Study it and adapt it for your own skill.
🎬 Module Summary — and the Skills Track
🔁 Next Track:
Track 4 — Automation: now that you know how to create skills, learn how to chain them into automatic workflows, hooks, and scheduled routines that run without manual intervention.