Ingest link

ingest-link

Turn one saved link into a trustworthy, cited note in the vault. The value is comprehension + deep research + provenance, not a shallow summary. Never invent; mark what is gated/failed.

Core principle

A saved link becomes second-brain material only after the media is actually comprehended (video frames + audio, not just the caption) and the topic is deep-researched beyond the source. A thin caption is a keyword; the point of sharing the link is the content you could not have typed. If the source is biased or incomplete (marketing, a hot take), research is what stops the vault from storing an ad as if it were neutral knowledge.

Requirements (one-time)

• yt-dlp + ffmpeg — media acquisition + frame/audio extraction (brew install yt-dlp ffmpeg).
• mlx-whisper (optional, Apple silicon) — spoken-audio transcription (pipx install mlx-whisper). Without it, video is comprehended from frames + caption only, and speech-heavy clips are marked extraction_status: partial.
• The agent runtime must provide multimodal image reading, WebSearch, and WebFetch (e.g. Claude Code).

Config

• SKILL_DIR — this skill's install directory (e.g. ~/.claude/skills/ingest-link).
• VAULT_INBOX — your Obsidian inbox, e.g. <vault-or-output-dir>/Inbox (created if missing; notes land here for review, never straight into durable notes).
• INGEST_FPS (default 0.5 = 1 frame/2s), INGEST_MAX_FRAMES (default 24).
• Research engine: native WebSearch + WebFetch (proven adequate). Optional Exa seam — see Layer 2.

Legal / scope guardrail

Only process content the user has legitimate access to (their own saved public links). Do not mass-scrape strangers' private content. For gated content, mark it gated — do not fabricate.

Step 0 — setup

WORK=$(mktemp -d /tmp/ingest-link-XXXXXX)
SKILL_DIR="${SKILL_DIR:-$HOME/.claude/skills/ingest-link}"
echo "WORK=$WORK"

Record the URL passed by the user as $URL.

Layer 1 — acquire + comprehend the media

Run the fetcher (it decides video vs not):

bash "$SKILL_DIR/scripts/fetch-media.sh" "$URL" "$WORK"

If it prints VIDEO:

1. Read each PNG in $WORK/frames/ (you are multimodal — read the on-screen text, diagrams, code, UI, and the visual sequence/animation, not just one frame).
2. If transcript= points to a file, read it (spoken audio). If transcript=none and the clip looked speech-heavy, note that audio was NOT transcribed (whisper absent) → set extraction_status: partial.
3. Also fetch the page's OpenGraph caption for context: WebFetch $URL → grab og:title / og:description (the author's caption).
4. Comprehend: write down, in your own words — the real content the video teaches (worked examples, sequence, claims), plus any URLs/tools/entities shown.

If it prints NOT_VIDEO (exit 3): it's an article/repo/paper/social-text post.

1. WebFetch $URL → main text. For a social post, also grab the OG caption.
2. Extract: topic, key claims, and outbound links (a thin post is a pointer — the value is often what it links to; note those links for Layer 2).

At the end of Layer 1 you must have: a clear statement of what the source actually says/shows, its topic/entities, its claims, and any links it points to.

Layer 2 — deep research (go beyond the source)

1. WebSearch the topic/entities for: verification of the claims, criticism / counter-evidence, alternatives / competitors, and recent changes.
   • Prefer queries that surface divergent angles ("X criticism", "X vs alternatives", "X problems <year>") — semantic-similar queries just return the source's own framing.
2. WebFetch 2-4 authoritative or critical sources for real quotes + citation URLs.
3. Note source bias when you see it (e.g. vendor blogs ranking themselves).

Optional Exa seam (only if native WebSearch misses the right niche docs on a real seed — on tech topics native has tested at least as well, so default OFF):

# EXA_KEY=$(cat <path-to-exa-key>)
# curl -s https://api.exa.ai/search -H "x-api-key: $EXA_KEY" -H 'content-type: application/json' \
#   -d '{"query":"<seed>","numResults":8,"type":"auto","contents":{"text":{"maxCharacters":800}}}'

Layer 3 — synthesize, dedup, write

Dedup first — do not create a duplicate:

INBOX="$VAULT_INBOX"; mkdir -p "$INBOX"
grep -rl "source_url: $URL" "$INBOX" 2>/dev/null || echo "NO_DUP"

If a note with this source_url exists, update it instead of writing a new file.

Write the note using this schema. Provenance discipline: separate what the SOURCE said from what EXTERNAL research found. Cite every external claim with a URL.

---
source_url: <url>
source_type: article | repo | paper | video | social | product | unknown
captured_at: <ISO8601>
analysis_depth: surface | standard | deep
confidence: high | medium | low
extraction_status: complete | partial | gated | failed
comprehension: <what was actually read — e.g. "video frames + transcript + external docs">
tags: []
---

# <Title>

## TL;DR

## What the source actually says/shows
<from Layer 1 — for video, the visual/spoken content beyond the caption>

## Claims (source) vs verification (research)
| Claim (source) | Verified? / counter-evidence (cited) |

## What the source left out
<from Layer 2 — criticism, alternatives, recency the source omitted>

## Evidence and citations
<URLs: the source + every external doc used>

## Why it matters / who should care

## Extraction limits
<what was gated/failed/not transcribed; source bias noted>

## Promotion recommendation
<keep in inbox | promote to durable if ...>

Filename: <INBOX>/<yyyy-mm-dd>-<slug>.md (slug from the title, kebab-case).

Step final — report + cleanup

• Tell the user: note path, a 3-line summary, and explicitly what was gated or missed.
• rm -rf "$WORK" (keep frames only if the user asks).

Rules

• Never invent content. Thin/gated source → say so, lower confidence, mark extraction_status.
• Deep research must surface what the source omitted — don't just parrot the source.
• Human keeps control: notes land in the inbox for review, never straight into durable notes.

Relationship to sibling skills

• youtube-second-brain — YouTube-specific transcript→note workflow. ingest-link generalizes to any source and adds video-frame comprehension + a deep-research layer.
• raindrop-bookmark-curator — organizes Raindrop bookmarks (titles/tags/collections). Pair them: curate with raindrop, then ingest-link the ones worth a full note.