youtube

<Purpose> Extract transcript and metadata from a YouTube video, then synthesize it into a vault-formatted post note. Uses youtube-transcript-api for transcript and yt-dlp for rich metadata (with oEmbed fallback). </Purpose>

<Use_When>

• User shares a YouTube URL and wants notes taken
• User says "take notes from this video"
• User pastes a YouTube link with /youtube
• User wants to add a video's insights to the vault </Use_When>

<Do_Not_Use_When>

• User wants to watch or download the video itself
• User has a local video file (not YouTube)
• Video has no transcript/captions at all
• User wants to process an existing vault note (use /process) </Do_Not_Use_When>

<Execution_Policy>

• Extract first, synthesize second, integrate third
• Always check vault for existing notes on the same video before creating
• Create note as type: post with processing_status: inbox
• The note is a starting point — user can /process it later for deeper engagement </Execution_Policy>

<Steps>

Stage 1: EXTRACT

Parse the YouTube URL/ID from $ARGUMENTS. If no URL provided, ask the user.

Run the extraction script. Redirect stdout to a temp file (stderr has progress messages that break piping):

SKILL_DIR="${CLAUDE_SKILL_DIR}"
YT_OUTPUT="$SKILL_DIR/_output.json"
uv run "$SKILL_DIR/scripts/fetch_youtube.py" "VIDEO_URL" --lang en > "$YT_OUTPUT"

Then read $YT_OUTPUT with the Read tool to get the JSON. Clean up the file after use.

The JSON contains:

• title, channel, duration, upload_date, description, chapters
• transcript.full_text, transcript.segments, transcript.language
• transcript.error (null if success)

If transcript.error is not null: inform the user and stop. No note without content.

If transcript is very long (>50,000 chars): warn the user this is a long video. Chunk the transcript for the agent if needed — send first 40,000 chars with a note about total length. For very long videos (>2hrs), consider suggesting the user watch key sections instead.

Stage 2: SYNTHESIZE

Read the agent definition:

Read("${CLAUDE_SKILL_DIR}/agents/video-noter.md")

Search the vault for existing notes related to the video's topics using the MCP tool:

search_notes(query="KEYWORD", limit=20)

Or fall back to Grep if MCP is unavailable:

Grep(pattern="KEYWORD", path="notes/", glob="*.md", head_limit=20)

Launch the video-noter agent:

Agent(
  subagent_type="general-purpose",
  model="sonnet",
  run_in_background=false,
  prompt="You are Video Noter. Follow these instructions exactly:

  [INSERT FULL CONTENT OF agents/video-noter.md HERE]

  VIDEO METADATA:
  - Title: [title]
  - Channel: [channel]
  - Duration: [duration]
  - Upload date: [upload_date]
  - Chapters: [chapters if any]
  - Description: [first 500 chars of description]

  EXISTING VAULT NOTES ON RELATED TOPICS:
  [List any matching notes found in grep]

  TRANSCRIPT:
  [full_text or chunked text]

  Produce the note body following the Output Format. Do NOT include frontmatter —
  only the body starting from the # title line."
)

Stage 3: INTEGRATE

1. Generate timestamp ID:

date +%Y%m%d%H%M%S

2. Format the upload_date for frontmatter (YYYYMMDD → YYYY-MM-DD)

3. Check for duplicate notes:

grep -rl "VIDEO_TITLE" notes/ --include="*.md" | head -5

4. Create the note file with frontmatter + agent output:

---
id: YYYYMMDDHHMMSS
type: post
processing_status: inbox
author: Channel Name
link: "https://www.youtube.com/watch?v=VIDEO_ID"
created_date: YYYY-MM-DD
updated_date: YYYY-MM-DD
---

[AGENT OUTPUT HERE — starts with # title and 🏷️Tags line]

Place the note in notes/ under the most appropriate topic subfolder:

• ML/AI content → notes/ml/
• Startup/business → notes/startup/
• Finance → notes/finance/
• Design → notes/design/
• Psychology → notes/psychology/
• General/unclear → notes/

5. Report to user:
   • Note path and title
   • Number of concepts suggested for extraction
   • Any related vault notes found
   • Remind: "Run /process on this note when you're ready to deepen it"

</Steps>

<Tool_Usage>

• Bash: Run fetch_youtube.py script (via uv run), generate timestamps, search vault
• Read: Read agent definition, read existing vault notes for context
• Write: Create the post note in vault
• Agent: Delegate synthesis to video-noter agent (sonnet)
• Grep/Glob: Search vault for duplicates and related notes
• TodoWrite: Track progress through stages </Tool_Usage>

<Examples> <Good> User: /youtube https://www.youtube.com/watch?v=abc123 1. Extract → transcript (12 min video, 3400 words) + metadata (title, channel, chapters) 2. Search vault → found 2 related notes on the topic 3. Agent synthesizes → 6 themed sections, 4 questions, 3 concept suggestions 4. Create note → notes/ml/(Post) Video Title.md 5. Report: "Created note with 6 sections. Found connections to [[Existing Note 1]] and [[Existing Note 2]]. 3 concepts could become Term notes. Run /process when ready." </Good> <Bad> User: /youtube https://www.youtube.com/watch?v=abc123 - Creates note that is just a chronological transcript summary - Misses connections to existing vault notes - Doesn't check for duplicates - Places note in wrong folder </Bad> </Examples>

<Escalation_And_Stop_Conditions>

• No transcript available: Inform user, suggest manual notes while watching
• Transcript in wrong language: Try other available languages, report what's available
• yt-dlp fails for metadata: Fall back to oEmbed (basic title/channel only)
• Video extremely long (>3hrs): Warn user, offer to process first N minutes only
• Duplicate note exists: Show existing note, ask if user wants to update or create new </Escalation_And_Stop_Conditions>

$ARGUMENTS