YouTube Summary (youtube2md)

Use the official youtube2md CLI behavior from the package/repository, with this skill's full-mode default model set to gpt-5.4-mini.

Runtime + security prerequisites

• Require Node.js 18+.
• Require preinstalled youtube2md on PATH.
  • Recommended pinned install: npm i -g [email protected]
• Require python3 for transcript text preparation (prepare.py) in simple/transcript modes.
• 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.
• OPENAI_API_KEY enables full summarization mode; transcript and/or audio-derived content may be sent to OpenAI through youtube2md's workflow.
  • For sensitive content, omit OPENAI_API_KEY and use simple or transcript mode when captions are available.
• Full-mode runner default model is gpt-5.4-mini.
  • Override per run with the fifth runner argument: scripts/run_youtube2md.sh <url> full <output_md_path> <language> <model>.
  • Override by environment with YOUTUBE2MD_DEFAULT_MODEL=<model> when the fifth argument is omitted.
• YOUTUBE_COOKIES_PATH or YOUTUBE_COOKIE_HEADER can be used when YouTube blocks anonymous caption/audio access.
• In sensitive environments, audit upstream [email protected] 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.
   • 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. Choose mode

   • Full mode: generates Markdown with youtube2md's summarization pipeline.
     • If OPENAI_API_KEY is visible/available and external API use is acceptable, try full mode first.
     • Defaults to model gpt-5.4-mini through the runner.
   • Simple mode: uses youtube2md --extract-only internally, prepares transcript text (.txt), then summarizes from that transcript.
     • Use when API key is unavailable, content is sensitive, external API use is not acceptable, or full mode fails/falls back.
   • Transcript mode: uses youtube2md --extract-only internally and returns/prepares transcript output without a summary.
     • Use when the user asks for transcript extraction, transcript-only output, raw transcript, or machine-readable transcript JSON.
   • Prefer a no-error path: check key first and run simple mode directly when key is missing and the user asked for a summary.

3. Run converter

   • Preferred runner script:
     • scripts/run_youtube2md.sh <url> full [output_md_path] [language] [model]
       • If OPENAI_API_KEY is missing, runner auto-falls back to the internal extract path; disclose summary output as simple mode.
       • If [model] is omitted, runner passes --model gpt-5.4-mini unless YOUTUBE2MD_DEFAULT_MODEL is set.
     • scripts/run_youtube2md.sh <url> extract [output_json_path]
       • extract is the runner/CLI mode name.
       • Disclose it as simple when summarizing from the prepared .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
   • 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
   • Runtime controls:
     • Use only locally installed youtube2md executable.
     • Do not use runtime npm execution (npx) for this skill.
   • Direct CLI equivalent:
     • youtube2md --url <url> [--out <path>] [--out-dir <dir>] [--lang <language>] --model gpt-5.4-mini
     • Add --extract-only for simple/transcript modes.
     • Add --json for machine-readable status/errors.
     • Add --stdout to write output to stdout instead of a file.

4. Verify output

   • Full mode: Markdown file exists and is non-empty unless --stdout is used.
   • Simple mode: JSON file exists and prepared TXT file exists and is non-empty when file output is used.
   • Transcript mode: JSON or TXT transcript output exists and is non-empty, unless --stdout is used.
   • If using --json, parse ok: true/false and handle error code.

5. Respond to the user

   • Follow references/output-format.md as the default response shape.
   • Follow references/summarization-behavior.md for source policy and chapter/takeaway density.
   • Do not include generated local file path(s) in normal user-facing replies.
   • Share file paths only when explicitly requested by the user (e.g., debugging/export workflows).
   • Summary source policy:
     • Full mode succeeded -> use youtube2md Markdown output as the summary source.
     • Simple mode -> use prepared .txt transcript text as the summary source.
     • 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; OPENAI_API_KEY unavailable) 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 key is missing, 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 (CLI extract): ./summaries/<video_id>.json
  • Local runner post-process (simple/transcript modes): ./summaries/<video_id>.txt via prepare.py
• Skill runner default full-mode model: gpt-5.4-mini unless the fifth runner argument or YOUTUBE2MD_DEFAULT_MODEL overrides it.
• Upstream youtube2md package default model: gpt-5-mini when no model is passed directly; this skill normally passes its own default.
• Transcript strategy:
  • YouTube captions via watch-page / InnerTube requests, with YouTube cookies when configured.
  • youtube-transcript fallback.
  • Whisper STT fallback when OPENAI_API_KEY is available; skipped in simple/transcript modes without an API key.

Packaging hygiene

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

Resources

• CLI runner: scripts/run_youtube2md.sh
• Transcript text prep: prepare.py
• 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