name: youtube-fetcher description: >- Turn a YouTube video into a structured, Obsidian-ready archival Markdown note containing its transcript, creator metadata, description, chapters, language, and capture provenance. Use when a user shares a YouTube URL or video ID and wants transcripts, captions, subtitles, notes, a knowledge-base record, summarization, analysis of what was said, or YouTube content saved to Markdown. When a user pastes only a YouTube link, fetch the note and report where it was saved.

YouTube Fetcher

Turn one YouTube link into one queryable Markdown knowledge note. The bundled script uses youtube-transcript-api for captions, optionally uses yt-dlp for richer metadata, and needs no API key.

Workflow

1. Resolve scripts/fetch_transcript.py relative to this SKILL.md. Do not assume a particular Codex, Claude, Skillshare, or home-directory install path.
2. If the request is only a YouTube link, run the script with its defaults.
3. Use --stdout when the user wants the transcript in the conversation rather than a saved note.
4. Use --output-dir when the user names an Obsidian vault or notes directory. A specific --output file takes precedence.
5. Report the saved path and any language-fallback warning. Read the result only when the user also wants a summary, analysis, or follow-up work.

Typical invocation, where SKILL_DIR is the directory containing this file:

python3 "$SKILL_DIR/scripts/fetch_transcript.py" "https://youtu.be/VIDEO_ID"

Safe Agent Behavior

• Run without --force first. Exit code 3 means an existing note was found and left unchanged; report that outcome and ask before overwriting.
• Never install Python packages, Homebrew packages, or yt-dlp automatically. If exit code 2 reports a missing required dependency, show the user the suggested command and ask for permission before changing their system.
• Do not claim the requested language was used when the script reports a fallback. The saved note records the actual selected caption language.
• Do not silently change the output directory. The precedence is: --output, then --output-dir, then YOUTUBE_FETCHER_DIR, then ~/yt_transcripts/.

Useful Options

# Put notes in an Obsidian vault or another directory
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --output-dir ~/Notes/Vault

# Save to one exact file
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --output ~/Notes/video.md

# Print Markdown instead of saving it
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --stdout

# Request captions in a language, with truthful English fallback
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --lang es

# Include timestamps or export raw JSON/SRT
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --timestamps
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --format json
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --format srt

# Inspect available caption languages or dependencies
python3 "$SKILL_DIR/scripts/fetch_transcript.py" URL --list
python3 "$SKILL_DIR/scripts/fetch_transcript.py" --check-deps

Other useful flags are --source, --no-description, and --force.

Capabilities and Boundaries

• Network: contacts YouTube caption endpoints and the YouTube oEmbed API. When available, yt-dlp contacts YouTube for descriptions, chapters, upload dates, and duration.
• Filesystem: reads only existing Markdown notes in the resolved output directory for duplicate detection and writes the requested Markdown, JSON, or SRT result there.
• Subprocess: invokes the locally installed yt-dlp executable for metadata.
• Dependencies: requires youtube-transcript-api and requests; yt-dlp is optional. The script reports missing dependencies but does not install them.
• Limits: requires captions that YouTube makes accessible. It does not download video, run Whisper, identify speakers, or translate captions.

Exit Codes

YouTube Fetcher to Markdown

YouTube video in, structured archival Markdown note out. Capture the transcript, creator metadata, description, chapters, actual caption language, and provenance in one Obsidian-ready file—without an API key.

npx skills add JimmySadek/youtube-fetcher-to-markdown

What you get

Paste a YouTube link and receive a file such as:

~/yt_transcripts/2026-03-04_obsidian-the-king-of-learning-tools_[hSTy_BInQs8].md

---
title: "Obsidian: The King of Learning Tools (FULL GUIDE + SETUP)"
channel: "Odysseas"
url: "https://www.youtube.com/watch?v=hSTy_BInQs8"
video_id: "hSTy_BInQs8"
fetched: "2026-03-04"
source_project: "my-project"
language: "en"
caption_type: "manual"
duration: "36m 26s"
upload_date: "2024-04-24"
tags:
  - yt-transcript
---

# Obsidian: The King of Learning Tools (FULL GUIDE + SETUP)

## Video Details
| Field    | Value |
|----------|-------|
| URL      | https://www.youtube.com/watch?v=hSTy_BInQs8 |
| Channel  | Odysseas |
| Duration | 36m 26s |
| Uploaded | 2024-04-24 |
| Fetched  | 2026-03-04 |
| Source   | my-project |
| Language | en (manual) |

## Video Description
The creator's description, links, and chapter markers...

## Transcript
The complete caption text...

The YAML frontmatter makes a collection queryable through tools such as Dataview, while the Markdown remains portable to Logseq, other knowledge bases, and plain text workflows.

Why this exists

Most transcript extractors stop at raw caption text. An archival knowledge note also needs the source URL, creator, capture date, actual language, description, chapters, and a predictable filename. YouTube Fetcher keeps that complete record in one local file.

Features

• Manual and auto-generated captions with optional timestamps
• Truthful language fallback: the note records the selected caption language
• Title, channel, duration, upload date, description, and chapters when available
• Safe YAML frontmatter and Markdown tables for dynamic metadata
• Duplicate detection that preserves existing notes unless overwrite is approved
• Obsidian-vault and custom-directory output
• Raw JSON and SRT export
• No API keys and no hosted service

Installation

Install the skill

npx skills add JimmySadek/youtube-fetcher-to-markdown

Or clone the canonical repository:

git clone https://github.com/JimmySadek/youtube-fetcher-to-markdown.git

Install runtime dependencies

Python 3.8 or newer is supported.

python3 -m pip install -r requirements.txt

yt-dlp is optional but recommended for descriptions, chapters, duration, and upload dates:

brew install yt-dlp              # macOS
# or: python3 -m pip install yt-dlp

Check dependencies without fetching a video:

python3 scripts/fetch_transcript.py --check-deps

The script reports missing packages but never installs them automatically.

Usage

python3 scripts/fetch_transcript.py "https://youtu.be/VIDEO_ID"

An agent using the skill resolves scripts/fetch_transcript.py relative to its installed SKILL.md; it does not depend on one fixed home-directory path.

Output location

The first configured option wins:

1. --output for one exact file
2. --output-dir for this run
3. YOUTUBE_FETCHER_DIR for a persistent directory
4. ~/yt_transcripts/ by default

# Save this note to an Obsidian vault
python3 scripts/fetch_transcript.py URL --output-dir ~/Notes/MyVault

# Set a persistent default
export YOUTUBE_FETCHER_DIR=~/Notes/MyVault
python3 scripts/fetch_transcript.py URL

# Save to one exact file
python3 scripts/fetch_transcript.py URL --output ~/Notes/video.md

Duplicate detection uses the resolved output directory. In a non-interactive session, an existing note exits with code 3 and remains untouched. Run again with --force only after deciding to overwrite.

Options

Supported YouTube inputs

• Standard watch URLs, regardless of query-parameter order
• youtu.be short links
• /embed/, /shorts/, /live/, and legacy /v/ links
• Mobile and YouTube Music watch URLs
• Privacy-enhanced youtube-nocookie.com/embed/ links
• A raw 11-character video ID

Lookalike hosts such as youtube.com.example.org are rejected.

Compatibility

The repository follows the portable SKILL.md format. The same install command works with Codex, Claude Code, Cursor, Windsurf, Gemini CLI, and other compatible agents. Manual users can run the Python script directly.

Capabilities and limitations

• Network: contacts YouTube captions and oEmbed; optionally invokes yt-dlp for richer metadata.
• Filesystem: reads Markdown frontmatter in the selected directory to detect duplicates and writes only the requested Markdown, JSON, or SRT output.
• Subprocess: uses the locally installed yt-dlp executable when available.
• Videos must expose captions. Private, restricted, or caption-disabled videos may fail.
• It does not download video, run Whisper, identify speakers, or translate text.

License

MIT