atrislabs/atris/youtube

YouTube Skill

Route first: learning vs product

Two rails. Pick one before running anything.

• Learning rail (free): atris youtube notes URL or atris youtube teach URL. Local yt-dlp captions plus a local AI writer, zero credits, no login. Use it when the ask is "learn from", "notes on", "alpha", "rabbit hole", "what does this say". This replaces the old alpha-learn skill.
• Product rail (5 credits): atris youtube process URL (bare atris youtube URL is the same call). Stores the analysis in the Atris backend, needs a stored login, and is gated on a filled Apply. Use it only when the ask is "process", "store", "add to knowledge", or --agent ID --store.

Process is gated. It exits 2 with write one apply (change + receipt) before process. until atris/wiki/briefs/youtube-<id>.apply.md (relative to the current directory) has real change: and receipt: lines. fill this does not count, and a notes/search keep-sidecar (change: apply atris/experiments/...) does not count. The CLI prints the exact file on the next line. It writes a fill-this stub there only when atris/wiki/ already exists; otherwise create the file yourself. The gate runs before any login or billing, so a refusal never spends credits. Write the Apply from what the person will actually change, not a placeholder.

Notes writer: Gemini Flash through the Antigravity CLI (agy -p) when installed, else Haiku (claude), then Codex, then Cursor. The Antigravity editor's own agy launcher has no -p mode and is skipped. notes by <writer> names who wrote them. check: fill this after notes, teach, or search means the video had no number or named mechanism to build a check from; it is not an error.

Feature map

Hard path. Follow in order. Soft memory does not override this.

search QUERY (free)
    |
   rows --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
        --> thin: check: fill this, then next: atris youtube teach <first-url>
        --> --json stays quiet
    |
   429 --> printed rows? use them (no retry). warning/NA/None print lines are not rows
        --> else CLI retries once
        --> cached rows printed? use them (same rich mint or thin check as live rows)
        --> rate-limit sentence printed? STOP
             do not run --paid
    |
   pick a URL --> notes URL (free, ephemeral unless --save)
    |                 rich ephemeral prints one apply next-step and one failing check (score 0), no files
    |                 thin ephemeral prints check: fill this instead of inventing a check
    |                 then next: atris youtube teach <same-url>
    |                 --json stays quiet
    |                 --save files brief + pack-named apply when notes have a number or named mechanism; a multi-url --save batch proves the first saved pack the same way single-url --save does; thin --save refuses
    |                 playlist expand keeps printed yt-dlp rows on 429 and skips warning lines so they do not become fake ids; expander passes --no-warnings like watch fetch
    |                 notes keep a written yt_<id>.md (and ytnotes keeps a written manual or auto en / en-orig / en-US / en-GB VTT) when yt-dlp exits 429 or a later error, or --print is empty; a leaked warning line or NA/None print is not the video id
    |                 watch, youtu.be, shorts, embed, live, /e/, and youtube-nocookie embed urls all resolve the same video id for that keep
    |                 a copied #t= timestamp still finds yt_<id>.en.vtt
    |                 a watch?v=&list= copy still finds yt_<video>.en.vtt when -J dumps playlist JSON
    |            or teach URL [--section N] (one chapter: claim numbers, named mechanisms, one check; free unless --save)
    |                 printed yt-dlp metadata is a hit even on 429; a leaked WARNING/ERROR/INFO line before the -J dump is skipped so the json still parses
    |                 a written VTT or leftover same-id clean.txt is used when the caption URL fetch fails, `-J` stdout is empty, or `-J` dumps a playlist; leftover [mm:ss] stamps become cues; another video leftover is not invent-keep
    |                 a taught section that is not last prints next: recap TEXT or skip
    |                 last section: rich ephemeral apply, failing check, and score 0, then next: atris youtube watch tick; save pack keep stays; no recap next
    |                 next --section refuses until recap/skip
    |                 owed prints unpaid check; successful unlock prints next section command
    |                 bare teach resumes owed, or prints a start command if nothing is owed
    |
   persist a rich lesson? --> learn log '{"type":"pattern","key":"...","insight":"..."}'
                           --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
                           --> thin: jsonl only
 
   write one Apply (claimable) before process
    |
   store knowledge? --> process URL (5 credits)
                    --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
                    --> thin: check: fill this; --json stays quiet
 
watch add --> next: atris youtube watch tick
watch tick --> briefs new videos
           --> if briefed: first rich brief mints pack-named apply + failing measure.py (score 0), then next: experiments keep
           -->            all thin: check: fill this, then next: atris youtube teach <first-briefed-url>
           --> 0 briefed, no channels: next: atris youtube watch add <channel-url-or-@handle>
           --> 0 briefed, channels exist: next: atris youtube search " "
 
digest --> files brief + claimable journal
       --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
       --> thin: check: fill this, then next: atris youtube watch tick
 
--paid QUERY only if the user asked to buy permalinks
    |
   rows --> rich: one pack-named apply + failing measure.py (score 0), then next: experiments keep
        --> thin: check: fill this, then next: atris youtube teach <first-url>
        --> --json stays quiet and writes no pack
login: atris login --agent from a stored login
never paste tokens, never /auth/cli

1. Get watch permalinks: atris youtube search QUERY (free). A rich hit mints atris/experiments/search-<query>/, writes one pack-named Apply, and prints score: 0 only when that Apply starts failing. A thin hit prints check: fill this, then one next teach command. --json stays quiet and writes no pack.
2. If 429: use any rows already printed. A leaked warning line or a youtu.be/NA / youtu.be/None row is not printed. If none, wait/retry is already in the CLI. If it prints cached rows, use those. Cached rows mint or print the same rich or thin gate as a live hit. If it prints youtube rate-limited local search. do not use --paid as a fallback; retry later., STOP. Do not run --paid.
3. --paid only when the user explicitly asked to buy permalinks. The CLI hard-refuses --paid when the free cache still has a fresh same-query hit.
4. atris youtube notes URL after a URL is picked (free). Notes is ephemeral unless --save. Rich ephemeral prints one apply next-step and one failing check (score: 0), then one next: atris youtube teach <same-url>, and writes no files. Thin ephemeral prints check: fill this instead of inventing a check. A playlist or multi-url batch does the same for the first successful item only. A playlist expand that prints video rows keeps them even when yt-dlp exits 429. A notes run that already wrote yt_<id>.md keeps that lesson even when the runner exits 429 or a later error, so the learner gate and rich --save mint still run. Watch, youtu.be, shorts, embed, live, /e/, and youtube-nocookie embed urls all resolve the same video id, so empty-JSON teach/process and notes keep still find that file. A copied watch?v=&list= URL still finds yt_<video>.en.vtt when -J dumps playlist JSON. A copied #t= timestamp still finds the same yt_<id> file. The bundled ytnotes script does the same for a written manual or auto en, en-orig, en-US, or en-GB VTT plus printed metadata, and skips a leaked WARNING/ERROR print line or a NA/None print when choosing the video id. --json stays quiet on the check and the teach next-step. Rich --save files the brief, mints atris/experiments/notes-<id>/, writes one Apply, and prints score: 0 only when that Apply starts failing. A rich multi-url --save batch proves that failing baseline for the first saved pack only; thin --save (no number-with-units and no named mechanism) refuses with no brief and exit 2. Do not auto --paid.
5. Write one Apply (change + receipt) before atris youtube process. Process still requires a filled Apply (so you --save a rich brief, fill Apply, then process). A rich analysis then mints atris/experiments/process-<id>/, writes one pack-named Apply, and prints score: 0 only when that Apply starts failing. Thin analysis prints check: fill this. --json stays quiet. 401, 402, or 502 print Credits when present and say credits refunded only when the server marks a refund. A local-transcript 502 that then retries cloud prints those same credit lines from the first payload before the retry. A 401 that remints and retries prints those same credit lines from the first payload before the retry.
6. Never paste tokens. Never /auth/cli. Mint with atris login --agent from a stored login.

If the user says "find videos", "search youtube", or "get youtube links" → search. If they say "learn from", "notes on", "alpha", or "rabbit hole" → notes. If they say "process", "store", "add to knowledge" → process. "Buy permalinks" or "paid search" is the only ask that unlocks --paid.

Never summarize a video from model memory; that is fabrication.

Bootstrap

Search and notes need no login. Paid search and process need a stored login, then atris login --agent. Never print credentials. Never /auth/cli.

#!/bin/bash
set -e
 
if ! command -v atris &> /dev/null; then
  echo "Installing atris CLI..."
  npm install -g atris
fi
 
echo "Ready. Feature map: free search, 429 printed-rows or cache-or-stop, notes, then process."

Search videos (free)

atris youtube search "MCP agents 2026"
atris youtube search "MCP agents" --limit 10
atris youtube search "MCP agents" --json

Uses ytsearch on PATH when present, else bundled scripts/det/ytsearch, else yt-dlp --flat-playlist --print with ytsearchN:. No credits. No /agent/process_youtube call. A rich hit prints one inferred check plus score: 0. A thin hit prints check: fill this. Then one next: atris youtube teach <first-url>. --json stays quiet.

On 429, printed rows are a hit (no retry). A leaked WARNING/ERROR/INFO print line or a youtu.be/NA / youtu.be/None row is not a hit. If stdout is empty the CLI retries once, then serves ~/.atris/youtube-search-cache.json if the same query is younger than one hour. A cache reprint prints the same rich or thin check as a live hit. If it prints the rate-limit sentence, stop. Do not run --paid.

Paid search (5 credits, opt-in buy only)

Only when the user explicitly asked to buy permalinks. A 429 or a missing cache is not that ask.

atris youtube search --paid "MCP agents 2026"
atris youtube search --paid "MCP agents" --limit 10