tzq-tbw/agent-skills

Video Study Notes

Read the user-selected material and organize concepts, steps, cases, and conclusions. Clearly state the author's viewpoint and AI additions. First describe the actual materials obtained and their scope, then report the content. Do not equate download success, subtitle duration, or transcription completion with semantic verification.

Confirm Input and Output Location

Confirm a single video, selected playlist items, or a local file. For collections where the scope is unclear and affects the task, ask. Preserve original source links and canonical links; remove irrelevant tracking parameters.

Original user files are read-only. In each session, create a unique work/video_tmp/<task ID>/ directory to save media, checkpoints, and temporary frames. Only one write process is allowed per directory. Create a new task directory when changing source, model, or language. Valid retries for the same task reuse the original directory.

Check only the environment needed for this run. See the environment note for commands. Prefer saving to the user-designated notes directory. If unspecified, use an existing, writable Obsidian video notes directory; otherwise, use outputs/ in the current workspace. Append a unique suffix to same-name products; do not overwrite.

Obtain Trusted Materials

Source	Preferred Route	When Reliable Subtitles Are Unavailable
Bilibili	Public API or an already connected and authorized subtitle tool	Configured bili audio --no-split -o <task_dir> or other authorized tool
YouTube	yt-dlp to fetch required subtitles for the selected language	Get audio track; only fetch video stream if frames are needed
Other sites	Existing platform tools or yt-dlp	Switch to a supported fetch route based on actual failure
Local audio/video	Existing subtitles	Run transcription script on the original file

Verify video ID, playlist items, language, whether subtitles are empty, and if sections are obviously missing. Subtitle coverage does not prove sentence-by-sentence correctness. Normal end-of-video silence is not automatically considered missing.

Use public materials first. Do not default to extracting browser cookies, logging in, or adding new channels. For the same failure, attempt no more than two tries with clear changes. Do not retry in a loop, change proxies, or describe connection failure as the video not existing. When blocked, retain any obtained materials and explain the gap.

Transcribe Audio on Demand

When no reliable subtitles are available, first read the transcription command, then use transcribe.py:

1. Clearly select a model, preferring cached ones. Run with --pilot to transcribe the first minute, checking language, content, and speed.
2. If that is usable, run the same command without --pilot to continue full processing with checkpoints. If no cache exists, add --download-model only when a download is truly needed.
3. Read the complete transcript.json to check for empty speech, abnormal repetitions, needs_review, key terms, and numbers. If an important quote spans a minute boundary, listen to the cross-boundary segment.

The script takes 16 kHz mono PCM16 and NumPy input to the recognizer and saves checkpoints per minute. "completed": true only indicates that the processing range has been consumed; it does not prove recognition accuracy. Do not silently switch to a smaller model, and do not download a model just to import a module.

Run only one main recognition pipeline. First verify a small segment, then decide whether to switch. Do not default to running both ASR and OCR on the full material simultaneously. Background single waits should not exceed 60 seconds, and report meaningful progress.

Verify Key Frames

First read the frame selection note. If chapters are available, locate frames by chapter. If not, use topic transitions to establish analyst divisions. Use a small overview to locate frames, then extract only the necessary clear frames.

Code, formulas, tables, settings, and operation steps cannot be conveyed only through speech. When similar frames contain unique information, keep them. Do not use a fixed number of screenshots to replace completeness judgment.

OCR is only used for verifying text within images or as a fallback when no audio track is available. First try reading representative frames to avoid confusing subtitles, body text, and watermarks with spoken content. For low-resolution, obstructed, or unrecognizable formulas, specify the exact time gap. For silent visual videos, describe using visual reading; do not fabricate voice transcriptions.

Write Notes and Evidence

By default, include title, source, duration, actual materials, summary, key topic points, and key timestamps. When users request or when the video is suitable for reproducible operations, also organize workflow, inputs, steps, outputs, and completion criteria. Do not default to attaching the full transcript.

Distinguish between original video facts, author's opinions and cases, and AI additions. Do not present the speed or quantity demonstrated by the author as a universal guarantee. Clearly state the processed scope and any gaps that affect understanding. Do not equate "full-video subtitles obtained" with "sentence-by-sentence verification of the full audio track."

Save screenshots to a persistent attachments directory and embed them as Markdown image links. Notes, attachments, and the accompanying .evidence.json file cannot depend on the temporary media directory. Evidence retains only necessary segments, time ranges, key details, and verification records. Format is described in the evidence note.

Verify and Clean Up

First reread the materials, notes, and attachments. Check the main concepts, methods, cases, and conclusions for each section, as well as important names, numbers, formulas, and steps. In the evidence, truthfully record the scope of review and any unresolved items. Silence or repeated segments can be noted as containing no substantive content; do not fabricate summaries to fill the timeline.

Then run finalize.py to check source, chapters, completion status, persistent files, and gaps. The script only verifies records and files; it does not replace content review. Do not falsify reviewed or passed just to pass the check.

Only add --clean after confirming that the selected materials have been processed, content verification has passed, and persistent files have been successfully read. Cleaning is limited to one direct subdirectory under the current workspace's work/video_tmp. It must reject symbolic links, junctions, or reparse points in the directory and its sub-items. Original files, model caches, and persistent products are not deleted. If cleaning fails or gaps still exist, keep media and checkpoints.

At the end, report the actual materials and processing scope, note location, cleanup result, and limitations. Short video previews, static checks, and import success should be reported according to their real scope; they cannot be treated as full-video acceptance.