yt2md

name	yt2md
description	Fetch a YouTube video's transcript and act on it with a free-form prompt (summarize, extract quotes, draft a post, answer questions). Use when the user runs /yt2md, or says "summarize this video", "transcript of", "youtube to notes", "what does this video say about". Triggers on "yt2md", "youtube transcript", "summarize video", "video to post", "transcript of".
allowed-tools	Bash, Read, Write

ABOUTME: Claude Code skill wrapping the yt2md CLI into a /yt2md flow

ABOUTME: Fetches a transcript, then acts on it per the user's prompt; summary is the default

yt2md

Turn a YouTube video into whatever the user asked for. The invocation is:

/yt2md <video-url-or-id> [free-form prompt]

<video> is a YouTube URL (watch, youtu.be, shorts, embed, live) or a bare 11-character ID. The rest of the line is the user's intent: summarize, pull key points, draft a LinkedIn post, extract quotes, answer a question, translate, outline, and so on. If no prompt is given, produce a structured summary.

Workflow

1. Parse the arguments

Split the input into the video reference (first token that looks like a URL or an 11-char ID) and the prompt (everything else). If you cannot find a video reference, ask the user for the URL or ID instead of guessing.

2. Choose the fetch mode

Default to plain flowing paragraphs. Use --timestamps only when the prompt implies positions in the video, e.g. it mentions "timestamp", "where does he/she", "at what point", "jump to", "quote ... at", "chapters", or "when did". In that case the model can cite [MM:SS] markers from the transcript.

3. Fetch the transcript

Write the transcript to a temp file (not stdout) so large transcripts do not flood the conversation, then Read it. Prefer a globally installed yt2md; fall back to running it from the public repo via uvx (no install needed):

# Resolve a runner once.
if command -v yt2md >/dev/null 2>&1; then
  YT2MD=(yt2md)
else
  YT2MD=(uvx --from git+https://github.com/mauromedda/yt2md yt2md)
fi

# Plain paragraphs (default):
"${YT2MD[@]}" "<video>" -o /tmp/yt2md_transcript.md
# ...or, when the prompt needs positions:
"${YT2MD[@]}" "<video>" --timestamps -o /tmp/yt2md_transcript.md

Add -l <codes> (e.g. -l it,en) if the user asks for a specific language or the video is clearly non-English. Use the scratchpad temp dir if one is defined in your environment; otherwise /tmp is fine.

Then Read the file. The header carries the title, source URL, and language, keep those handy for attribution.

4. Handle failures cleanly

yt2md exits non-zero with a single yt2md: error: ... line on stderr. Do not retry blindly; read the message and relay it plainly:

Symptom	Meaning	What to tell the user
Subtitles are disabled for this video	Owner turned off captions	No transcript available; suggest another video.
Could not retrieve a transcript ... no ... language	No track in requested language	Offer to retry with -l <other> (e.g. the video's original language).
Video unavailable / is no longer available	Private/removed/region-locked	Nothing to fetch; confirm the ID/URL.
could not extract a YouTube video ID	Bad reference	Ask for a valid URL or 11-char ID.

Do not fabricate a transcript or answer from the title alone. No transcript, no content task.

5. Act on the prompt

With the transcript in hand, do exactly what the prompt asked, grounded only in the transcript. Attribute to the video (title + URL from the header). Never invent facts the transcript does not contain; if the prompt asks for something the video does not cover, say so.

Default (no prompt) → structured summary:

## <video title>
Source: <url> · <language>

**TL;DR:** one or two sentences.

**Key points:**
- ...
- ...

**Notable quote:** "..." (only if a genuinely quotable line exists)

With a prompt, the prompt wins: a request to "draft a post", "list the action items", "extract every statistic", or "answer: does he mention X?" overrides the default summary. Match the output format to the ask (a post reads like a post, an outline like an outline). Keep the model's own commentary out of it unless the user asked for analysis.

Notes

• The --claude flag of the CLI reflows the transcript via a separate claude -p subprocess. Do not use it from this skill: you already have the model in the loop, so a plain fetch plus your own processing is cheaper and avoids a nested Claude call.
• yt2md uses YouTube's unofficial caption endpoints. This is a personal-use tool; do not use it to bulk-harvest or redistribute third-party content. See the repo's "Legal & responsible use" section.
• First uvx run builds the package (a few seconds); subsequent runs are cached.