video-curriculum — vídeos que cobrem o escopo de um conceito

A diferença para uma busca comum: aqui o conceito vira um escopo (lista de subtópicos), e a skill garante que a trilha de vídeos cobre cada subtópico, apontando o que ficou descoberto.

Scripts (a parte determinística)

Sempre use os scripts bundled — não reescreva os comandos do yt-dlp na mão.

• Buscar (scripts/yt-search.ps1) — busca no YouTube, devolve JSON. Batch em paralelo:

  pwsh -NoProfile -File "<skill>/scripts/yt-search.ps1" -QueriesJson '["q subtópico 1","q subtópico 2"]' -Limit 8 -SortBy views [-MinMinutes N] [-MaxMinutes N]

  Uma query só: -Query "texto". Retorna {results:[{query, videos:[{title,channel,views,viewsHuman,durationSec,duration,url,videoId}]}]}.
• Verificar cobertura (scripts/yt-coverage.ps1) — confirma que um vídeo cobre o subtópico:

  pwsh -NoProfile -File "<skill>/scripts/yt-coverage.ps1" -Video <url|id> [-Transcript] [-Lang en]

  Retorna metadata + chapters (sinal forte e confiável de cobertura). Com -Transcript baixa a legenda e devolve o texto limpo — best-effort (o YouTube pode dar HTTP 429; o script avisa).

Dica de relevância: queries em inglês trazem muito mais material. Traduza os subtópicos para inglês na busca, mesmo que a conversa seja em português.

Fluxo

1. Capte o conceito e o nível. Pegue o tema do argumento. Se o escopo estiver ambíguo (tema amplo demais, nível não óbvio), faça uma pergunta curta com AskUserQuestion (nível iniciante/intermediário/avançado, foco prático vs. teórico). Senão, assuma e siga.
2. Decomponha em subtópicos (o ESCOPO). Liste 4–8 subtópicos que, juntos, cobrem o conceito — ordenados do fundamento ao avançado. Esse é o coração da skill: o escopo explícito.
3. Busque vídeos por subtópico. Monte uma query (em inglês) por subtópico e rode yt-search.ps1 com -QueriesJson (uma chamada, roda em paralelo). Use -SortBy views para qualidade e -MinMinutes 4 para evitar Shorts quando fizer sentido.
4. Mapeie vídeos → subtópicos e monte a MATRIZ DE COBERTURA. Para cada subtópico, escolha 1–3 vídeos (priorize: aderência ao subtópico → views → duração adequada → canal reputado). Um vídeo longo "tudo-em-um" (curso completo) pode cobrir vários subtópicos — registre isso. Marque cada subtópico como ✅ coberto, 🟡 fraco (só tangencial) ou ❌ gap (nada bom achado).
5. (Sob demanda) Verifique a cobertura de verdade. Se o usuário pediu rigor (--rigor) ou um subtópico estiver duvidoso, rode yt-coverage.ps1 nos candidatos: os chapters já confirmam o que o vídeo aborda; use -Transcript só quando precisar e o rate-limit permitir.
6. Monte a trilha por nível e grave o .md. Ordene tudo em iniciante → intermediário → avançado. Grave um plano de estudo em ./<slug>-video-plan.md no diretório atual (avise o caminho), com: título, escopo (subtópicos), a matriz de cobertura, e a trilha ordenada (cada item: título, canal, duração, URL clicável, qual subtópico cobre). Imprima um resumo no chat também.
7. Reporte os gaps. Liste os ❌/🟡 explicitamente e sugira refinar a query ou ampliar o escopo. Nunca finja cobertura: um gap honesto vale mais que um vídeo que não cobre o subtópico.

Modos

• --flat → pula a decomposição de escopo: trata o conceito como query única, devolve os top-N vídeos ranqueados. Use quando o usuário só quer "um bom vídeo sobre X", não um currículo.
• --rigor → ativa verificação de cobertura via yt-coverage.ps1 (chapters + transcrição quando possível) para todos os subtópicos, não só os duvidosos.
• --nivel <n> → fixa o nível-alvo e calibra os subtópicos e a profundidade dos vídeos.

Guardrails

• yt-dlp é obrigatório (grátis, keyless). Se ausente, o script avisa (pip install -U yt-dlp); declare isso ao usuário e pare — não invente vídeos nem URLs.
• Anti-alucinação: todo vídeo citado vem do JSON do yt-search.ps1. Nunca cite título/URL que não saiu do script. Se a cobertura de um subtópico não foi achada, diga "gap", não improvise.
• Rate-limit (HTTP 429): a transcrição é best-effort. Se o script reportar 429, caia para os chapters (já são ótimo sinal) e siga — não trave o fluxo.
• Só leitura do YouTube. O único artefato gravado é o plano de estudo .md (e só no diretório atual).