Analyze YouTube Video

Resolve the correct YouTube URL, extract a self-contained Markdown transcript with the bundled script, and use it only according to the user's requested task or question.

Feature and Boundary

Prefer subtitle-first processing because it converts a video into compact text before model use. This usually uses substantially fewer input tokens than sending the full video, audio, or sampled frames to a multimodal model, making long-video summarization, extraction, organization, and question answering faster and more economical.

Require an accessible YouTube caption track, either human-authored or automatically generated. Treat videos with no captions, disabled captions, inaccessible private or members-only captions, or captions blocked by region, age, authentication, or YouTube request restrictions as unsupported by this Skill's default workflow.

When captions cannot be retrieved, state that the subtitle workflow cannot process the video. Do not infer the video's contents from its title, thumbnail, description, comments, search snippets, or related coverage. Offer a copy-ready Gemini @youtube prompt in the language of the user's current request so the user can try Gemini's built-in YouTube extension. Also offer audio transcription or multimodal video analysis only as a separate workflow, explain the additional requirements or cost, and obtain the user's permission before proceeding.

Treat transcript-based work as processing of spoken content only. It is not sufficient when the user's question depends on video frames, charts, demonstrations, gestures, on-screen text omitted from captions, speaker identity from the image, music, sound effects, vocal tone, or editing choices.

When those non-text signals are material, tell the user that the subtitle workflow cannot answer reliably by itself. Explain which visual or audio evidence is missing and ask whether to augment or replace it with image, audio, or multimodal video analysis. Do not present a transcript-only conclusion as if the full audiovisual content was inspected.

Canonical Paths

Resolve SKILL_DIR to the installed directory containing this SKILL.md. Do not use the literal placeholder below. Keep these paths canonical:

• Extractor: $SKILL_DIR/scripts/extract_transcript.py
• Channel-feed helper: $SKILL_DIR/scripts/list_channel_feed.py
• Dependency lock: $SKILL_DIR/requirements.txt
• Virtual environment: $SKILL_DIR/.venv/
• Temporary Markdown transcripts: tmp/youtube-analysis/
• Durable user-requested studies: research/youtube/<YYYY-MM-DD_topic>/

Keep $SKILL_DIR/scripts/extract_transcript.py as the single source of truth. Treat the Python script as a subtitle extractor only; do not embed a fixed analysis framework in it.

Workflow

1. Resolve the Request

Identify:

• the target channel, creator, video, or topic;
• whether the user wants the latest upload or a particular date/title;
• whether Shorts, livestreams, premieres, members-only videos, or reposts are in scope;
• the exact task, question, output format, and requested depth.

Use an explicit user-provided URL directly after validating that it is a YouTube URL. When the user names a channel or asks for the latest video, search the current internet and prefer the official channel or official video page. Verify the channel identity, title, URL, and any explicitly sourced upload date needed to select the correct video before extracting subtitles. If the date cannot be confirmed, do not infer it; use other verified selection evidence or ask a concise question when the candidates remain ambiguous.

For the latest upload, recent uploads, or a date range likely covered by the channel's current feed, prefer YouTube's official channel RSS feed after resolving the official channel ID. Make one feed request, save the result, and reuse it for the task instead of repeatedly searching or opening one page per candidate:

mkdir -p tmp/youtube-analysis
"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/list_channel_feed.py" \
  "CHANNEL_ID_OR_CHANNEL_URL" \
  --output "tmp/youtube-analysis/CHANNEL_ID.feed.json"

The feed helper accepts a UC... channel ID or an official /channel/UC... URL. A handle such as @creator must first be resolved to the official channel ID through the channel page or current web search. Treat the feed's published value as an official publication timestamp and convert it from UTC to the user's relevant timezone when presenting a schedule. Do not confuse updated with publication time. Retain the feed JSON as selection evidence for the active task.

The RSS feed exposes only a recent window and does not itself prove whether an entry is a completed standard upload, Short, premiere, or livestream, or whether captions are available. Apply the user's scope, verify ambiguous entry types using the official video or channel page, and fall back to the official channel page or current search when the requested history is outside the feed window. RSS discovery finds candidate URLs; it does not replace caption extraction.

Keep this discovery helper separate from transcript storage. Its temporary JSON output is selection evidence for the active task only. This Skill does not create or maintain annual transcript indexes, year catalogs, archive feeds, or retained RSS products; those belong to a separate archive system when needed.

Treat URL parameters such as t=51s, start=51, or timestamp fragments as playback navigation only. Unless the user explicitly asks to start at that time, analyze that segment, or restrict the task to a stated range, extract and process the complete video from the beginning. Do not infer a partial-video scope merely because the submitted URL contains a timestamp. When the user explicitly requests a segment, preserve enough context before and after the range to interpret it accurately.

For “latest video,” normally select the newest completed public upload with usable content. Do not substitute a scheduled premiere, still-running livestream, Short, or third-party repost unless it matches the request. If two candidates remain materially ambiguous, ask one concise question.

2. Check and Bootstrap the Environment

Check existing state before installing anything:

command -v python3
python3 --version
test -f "$SKILL_DIR/scripts/extract_transcript.py"
test -f "$SKILL_DIR/scripts/list_channel_feed.py"
test -f "$SKILL_DIR/requirements.txt"
test -x "$SKILL_DIR/.venv/bin/python"

If the bundled extractor or requirements file is absent, report that the Skill installation is incomplete and offer to reinstall it. Do not reconstruct missing package files from memory. The requirements file contains:

youtube-transcript-api==1.2.4
requests==2.32.5
urllib3<2

If python3 exists but the virtual environment is absent, initialize it and install only inside that environment:

python3 -m venv "$SKILL_DIR/.venv"
"$SKILL_DIR/.venv/bin/python" -m pip install -r "$SKILL_DIR/requirements.txt"

If the environment exists, avoid reinstalling on every run. Verify the dependency first:

"$SKILL_DIR/.venv/bin/python" -c "from youtube_transcript_api import YouTubeTranscriptApi; print('ok')"

If verification fails, rerun the requirements installation. Do not use global pip, sudo pip, or modify the system Python environment.

Require Python 3.9 or newer. If Python itself is missing, unusable, or too old to create the environment, stop before installing it. Tell the user that Python is required, state the detected problem and proposed installation method, explicitly offer to install it, and obtain the user's permission before running Homebrew, an OS installer, pyenv, or any other Python installation command. Treat a sandbox or network approval as separate from this user authorization.

If venv or pip is missing because the Python installation is incomplete, apply the same authorization rule before installing or replacing system-level Python components. Running ensurepip inside an already-created project virtual environment is allowed.

3. Extract the Transcript and Metadata

Create a temporary task directory and write one self-contained Markdown transcript. This is the sole default persistent transcript artifact; do not create companion JSON or TXT files:

mkdir -p tmp/youtube-analysis
"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/extract_transcript.py" \
  "YOUTUBE_URL" \
  --languages "USER_LANGUAGE_CODES" \
  --output "tmp/youtube-analysis/"

When --output points to an existing directory, the extractor names the document YYYY-MM-DD<video-id>.md, for example 2026-08-21hSpi0XG7xDQ.md. It uses only a verified upload_date or publish_date; a date parsed from the title is never treated as verified. If neither verified date exists, the name is undated-<video-id>.md. Passing an explicit file path remains supported and preserves that exact path.

Set --languages from an explicitly requested transcript language; otherwise use the language of the user's current request. For example, use ja for Japanese, en for English, and zh-Hans,zh-Hant,zh for Chinese. The extractor selects a track in this order: the supplied language codes, the language conservatively inferred from the video's parsed title, English, then any accessible caption track. Within the same language, prefer a human-authored track. A language mismatch is not a no-caption result: if a video has captions only in another language, extract them and let the model work from the actual track while reporting its language and automatic/manual status.

Do not use HTTP Accept-Language as a substitute for caption-track selection. The extractor passes a dedicated requests.Session with a normal desktop-browser User-Agent to youtube-transcript-api; this can improve request compatibility but does not bypass IP, authentication, region, age, or rate-limit controls.

Read the complete Markdown transcript before drawing conclusions; do not analyze only the first lines or search snippets.

The bundled extractor waits a random 2–6 seconds before each subtitle request. Keep this pacing when running repeated extractions; it reduces burst traffic but does not bypass YouTube blocking. If YouTube returns RequestBlocked, IPBlocked, HTTP 429, or a similar rate-limit error, stop increasing request volume, report the endpoint family and error, and use the Gemini handoff or ask the user for another authorized workflow.

Use the Markdown document's YAML frontmatter and timestamped transcript together. The frontmatter retains all video and caption-track metadata. Each transcript item retains the original floating-point start and duration, plus a millisecond-readable clickable timestamp. Use the floating-point values for evidence selection and chunking; convert start to integer seconds only for YouTube's t=SECONDSs navigation parameter.

Resolve video metadata in this fixed fallback order:

1. Use the extractor's parsed YouTube video-page metadata.
2. If title or channel is still missing, use the extractor's YouTube oEmbed fallback.
3. If required metadata remains missing, search the current web and use the official YouTube video/search result where possible.

When the video was selected from the official channel RSS feed, its retained published timestamp is also valid publication-date evidence. Keep that discovery evidence separate from the transcript document instead of pretending the extractor returned it.

Inspect video.metadata_sources, video.metadata_errors, and video.date_status in the Markdown frontmatter before presenting metadata. A metadata failure does not by itself mean subtitle extraction failed. Never infer an upload or publication date from the title, video ID, surrounding search results, channel cadence, or current date. Use a date as an upload/publication date only when the source explicitly identifies it as such. If only video.title_date is available, label it explicitly as title date (or the equivalent in the response language) and make clear that it is not a verified upload/publication date. If no date can be confirmed, label it date unknown (or the equivalent in the response language).

If the extractor reports that no caption tracks are accessible after its any-language fallback, report that the video lacks accessible captions or that YouTube blocked the request. Do not invent an analysis from the title and description. Then provide a copy-ready Gemini prompt using the user's current request language, the exact target URL, and the substantive task from the user's original request. Preserve the requested task type, focus, level of detail, and output format instead of forcing a fixed summary structure. Items such as core themes, viewpoints, itemized information, or recommendations are examples only and should appear only when they fit the user's request. For a Chinese request, use this adaptable template:

@youtube
请使用你内置的 YouTube 扩展程序，直接读取并分析这个视频：YOUTUBE_URL

请按照我最初的要求完成以下任务：
USER_REQUEST

请根据上述要求自行选择最合适的分析结构、重点、详细程度和输出格式，不要机械套用固定模板。
请严格对齐时间轴：在关键结论、回答或提取结果后标注对应的精准时间，以带有 ?t=xxx 的链接，链接到原视频的对应位置。

Replace YOUTUBE_URL with the canonical video URL and USER_REQUEST with a concise restatement of the user's substantive original task before presenting the prompt. Do not copy unrelated conversation context, private data, or setup discussion into USER_REQUEST. If the current message is shorthand such as “这个视频呢”, inherit the task from clear conversation context; ask a concise clarification only when the intended task would materially change the result and cannot be inferred safely. For another request language, translate the prompt naturally into that language while retaining @youtube, the target URL, the user's actual task, and the requirement for precise ?t=xxx links after relevant results. Present this as an option the user can paste into Gemini; do not claim that Codex ran Gemini, that the extension is available to every account, or that the resulting timestamps are guaranteed accurate.

Do not automatically fall back to downloading video, transcribing audio, or sending the YouTube URL to a multimodal model. Ask the user before expanding Codex's own workflow to audio transcription or multimodal analysis. Merely providing the copy-ready Gemini prompt does not require that additional permission because it does not execute or transmit the video on the user's behalf.

When YouTube appears rate-limited or blocked, report the host or endpoint family and observed error, then stop increasing request volume.

4. Use the Transcript According to the Prompt

Let the user's prompt determine what to do with the transcript. Do not force a generic summary, viewpoint-analysis template, stock-analysis template, or fixed list of fields. The extractor's role ends after producing timestamped subtitle text.

Adapt to common task types:

• For an abstract or summary, match the requested length and level of detail while preserving the speaker's main structure and qualifications.
• For viewpoint organization, group claims, reasoning, evidence, predictions, actions, and caveats without turning inference into a direct quotation.
• For outlines, timelines, key points, entities, numbers, or other structured extraction, use the format requested by the user and retain the supporting timestamps.
• For comparison across multiple videos, extract each transcript separately and preserve the video identity and timestamp provenance of every conclusion.
• For RAG-style question answering, treat the transcript as the retrieval corpus. Retrieve the passages relevant to the question, answer only from supported content, add timestamp links, and say clearly when the transcript does not contain enough evidence to answer.

When a transcript is too long for reliable direct use, split it into coherent timestamp-preserving chunks, retrieve the most relevant chunks for the user's question, and keep enough neighboring context to avoid misreading isolated sentences. Do not discard timestamp provenance during chunking.

Distinguish clearly between:

• statements made by the speaker;
• conclusions inferred from the transcript;
• facts independently verified from external sources.

For time-sensitive fact-checking or market validation, browse current primary sources and label that work as external verification. For transcript-only summarization, organization, extraction, or question answering, do not imply that the speaker's claims were independently verified.

Read the complete transcript when the task depends on overall context. For targeted RAG-style questions, inspect the retrieved passages plus their surrounding context. Complete the requested task directly and quote only short excerpts when useful. Do not reproduce the full transcript in the response unless the user explicitly requests it and doing so is permitted.

5. Add Clickable Time Footnotes

Add a clickable timestamp footnote after a result sentence when the user would benefit from locating the speaker's original words. Prioritize summary conclusions, organized viewpoints, direct answers, disputed claims, numbers, price levels, forecasts, stated positions, and actions. Do not attach a link mechanically to every sentence.

Use this inline Markdown form:

The speaker argues that demand is slowing as financing costs and weak income growth weigh on spending. ([00:33](https://www.youtube.com/watch?v=VIDEO_ID&t=33s))

Normalize links to:

https://www.youtube.com/watch?v=VIDEO_ID&t=SECONDSs

Select evidence and supporting segments from the Markdown timeline's original floating-point timestamps. Convert to integer seconds only when constructing a new YouTube t=SECONDSs URL. Use the start of the supporting subtitle segment, or a few seconds earlier when necessary to preserve context. When one sentence depends on multiple distant passages, append multiple timestamp links. Keep the visible label human-readable, such as [00:51] or [01:12:34].

These links support source navigation; they are not independent fact-check citations. State separately whether any external verification was performed.

6. Deliver the Result

Include the video title, channel, verified upload/publication date when available, and clickable YouTube URL, followed by the summary, organization, extraction, grounded answer, comparison, or analysis requested by the user. When the date is not verified, use title date or date unknown in the response language according to the rules above rather than presenting an estimate. Add timestamp footnotes where they materially improve traceability. Mention uncertainty caused by automatic captions, translation, missing context, or unclear wording, using the Markdown frontmatter's transcript-track metadata rather than guessing the caption type.

Keep transcripts in tmp/youtube-analysis/ for the active task and follow-up questions. Move them and any durable analysis into research/youtube/<YYYY-MM-DD_topic>/ only when the user asks to retain the work or when the task explicitly calls for a durable research deliverable.