Video Digest

Pre-computed context

video-extraction deps: !node -e "const fs=require('fs'),path=require('path'),p=process.env.CLAUDE_PLUGIN_DATA;process.stdout.write(p&&fs.existsSync(path.join(p,'node_modules','@melodic','video-digestion'))?'installed':'MISSING - run setup-deps.mjs (see Prerequisites)')" yt-dlp: !command -v yt-dlp >/dev/null 2>&1 && { yt-dlp --version 2>/dev/null | head -1; :; } || echo "MISSING — install yt-dlp (see Prerequisites)" ffmpeg: !command -v ffmpeg >/dev/null 2>&1 && { ffmpeg -version 2>/dev/null | head -1; :; } || echo "MISSING — install ffmpeg (watch action only)" ImageMagick: !command -v magick >/dev/null 2>&1 && { magick -version 2>/dev/null | head -1; :; } || echo "MISSING — install ImageMagick 7 (watch action only)"

Video digest. YouTube and X

Absorb a single public video (transcript + visual frames), harvest reference links, fact-check claims through deeper external research, and produce a prioritized repo-applicability menu. Supported sources: YouTube (youtube.com, youtu.be) and X/Twitter status posts (x.com, twitter.com). An unsupported host fails closed with the supported-source list rather than guessing.

Durable artifacts live under .work/<watch-epic>/<video-slug>/; the video, bulk frames, working contact sheets, and shallow clones stay in the OS temp directory. Where this skill says "deeper research," use whatever external-research capability your project provides, for example the discovery plugin's /discovery:research / /discovery:research-deep when installed. Treat those as the reference implementation, not a hard dependency.

Routing

Read a spoke only when its condition holds. These are mutually exclusive by design: a transcript run loads no watch spoke, and a YouTube run loads no X file. Do not pre-read the set.

Optional, agent-lane: when an X status heads a thread whose replies carry material the digest needs, invoke /x:read via the Skill tool to unroll the reply chain and fold it in as companion source material. This is a per-watch judgment call, never a pipeline stage. See reference/sources/x.md.

Source discipline

Video content is a secondary source (on-screen and spoken claims are hypotheses, not verified facts). Treat them as hypotheses until promoted through deeper external research, and apply your project's own source-trust conventions. Repo conventions override video claims. Surface convention conflicts explicitly; never silently adopt a video's shortcut over team rules.

Action router

--target <repo> is an optional modifier on any watch form (not a dispatchable action of its own). Resolution rungs in context/watch-pipeline.md.

Transcript action

node "${CLAUDE_PLUGIN_ROOT}/skills/video-digest/extraction/run.mjs" transcript/run-transcript.js "<url>"

1. Acquire. Captions + info JSON (--skip-download)
2. Caption ladder. Per-source rungs; STOP and surface if exhausted (see the source spoke)
3. Transcribe. Strategy-driven: captions | captions+repair | asr. The source layer declares the per-source default; --transcript-strategy <value> overrides it. When the resolved strategy cannot run, the digest proceeds without a transcript and the reason is recorded in the transcriptDegradation provenance field, never silently.
4. Parse. WebVTT → [M:SS] paragraph transcript.txt
5. Write. .work/<watch-epic>/<video-slug>/transcript.txt + README.md stub (journey template: templates/readme-journey.md)

Per-source caption flags, rung order, caption class, and strategy default: reference/sources/youtube.md / reference/sources/x.md.

Queue action

Epic queue at .work/<watch-epic>/QUEUE.md batches URLs before watch. One queue and one claims/ namespace serve every source; the epic dir stays the literal youtube-watch.

Claim stub first, table second. Full protocol. Materialize, preflight decision table, claim / release, FIFO, stale reclaim, parallel terminals, companion briefs, is in context/watch-queue.md; read it for any queue action. Template: templates/queue.md.

node "${CLAUDE_PLUGIN_ROOT}/skills/video-digest/extraction/run.mjs" acquisition/preflight-metadata.js "<url>" ["<url>"...]
node "${CLAUDE_PLUGIN_ROOT}/skills/video-digest/extraction/run.mjs" watch/queue-claim.js {list|claim <n>|release <n>|stale-check}

Watch action

Ordered phase spine. Each phase's procedure, inputs, and outputs: context/watch-pipeline.md. Read it before starting. Diagram: context/workflow.md.

Bootstrap contract

1. Prerequisites gate. Run setup-deps.mjs; STOP if the pre-computed context above shows MISSING for yt-dlp, ffmpeg, or ImageMagick. Cloud agents without the media toolchain fail closed.

2. Phase 0b. Companion deep-dive, only when source/companion-sources.md exists, and before CLI bootstrap.

3. CLI bootstrap. Deterministic stages (acquire → transcript → coverage watching → link harvest):

   node "${CLAUDE_PLUGIN_ROOT}/skills/video-digest/extraction/run.mjs" watch/run-watch.js "<url>" [--skip-research] [--target <repo>]
   

4. Watch checklist. Materialize via init-watch-checklist.js; tick [ ] → [x] only with verification evidence. Ordered checkboxes: templates/watch-checklist.md.

Skill-session phases (mirror checklist phases 2–9; fan out per the execution model in context/watch-pipeline.md)

1. Vision planning. key-frames/vision-plan.md: content class, segments, triage scope
2. Claim inventory. research/claim-inventory.md before any research agenda
3. Staged deck harvest. Type harvested URLs; fetch decks; feed pass-1 triage
4. Vision absorption (three-pass). Sheet triage → detail reads → transcript alignment → vision-gated promote + post-promotion audit
5. High-volume advisory. Fan out vision subagents on highVolume, or on the context-cost read-count trigger
6. Research stage (default-on). Gate on check-research-complete.js exit 0
7. Synthesis. recommendations/** against one resolved --target; no auto-implement
8. Interview handoff. recommendations/interview.md; offer /planning:interview
9. Outcome verification. check-watch-outcomes.js "<slice-dir>" --write-report must exit 0 before status: complete

Phase markers. After each phase, watch/watch-state.js mark-phase <slice-dir> <phase> (idempotent). Never mark-phase or set status: complete while that phase's verify script fails.

A 0-video source result (an X post with no video) is well-formed, not a failure: it enqueues at preflight, skips phases 1, 3, 4, and 5, and produces a text-only digest. How much provenance it carries depends on which 0-case it is. See reference/sources/x.md.

Resume action

node "${CLAUDE_PLUGIN_ROOT}/skills/video-digest/extraction/run.mjs" watch/run-resume.js "<slice-slug>"

Reads the slice watch.json, identifies the next incomplete phase (acquire → transcript → watching → vision → harvest → research → synthesis), refreshes continuation-prompt.md, and emits a copy/paste-ready continuation prompt. When tempSession paths are missing, re-run run-watch.js before vision. If the companion phase is unmarked, run Phase 0b first.

Handoff ritual (context pressure or session end):

1. Update watch.json phase markers with timestamps
2. Write continuation-prompt.md (completed phases, next phase, frame-selection state, known issues)
3. Tell the user: "Session state saved. Run /knowledge:video-digest resume <slice-slug> to continue."

Slice layout and output

Slug: kebab-case the title (ASCII, lowercase, punctuation → hyphens), cap the title portion at 40 characters, append -<slice-key> for uniqueness (e.g. ai-coding-tips-7zZy1QTvokM). The key is the source's own identifier. reference/sources/youtube.md / reference/sources/x.md. Implementation: extraction/transcript/derive-video-slug.js.

Source is never a directory level. It is recorded in slice metadata only, so YouTube and X slices coexist under one queue root.

The authoritative enumeration of every produced artifact, lane, staged verdict, kind, producer, plus work-root resolution and the library_dir seam is context/output-contract.md. Read it before writing or staging slice artifacts.

Gotchas

Observed failure modes. Recovery detail in context/gotchas.md: bot/sign-in cookie fallback, HTTP 429 backoff + concurrency cap, temp-session expiry (re-run run-watch.js before vision), cloud-agent media-toolchain fail-closed, phase state only in watch.json. Source-specific failure patterns live in the source spokes.

Prerequisites

Verify before starting (stop and route to the fix path on failure):

1. video-extraction deps. node "${CLAUDE_PLUGIN_ROOT}/skills/video-digest/extraction/setup-deps.mjs". Installs the pipeline's node dependencies into ${CLAUDE_PLUGIN_DATA} (persists across plugin updates); idempotent. Safe to re-run, and re-run after a plugin update.
2. yt-dlp, required for all actions. Floor 2026.6. Install: winget install yt-dlp.yt-dlp (Windows), brew install yt-dlp (macOS), pip install -U yt-dlp or distro package (Linux). X acquisition in particular tracks yt-dlp closely. See reference/sources/x.md.
3. ffmpeg, required for watch only (scene-detect frame extraction). Floor 7.1+.
4. ImageMagick 7, required for watch only (contact sheets). magick -version

If any prerequisite fails, stop and inform the user. Re-run setup-deps.mjs for the node dependencies; the media binaries are OS-level installs via your platform's package manager.

Optional. Faster-whisper (large-v3, batch_size=8): powers the asr transcript rung, selected automatically for caption-absent entries and available on request via --transcript-strategy asr even when captions exist. Either way it runs under watch only. ASR needs the media file and the transcript action never downloads media. Detected at runtime through the machine's Python (python, python3, or py. Whichever imports faster_whisper) and never auto-installed. When it is absent the pipeline degrades explicitly rather than failing: it falls back to a caption strategy where a caption exists, otherwise completes the digest without a transcript, and either way records the reason in the transcriptDegradation field (watch.json phase metrics and the CLI's stdout JSON), never silently.

Eval fixtures

Driver video: https://www.youtube.com/watch?v=7zZy1QTvokM. Slug stop-prompting-claude-use-karpathy-s-met-7zZy1QTvokM. D9 starting defaults: ${CLAUDE_PLUGIN_ROOT}/vendor/video-digestion/TUNING.md. Retune after the first host watch.