Video Deep Reader

What It Does

Turn a YouTube video or supplied transcript into a useful reading artifact:

• Quick: decide in a minute whether the video is worth watching.
• Deep: understand the argument, evidence, structure, and important timestamps.
• Research: verify selected material claims against public primary sources.

The bundled fetch helper retrieves public metadata and subtitles; Research mode may additionally verify selected claims with public sources. The agent creates the semantic notes from these inputs.

Bundled components are deliberately separate:

• fetch_video.py --doctor checks the local dependency and optional network readiness.
• fetch_video.py retrieves public metadata and subtitles into the declared temporary cache.
• fetch_video.py --retrieve-video returns timestamped excerpts from that cache by validated video ID.
• The agent applies this file and references/output-modes.md to create the semantic notes.

When to Use

Invoke when the user:

• provides a YouTube URL or video ID and asks to summarize, analyze, or understand it;
• pastes or uploads a transcript and asks for video notes;
• asks a follow-up question about a previously fetched video;
• wants to compare several videos or decide which one deserves deeper attention;
• asks to verify important claims made in a video.

A bare YouTube URL is enough only when the message is clearly asking the assistant to process that video. Do not activate when a link is merely cited, shared as a reference, requested for playback or download, or included as one source inside an unrelated task.

Do not invoke for:

• downloading the video or audio;
• bypassing login, age, geographic, paywall, or access controls;
• summarizing a video that has neither accessible subtitles nor a user-supplied transcript;
• publishing derived content without an explicit request.

Output Language

Respond in the language of the user's current request. If unclear, ask once. Preserve quotations in their original language and add a translation only when useful.

Bundled scripts emit machine-readable JSON, status codes, and transcript text rather than a localized natural-language interface. Explain their results in the language of the user's current request.

Select the Mode

If the requested depth is ambiguous, use Quick as the content mode. Still follow host confirmation requirements for package installation, file creation, and every other state-changing action.

Step 1: Check the Environment

Run the read-only doctor before the first URL fetch in a session:

python3 <skill_dir>/scripts/fetch_video.py --doctor

Add --network only when a network diagnosis is needed. If a local proxy should be tested, pass its loopback port explicitly with --proxy-port; Doctor does not scan local ports. Doctor never installs packages or changes configuration.

If the pinned dependency is missing, show the exact repair command:

python3 -m venv .venv
.venv/bin/python -m pip install --require-hashes -r <skill_dir>/requirements.lock

Do not install anything without explicit user approval.

Step 2: Get a Transcript

YouTube URL or video ID

Run:

python3 <skill_dir>/scripts/fetch_video.py "<youtube-url>"

For a local proxy, pass only the loopback port:

python3 <skill_dir>/scripts/fetch_video.py "<youtube-url>" --proxy-port 7890

The script:

• validates YouTube hosts and video IDs;
• calls the pinned yt-dlp Python API directly;
• never invokes a shell or external executable;
• accepts only a loopback proxy port and no proxy credentials;
• writes meta.json and transcript.txt to a private per-user cache under the system temporary directory;
• prints the cache directory as JSON.

The cache hierarchy must be owned by the current user with 0700 directory permissions. Cache files use atomic replacement, 0600 permissions, and reject symbolic links. Temporary cache is not a durable archive. Create a user-visible note file only when the user explicitly requests one.

Supplied transcript

If the user provides transcript text or a transcript file, skip YouTube fetching. Treat it as User-provided transcript and preserve any timestamps already present.

No subtitles or failed fetch

Do not stop at “unsupported.” Offer the smallest viable fallback:

1. Ask the user to paste or upload a transcript.
2. If the user already supplied an audio/video file, use an available transcription capability only with the user's request.
3. If neither is available, explain the exact limitation without inventing content.

Step 3: Produce the Requested Output

Follow references/output-modes.md.

Quick

Keep it to one screen:

• title, channel, duration, and source link;
• 2–3 sentence summary;
• five timestamped takeaways;
• one “worth watching if…” judgment;
• important uncertainty or missing context.

Deep

Include:

• concise overview;
• timestamped structure;
• argument map: claim → reasoning → evidence → limitation;
• Video statement and Author opinion as separate labels;
• notable quotations;
• unanswered questions and useful follow-ups.

Do not call a statement a verified fact merely because it appears in the video.

Research

Start from Deep, then verify only material claims that affect the conclusion.

• Prefer primary sources, official documentation, papers, or original datasets.
• Attach each verification result to the corresponding video timestamp.
• Label each claim Supported, Partly supported, Contradicted, or Not verified.
• State source date and scope.
• Do not perform broad web research when the user only asked for a summary.

Batch Quick

For each video provide:

• one-sentence thesis;
• three key timestamps;
• evidence quality;
• novelty;
• recommendation: Deep now / Save / Skip.

Compare videos only on common dimensions.

Follow-up Retrieval

The retrieval script accepts a video ID, never an arbitrary file path:

python3 <skill_dir>/scripts/fetch_video.py --retrieve-video <video-id> --keyword "attention"
python3 <skill_dir>/scripts/fetch_video.py --retrieve-video <video-id> --at 3:20
python3 <skill_dir>/scripts/fetch_video.py --retrieve-video <video-id> --list

It reads only transcripts created under the managed temporary cache. Quote the relevant timestamp range in the answer.

Content Integrity

• Preserve what the source actually says; remove filler, not substance.
• Separate a video's claims from external verification.
• Keep numbers, dates, named entities, caveats, and uncertainty.
• Trust visible slide text over an obvious transcription error when the user supplies frames or screenshots.
• Do not attribute a claim to a speaker unless the source supports the attribution.
• Do not turn the summary into promotional copy unless explicitly requested.

Completion Standard

• The selected mode matches the request.
• Every major point can be traced to a timestamp or labeled transcript section.
• Claims and opinions remain separate.
• Research mode includes source-backed verification and scope.
• Fetch failures produce a usable transcript fallback.
• No package installation, durable file write, publishing, or external state change occurs without explicit approval.