skill_youtube.md

gistfile1.txt

Preciso que você crie uma skill do Claude Code chamada youtube que usa yt-dlp para analisar vídeos automaticamente.

  Pré-requisito: ter yt-dlp instalado (pip install yt-dlp).

  Passo 1 — criar as pastas:
  mkdir -p ~/.claude/skills/youtube/scripts

  Passo 2 — criar o arquivo ~/.claude/skills/youtube/SKILL.md com o conteúdo abaixo:

  ---
  name: youtube
  description: Analisa vídeos do YouTube usando yt-dlp para extrair metadados e transcrição. Use SEMPRE que o usuário pedir para analisar, resumir, ou comentar sobre um link do
  YouTube. NUNCA use playwright para isso.
  ---

  # YouTube Analyzer

  Analisa qualquer vídeo do YouTube usando `yt-dlp` para extrair metadados e transcrição completa.

  ## Trigger

  Ativar automaticamente sempre que o usuário:
  - Passar um link do YouTube (`youtube.com/watch`, `youtu.be/`, `youtube.com/shorts/`)
  - Pedir para "analisar", "resumir", "o que fala", "explica esse vídeo" + URL do YouTube

  **NUNCA usar playwright para vídeos do YouTube — sempre usar este fluxo com yt-dlp.**

  ## Fluxo

  ```bash
  bash ~/.claude/skills/youtube/scripts/get-transcript.sh "<URL>"
  ```

  ## Após obter os dados

  Se o usuário não especificar o tipo de análise, fazer um resumo estruturado com:
  1. Sobre o vídeo (canal, data, contexto)
  2. Ideia central
  3. Pontos principais (bullet points)
  4. Takeaways práticos

  ## Erros comuns

  - **429 Too Many Requests**: normal — o script usa o primeiro idioma que funcionar
  - **Sem transcrição**: informar e oferecer analisar só pela descrição/título
  - **yt-dlp desatualizado**: sugerir `pip install -U yt-dlp`

  Passo 3 — criar o script ~/.claude/skills/youtube/scripts/get-transcript.sh:

  #!/usr/bin/env bash
  URL="$1"
  if [ -z "$URL" ]; then
    echo "Usage: $0 <youtube-url>" >&2
    exit 1
  fi

  TMP=$(mktemp -d)
  trap "rm -rf $TMP" EXIT

  echo "=== METADADOS ==="
  yt-dlp --no-playlist --skip-download \
    --print "Título: %(title)s" \
    --print "Canal: %(uploader)s" \
    --print "Data: %(upload_date>%d/%m/%Y)s" \
    --print "Duração: %(duration_string)s" \
    --print "Views: %(view_count)s" \
    "$URL" 2>/dev/null

  echo ""
  echo "=== DESCRIÇÃO ==="
  yt-dlp --no-playlist --skip-download --print "%(description)s" "$URL" 2>/dev/null

  echo ""
  echo "=== TRANSCRIÇÃO ==="

  yt-dlp \
    --write-subs --write-auto-subs \
    --sub-langs "pt-orig,pt,en" \
    --skip-download \
    -o "$TMP/sub" \
    --no-playlist \
    "$URL" 2>/dev/null

  SUB_FILE=""
  for lang in "pt-orig" "pt" "en"; do
    for ext in "srt" "vtt"; do
      f="$TMP/sub.$lang.$ext"
      if [ -f "$f" ]; then
        SUB_FILE="$f"
        echo "(Idioma: $lang)"
        break 2
      fi
    done
  done

  if [ -z "$SUB_FILE" ]; then
    SUB_FILE=$(ls "$TMP"/*.vtt "$TMP"/*.srt 2>/dev/null | head -1)
  fi

  if [ -z "$SUB_FILE" ]; then
    echo "Transcrição não disponível para este vídeo."
    exit 0
  fi

  grep -v "^WEBVTT\|^Kind:\|^Language:\|^NOTE\|^[0-9]*$\|^[0-9][0-9]:[0-9][0-9]:[0-9][0-9]" "$SUB_FILE" \
    | sed 's/<[^>]*>//g' \
    | grep -v "^[[:space:]]*$" \
    | awk 'prev != $0 { print; prev=$0 }' \
    | tr '\n' ' ' \
    | sed 's/  */ /g'

  echo ""

  Passo 4 — dar permissão de execução:
  chmod +x ~/.claude/skills/youtube/scripts/get-transcript.sh

  Pronto. Agora sempre que você mandar um link do YouTube pro Claude Code, ele automaticamente usa o yt-dlp para pegar metadados e transcrição antes de analisar.

Testei a skill no macOS (Apple Silicon) e funcionou muito bem 🙌 — metadados, descrição e transcrição saindo certinho. Mas esbarrei em dois pontos que podem fazer a transcrição falhar dependendo do ambiente/vídeo, e queria deixar a correção registrada.

1) yt-dlp precisa de curl_cffi (impersonation) pra baixar legenda

No yt-dlp recente (testei na 2026.03.17), o endpoint de legendas (timedtext) responde HTTP Error 429: Too Many Requests se o yt-dlp não conseguir se passar por um browser. Sem curl_cffi, --list-impersonate-targets mostra tudo como (unavailable).

Detalhe traiçoeiro: a versão mais nova do curl_cffi (0.15.0) aparece como (unsupported) pra essa build. Resolvi com downgrade:

# no venv do yt-dlp (ex.: instalado via Homebrew)
$(brew --prefix yt-dlp)/libexec/bin/python -m pip install "curl_cffi<0.14"

2) Um 429 num idioma aborta os outros (bug no script)

O script pede os três idiomas numa única chamada: --sub-langs "pt-orig,pt,en". O yt-dlp baixa em ordem e, se o primeiro idioma toma 429 (comum nas legendas auto-traduzidas, ex.: pt num vídeo em inglês), o ERROR aborta a chamada inteira antes de tentar o en — e o vídeo cai no "Transcrição não disponível" mesmo tendo legenda em inglês disponível.

A correção é baixar um idioma por vez (e passar --impersonate chrome), parando no primeiro que funcionar. Assim um 429 no pt não derruba o en:

echo "=== TRANSCRIÇÃO ==="

# Baixa um idioma por vez: um 429 num idioma não aborta os demais.
SUB_FILE=""
for lang in "pt-orig" "pt" "en"; do
  yt-dlp \
    --impersonate chrome \
    --write-subs --write-auto-subs \
    --sub-langs "$lang" \
    --skip-download \
    -o "$TMP/sub" \
    --no-playlist \
    "$URL" 2>/dev/null
  for ext in "srt" "vtt"; do
    f="$TMP/sub.$lang.$ext"
    if [ -f "$f" ]; then
      SUB_FILE="$f"
      echo "(Idioma: $lang)"
      break 2
    fi
  done
done

if [ -z "$SUB_FILE" ]; then
  SUB_FILE=$(ls "$TMP"/*.vtt "$TMP"/*.srt 2>/dev/null | head -1)
fi

(O resto do script — metadados, descrição, fallback e limpeza do .vtt — fica igual.)

Com esses dois ajustes a transcrição passou a vir de forma consistente, inclusive em vídeos só-inglês onde o pt auto-traduzido tomava 429. Valeu pela skill! 🚀