youtube-summary

Summarize YouTube videos with youtube2md, including bare YouTube URLs with no instructions, chaptered notes, timestamp links, transcript extraction, and key takeaways.

YouTube Summary (youtube2md)

Use the official youtube2md CLI behavior from the package/repository (pinned youtube2md@1.2.0).

Runtime + security prerequisites

• Require Node.js 20.18.1+.
• Require preinstalled youtube2md on PATH.
  • Recommended pinned install: npm i -g youtube2md@1.2.0
• Default runner uses the local youtube2md executable only.
• Runtime npm execution (npx) is intentionally not supported by this skill runner.
• The YOUTUBE2MD_BIN environment variable override is rejected by the runner.
• Full mode needs a summarization provider; with --provider auto, youtube2md tries:
  1. Codex SDK with ChatGPT login — requires both the optional @openai/codex-sdk peer (npm i -g @openai/codex-sdk) and a ChatGPT-authenticated Codex session. A logged-in codex CLI without the SDK is not enough. OPENAI_API_KEY is not passed to Codex.
  2. OpenAI API — used when Codex is unavailable or fails and OPENAI_API_KEY is set.
• The runner asks the installed youtube2md for its own Codex verdict (detectCodexChatGptLogin) rather than guessing, so its pre-check cannot disagree with the tool. When Codex is unavailable it logs the upstream reason, and in auto mode with OPENAI_API_KEY set it logs that the run will use the billed API path instead of the ChatGPT session.
  • If npm i -g @openai/codex-sdk fails with EACCES on a root-owned node_modules/@openai, it needs sudo (the user must run it; the skill never escalates privileges).
• Either provider sends transcript-derived content to OpenAI systems; for sensitive content, use simple or transcript mode when captions are available.
• Model default: the runner passes --model only when the fifth runner argument or YOUTUBE2MD_DEFAULT_MODEL is set; otherwise the upstream default (gpt-5.6-luna for both providers) and the per-provider CODEX_MODEL / OPENAI_MODEL env vars apply.
• Extract mode passes --captions-only by default: audio is never sent to Whisper in simple/transcript mode. Set YOUTUBE2MD_CAPTIONS_ONLY=0 to allow Whisper STT for captionless videos (requires OPENAI_API_KEY).
• Full mode keeps the Whisper fallback available: a captionless video may have its audio uploaded to OpenAI when OPENAI_API_KEY is set. Set YOUTUBE2MD_CAPTIONS_ONLY=1 to forbid that in full mode too (captionless videos then fail instead).
• YOUTUBE_COOKIES_PATH or YOUTUBE_COOKIE_HEADER can be used when YouTube blocks anonymous caption/audio access.
• In sensitive environments, audit upstream youtube2md@1.2.0 and dependencies before installation or future version bumps.

See references/security.md before first-time install/enable.

Workflow

1. Validate input

   • Accept youtube.com and youtu.be URLs (watch, Shorts, Live, Embed, Music, and youtube-nocookie.com embed shapes are supported; timestamped &t= URLs are accepted but the whole video is processed).
   • Quote URLs containing & when passing them to the shell.
   • If a message contains only YouTube URL(s), treat it as a request to summarize with this skill.
   • If YouTube URL(s) are provided without an explicit task, default to summary output, not transcript-only output.
   • If URLs are missing, ask for one URL per line.

2. Pin the caption language

   • Always set YOUTUBE2MD_CAPTION_LANG when the video's spoken language is known or inferable (user's request language, channel, title/description). Use en for an English video, ko for a Korean one, and so on.
   • Why: with no preference, every caption track ties in youtube2md's ranking, so the first track YouTube lists wins. Videos with community translations frequently yield a translated track — e.g. a 3blue1brown video returns Arabic (actualLanguage: "ar"), and the whole summary then comes out in Arabic.
   • After any run, verify the transcript/summary language and re-run with the correct YOUTUBE2MD_CAPTION_LANG if a translated track was picked. YOUTUBE2MD_JSON=1 exposes actualLanguage for an exact check; otherwise glance at the transcript text.
   • The runner warns on stderr whenever YOUTUBE2MD_CAPTION_LANG is unset. Treat that warning as a prompt to check the output language, not as noise.

3. Choose mode

   • Full mode: generates Markdown with youtube2md's summarization pipeline (Codex ChatGPT login first, then OpenAI API).
     • If a provider is available (Codex ChatGPT login or OPENAI_API_KEY) and external API use is acceptable, try full mode first.
     • Detail density is tunable via YOUTUBE2MD_DETAIL=concise|balanced|exhaustive (upstream default: balanced). Use exhaustive when the user asks for the densest possible notes, concise for a quick overview. --detail moves chapter-bullet density only; the ## Summary section stays short at every level.
     • Expect a short ## Summary and detailed ## Chapters (youtube2md 1.2.0 design): the Summary is a few-sentence orientation that states the video's conclusion/verdict, and every supporting fact lives in the chapter bullets. A short Summary is not truncated output — never pad, expand, or rewrite it.
   • Simple mode: uses youtube2md --extract-only --extract-format timestamped-text --captions-only internally to produce a timestamped .txt transcript, then summarizes from that transcript.
     • Use when no provider is available, content is sensitive, external API use is not acceptable, or full mode fails/falls back.
   • Transcript mode: uses the same extract path and returns transcript output without a summary.
     • Use when the user asks for transcript extraction, transcript-only output, raw transcript, or machine-readable transcript JSON (YOUTUBE2MD_EXTRACT_FORMAT=json).
   • Prefer a no-error path: the runner pre-checks provider availability and switches to the extract path automatically when full mode cannot run.

4. Run converter

   • Preferred runner script:
     • scripts/run_youtube2md.sh <url> full [output_md_path] [language] [model]
       • If no summarization provider is available, runner auto-falls back to the internal extract path; disclose summary output as simple mode.
       • [model] and YOUTUBE2MD_DEFAULT_MODEL are optional; when omitted, upstream defaults apply.
     • scripts/run_youtube2md.sh <url> extract [output_txt_path]
       • extract is the runner/CLI mode name; default artifact is timestamped text (.txt).
       • Disclose it as simple when summarizing from the .txt.
       • Disclose it as transcript when returning transcript-only output.
   • Optional machine-readable CLI output:
     • YOUTUBE2MD_JSON=1 scripts/run_youtube2md.sh <url> full
     • YOUTUBE2MD_JSON=1 scripts/run_youtube2md.sh <url> extract
     • With --json or --stdout active, stdout carries a single data payload; runner status goes to stderr.
   • Optional stdout/no-file mode:
     • YOUTUBE2MD_STDOUT=1 scripts/run_youtube2md.sh <url> extract
   • Optional output directory:
     • YOUTUBE2MD_OUT_DIR=./output scripts/run_youtube2md.sh <url> extract
   • Caption language (set this whenever the language is known — see step 2):
     • YOUTUBE2MD_CAPTION_LANG=ko scripts/run_youtube2md.sh <url> extract
   • Optional full-mode detail density:
     • YOUTUBE2MD_DETAIL=exhaustive scripts/run_youtube2md.sh <url> full
   • Runtime controls:
     • Use only locally installed youtube2md executable.
     • Do not use runtime npm execution (npx) for this skill.
   • Direct CLI equivalent:
     • Full: youtube2md --url <url> [--out <path>] [--out-dir <dir>] [--lang <language>] [--model <model>] [--provider auto|codex|openai] [--detail concise|balanced|exhaustive]
     • Simple/transcript: youtube2md --url <url> --extract-only --extract-format timestamped-text --captions-only [--out <path>]
     • Add --caption-lang <code> to pin the caption language; omitting it lets YouTube's track order decide (see step 2).
     • Add --captions-only in full mode to forbid the Whisper audio upload.
     • Add --json for a versioned machine-readable result envelope (includes outputPath).
     • Add --stdout to write output to stdout instead of a file.

5. Verify output

   • Full mode: Markdown file exists and is non-empty unless --stdout is used.
   • Simple mode: timestamped .txt transcript exists and is non-empty when file output is used.
   • Transcript mode: .txt or .json transcript output exists and is non-empty, unless --stdout is used.
   • If using --json, parse the envelope: ok: true/false, outputPath, transcriptSource, actualLanguage, provider, fallbackUsed; handle error code per references/troubleshooting.md.

6. Respond to the user

   • Follow references/output-format.md for the response shape: full mode is a verbatim pass-through of the package Markdown; simple/transcript modes use the compact authored structure.
   • Follow references/summarization-behavior.md for source policy and chapter/takeaway density.
   • Deliver the summary inline in the reply, in full — never as a file attachment, download link, or a meta-description in place of the content, no matter how long. A 3-hour video with 100+ chapters still gets its complete summary pasted into the response; length is never a reason to attach, truncate, or summarize-the-summary.
   • Send it in one reply even on channels that cap message size (Telegram ~4096 chars, Slack ~4000) — the host splits long text into multiple messages by itself. Do not hand-split into (1/3), (2/3), (3/3) sends: on openclaw the first message tool call ends the turn, so the later parts never get sent. See references/output-format.md.
   • Do not include generated local file path(s) in normal user-facing replies.
   • Share file paths, or produce an export file, only when explicitly requested by the user (e.g., debugging/export workflows).
   • Summary source policy:
     • Full mode succeeded -> the youtube2md Markdown output is the final summary; present it verbatim (append only the mode line). Do not re-summarize, condense, drop chapters/bullets, or reflow it into the compact template — that discards the detail the package produced. This is what makes the skill match the detail of running youtube2md directly.
     • Simple mode -> Claude summarizes from the timestamped .txt transcript using the compact structure in references/output-format.md.
     • Transcript mode -> return transcript content or requested transcript artifact details, not a summary.
   • Always append a final mode line after the user-facing result:
     • Mode: full
     • Mode: simple
     • Mode: simple (fallback from full; no summarization provider available) when full was requested but the runner fell back and a summary was still produced.
     • Mode: transcript when transcript-only output was requested.
   • Keep user-facing flow smooth: if no provider is available, use simple output and summarize from .txt without surfacing avoidable tool-error noise.

Multi-video requests

• Process URLs sequentially.
• Return per-video results (omit local file paths unless requested).
• Include the final mode line for each video result.
• If any fail, report successful items first, then failures with fixes.

Built-in behavior to trust

• Default output paths:
  • Full mode: ./summaries/<video_id>.md
  • Simple/transcript modes: ./summaries/<video_id>.txt (timestamped text) or ./summaries/<video_id>.json (YOUTUBE2MD_EXTRACT_FORMAT=json)
• Model defaults: upstream youtube2md defaults to gpt-5.6-luna for both providers; CODEX_MODEL / OPENAI_MODEL override per provider; the fifth runner argument or YOUTUBE2MD_DEFAULT_MODEL overrides everything via --model.
• Detail levels (--detail, full mode): chapter-bullet density scales with video length and content density at every level; the flag only shifts where the target sits (concise ≈ one bullet per ~750 transcript tokens, balanced ≈ ~450 (default), exhaustive ≈ ~300, densest notes). Responses that land far below the requested target (under 70%) are re-requested once automatically.
• Section sizing (full mode):
  • ## Summary is an orientation, not a recap: its sentence budget scales with duration but is hard-capped at 8 sentences (~3 for a 1-hour video) with a matching word ceiling, and it must state the video's actual conclusion/verdict — answering the title outright when the title poses a question. --detail does not lengthen it.
  • ## Chapters carries the detail. Bullets are budgeted as one approximate total per request and spent unevenly, so a dense section gets several times more bullets than a transitional one.
  • Chapter count follows chunk count (CHUNK_CHAPTER_CAP = 9 chapters per full-size chunk) rather than --detail; --detail shifts chapter density only for short or sparse sections.
• Chunking thresholds: single-pass at <= 20000 transcript tokens (and whenever the split yields one chunk, up to ~25000); chunk target is 20000 tokens with boundaries snapped to native chapter starts or speech pauses, summarized up to 4 chunks in parallel.
• Transcript strategy:
  • YouTube captions via watch-page / InnerTube requests, with YouTube cookies when configured; --caption-lang prefers an exact match, then the same base language, then another track.
  • youtube-transcript fallback.
  • Whisper STT fallback (whisper-1, audio under 24 MB) when OPENAI_API_KEY is available; skipped under --captions-only (the runner's extract-mode default) or when no API key is set.
• Timestamps render as [M:SS] / [MM:SS] (and [H:MM:SS] past one hour); chapter display times and ?t= links always agree.

Packaging hygiene

• Do not publish generated outputs (e.g., summaries/*.md, summaries/*.txt, summaries/*.json) inside the skill folder.
• Keep only source files (SKILL.md, scripts/, references/) in release artifacts.

Resources

• CLI runner: scripts/run_youtube2md.sh
• Output guidance: references/output-format.md
• Behavior reference: references/summarization-behavior.md
• Security/install notes: references/security.md
• Troubleshooting and error codes: references/troubleshooting.md