name	yt-summary
description	Summarize a YouTube video into a shareable, chronological markdown brief with clickable timestamped links. Use when the user gives a YouTube URL and asks for a summary, notes, a brief, a digest, a TL;DR, or says things like "what happened in this video", "summarize this podcast", or "give me the highlights with timestamps".

yt-summary

Produce a markdown document that lets someone who hasn't watched the video understand what happened and click straight to any moment. The output is meant to be shared as-is (pasted into Slack, sent in an email, dropped into a doc) — not consumed conversationally.

Pipeline

Fetch the transcript. Run the helper script and read its stdout. It prints metadata, YouTube's own chapter list (if present), and a timestamp-anchored transcript where every line begins with [HH:MM:SS] or [MM:SS].
```
python3 /Users/mdp/Sync/src/mdp/yt-summary-skill/yt-transcript.py "<YOUTUBE_URL>"
```
If the user gives only a video ID, pass https://www.youtube.com/watch?v=<ID>.
Read the output in full before writing anything. Note whether captions are manual or auto-generated — auto-generated captions mangle proper nouns and have no punctuation, so lean more on quoting context and less on exact phrasing.
Write the summary file. Save as <video-id>.md in the current working directory unless the user specifies a path. Use the template below.
Tell the user the output path. One sentence. No trailing summary of what you did.

Output template

# <video title>

**Channel:** <channel> · **Duration:** <MM:SS or H:MM:SS> · **Watch:** [youtube.com/...](https://www.youtube.com/watch?v=<ID>)

> <2–4 sentence TL;DR: the core thesis, the headline claims, who the guests are if it's an interview. No timestamps in the TL;DR.>

---

## <First section title> [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<START_SECONDS>s)

<2–3 short paragraphs of prose summarizing this section. Carry the narrative: what question got asked, what argument got made, what got decided, how it connects to what came before. Name people when they're speaking. No timestamps in the prose — the bullets carry those.>

- [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<SEC>s) — <one-line bullet. A specific claim, example, or decision, not a vague topic label.>
- [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<SEC>s) — <for interviews/podcasts, attribute: "**Host:** asked about X; **Guest:** said Y". Use names when you can infer them from the transcript.>

## <Next section title> [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<START_SECONDS>s)

...

Prose vs. bullets: what goes where

Prose = the throughline. The reader should be able to read just the prose and understand the arc of the video. Capture the motivation ("they rebuilt the harness because..."), the turning points ("the big unlock was..."), and how sections connect. 2–3 short paragraphs per section — not a wall of text.
Bullets = the skimmable specifics. Individual claims, numbers, names, anecdotes, punchlines. Bullets are where someone drills in after the prose tells them this section is relevant.
No duplication. If something is in the prose, don't also bullet it verbatim. Prose paraphrases and connects; bullets pin a specific moment to a timestamp.
Short sections get short prose. A 2-minute intro section might only need one paragraph. Don't stretch.

Rules for the summary

Sections must be in chronological order. This is a time-ordered brief, not a thematic one. If the video has YouTube chapters, use them as section boundaries and titles — the creator already did the work. If not, infer 5–12 sections from topic shifts in the transcript.
Every bullet is a clickable timestamp link. Format: [MM:SS](https://www.youtube.com/watch?v=<ID>&t=<SECONDS>s). Use HH:MM:SS only for videos over an hour. <SECONDS> is the total seconds from the start — compute it from the transcript marker, do not invent it.
Ground every timestamp in a real transcript segment. Pick the [HH:MM:SS] marker that starts the segment the bullet is about. Never interpolate. If you're unsure where a topic begins, use the earlier of the candidate segments.
Bullet density scales with length. Aim for roughly one bullet per 1–3 minutes of content, more where the content is dense, fewer during intros/outros/tangents. A 10-minute video gets ~6 bullets; a 90-minute podcast gets ~40–60. Don't pad; don't skim.
Each bullet is a specific claim, not a topic label. Bad: "They discuss MCP." Good: "Argues MCP is best for narrow, tightly-permissioned agents; coding agents with compute runtimes are a different tool."
Speaker attribution for interviews/podcasts. YouTube manual captions often mark speaker changes with >>. Use those as hints. Infer names from the intro (hosts usually introduce themselves and the guests in the first few minutes). Bold speaker names: **Simon:**, **Sarah:**. If you can't tell who said what, drop attribution rather than guessing.
Skip sponsor reads, intros, and outros unless they contain substantive content. A one-line "intro / housekeeping" bullet is fine; don't burn five bullets on the cold open.
Preserve concrete details. Numbers, product names, company names, specific claims, direct quotes for punchy lines. These are what make the summary useful vs. generic.
No invented content. If the transcript doesn't support a claim, leave it out. Auto-generated captions in particular will have misspellings — fix obvious ones (common words, famous names) but don't confabulate technical terms you can't verify.
No meta-commentary. Don't write "The video starts with..." or "They then move on to...". Just state what was said.

Quick reference: second-offset math

MM:SS → M*60 + S
HH:MM:SS → H*3600 + M*60 + S
The &t=<N>s fragment seeks the YouTube player to second N on load.

yt-summary

Pipeline

Fetch the transcript. Run the helper script and read its stdout. It prints metadata, YouTube's own chapter list (if present), and a timestamp-anchored transcript where every line begins with [HH:MM:SS] or [MM:SS].

python3 /Users/mdp/Sync/src/mdp/yt-summary-skill/yt-transcript.py "<YOUTUBE_URL>"

If the user gives only a video ID, pass https://www.youtube.com/watch?v=<ID>.

Read the output in full before writing anything. Note whether captions are manual or auto-generated — auto-generated captions mangle proper nouns and have no punctuation, so lean more on quoting context and less on exact phrasing.

Write the summary file. Save as <video-id>.md in the current working directory unless the user specifies a path. Use the template below.

Tell the user the output path. One sentence. No trailing summary of what you did.

Output template

# <video title> **Channel:** <channel> · **Duration:** <MM:SS or H:MM:SS> · **Watch:** [youtube.com/...](https://www.youtube.com/watch?v=<ID>) > <2–4 sentence TL;DR: the core thesis, the headline claims, who the guests are if it's an interview. No timestamps in the TL;DR.> --- ## <First section title> [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<START_SECONDS>s) <2–3 short paragraphs of prose summarizing this section. Carry the narrative: what question got asked, what argument got made, what got decided, how it connects to what came before. Name people when they're speaking. No timestamps in the prose — the bullets carry those.> - [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<SEC>s) — <one-line bullet. A specific claim, example, or decision, not a vague topic label.> - [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<SEC>s) — <for interviews/podcasts, attribute: "**Host:** asked about X; **Guest:** said Y". Use names when you can infer them from the transcript.> ## <Next section title> [<MM:SS>](https://www.youtube.com/watch?v=<ID>&t=<START_SECONDS>s) ...

Prose vs. bullets: what goes where

Prose = the throughline. The reader should be able to read just the prose and understand the arc of the video. Capture the motivation ("they rebuilt the harness because..."), the turning points ("the big unlock was..."), and how sections connect. 2–3 short paragraphs per section — not a wall of text.

Bullets = the skimmable specifics. Individual claims, numbers, names, anecdotes, punchlines. Bullets are where someone drills in after the prose tells them this section is relevant.

No duplication. If something is in the prose, don't also bullet it verbatim. Prose paraphrases and connects; bullets pin a specific moment to a timestamp.

Short sections get short prose. A 2-minute intro section might only need one paragraph. Don't stretch.

Rules for the summary

Sections must be in chronological order. This is a time-ordered brief, not a thematic one. If the video has YouTube chapters, use them as section boundaries and titles — the creator already did the work. If not, infer 5–12 sections from topic shifts in the transcript.

Every bullet is a clickable timestamp link. Format: [MM:SS](https://www.youtube.com/watch?v=<ID>&t=<SECONDS>s). Use HH:MM:SS only for videos over an hour. <SECONDS> is the total seconds from the start — compute it from the transcript marker, do not invent it.

Ground every timestamp in a real transcript segment. Pick the [HH:MM:SS] marker that starts the segment the bullet is about. Never interpolate. If you're unsure where a topic begins, use the earlier of the candidate segments.

Bullet density scales with length. Aim for roughly one bullet per 1–3 minutes of content, more where the content is dense, fewer during intros/outros/tangents. A 10-minute video gets ~6 bullets; a 90-minute podcast gets ~40–60. Don't pad; don't skim.

Each bullet is a specific claim, not a topic label. Bad: "They discuss MCP." Good: "Argues MCP is best for narrow, tightly-permissioned agents; coding agents with compute runtimes are a different tool."

Speaker attribution for interviews/podcasts. YouTube manual captions often mark speaker changes with >>. Use those as hints. Infer names from the intro (hosts usually introduce themselves and the guests in the first few minutes). Bold speaker names: **Simon:**, **Sarah:**. If you can't tell who said what, drop attribution rather than guessing.

Skip sponsor reads, intros, and outros unless they contain substantive content. A one-line "intro / housekeeping" bullet is fine; don't burn five bullets on the cold open.

Preserve concrete details. Numbers, product names, company names, specific claims, direct quotes for punchy lines. These are what make the summary useful vs. generic.

No invented content. If the transcript doesn't support a claim, leave it out. Auto-generated captions in particular will have misspellings — fix obvious ones (common words, famous names) but don't confabulate technical terms you can't verify.

No meta-commentary. Don't write "The video starts with..." or "They then move on to...". Just state what was said.

Quick reference: second-offset math

MM:SS → M*60 + S

HH:MM:SS → H*3600 + M*60 + S

The &t=<N>s fragment seeks the YouTube player to second N on load.