| name | youtube-notes |
| description | Take structured notes on any YouTube video. Fetches captions via yt-dlp, extracts key points with clickable timestamps, identifies concepts, action items, and resources mentioned — saved as a markdown note. |
| version | 1.0.0 |
| metadata | {"openclaw":{"emoji":"📝","requires":{"bins":["yt-dlp","jq"]},"install":[{"kind":"brew","formula":"yt-dlp","bins":["yt-dlp"]},{"kind":"brew","formula":"jq","bins":["jq"]}],"envVars":[{"name":"YOUTUBE_NOTES_DIR","required":false,"description":"Directory where notes are saved. Defaults to ~/youtube-notes."},{"name":"YOUTUBE_NOTES_MODE","required":false,"description":"Note style: 'lecture' (concepts + timestamps), 'tutorial' (steps + commands), 'talk' (arguments + quotes). Defaults to auto-detect."}]}} |
youtube-notes
Take structured notes on any YouTube video. Given a URL, it downloads captions, extracts key points linked to timestamps, and saves a markdown note you can navigate like a table of contents.
Trigger
User sends a YouTube URL with a note-taking intent. Examples:
notes on https://youtube.com/watch?v=...youtube-notes https://youtu.be/...take notes on this video: https://...summarize this youtube video: https://...what does this video cover? https://...
Capture the URL from the message. Validate it is a YouTube URL (youtube.com/watch, youtu.be/, youtube.com/shorts/, or youtube.com/live/).
Execution Steps
Step 1 — Fetch Video Metadata
mkdir -p /tmp/youtube-notes
yt-dlp --dump-json --no-download "<URL>" > /tmp/youtube-notes/meta.json
Extract fields needed for the note:
jq -r '{
id: .id,
title: .title,
channel: .uploader,
duration: .duration,
upload_date: .upload_date,
description: (.description | .[0:500]),
chapters: .chapters,
tags: .tags[0:10],
view_count: .view_count
}' /tmp/youtube-notes/meta.json
Store id — it is needed to build clickable timestamp URLs in the format:
https://www.youtube.com/watch?v=<id>&t=<seconds>
Step 2 — Download Captions
Prefer manual captions over auto-generated; prefer English.
yt-dlp \
--skip-download \
--write-sub \
--write-auto-sub \
--sub-lang "en,en-orig,en-US" \
--sub-format "vtt" \
--output "/tmp/youtube-notes/%(id)s.%(ext)s" \
"<URL>"
Locate the downloaded .vtt file:
VTT_FILE=$(ls /tmp/youtube-notes/*.vtt 2>/dev/null | head -1)
If no .vtt file was produced, captions are unavailable. Inform the user:
"This video has no available captions. I'll generate notes from the title, description, and chapter markers only."
Proceed to Step 4 using only metadata.
Step 3 — Parse Captions into Timestamped Segments
Convert the VTT file into a clean timestamped transcript. Each line: [HH:MM:SS] text.
python3 - <<'EOF'
import re, sys
vtt_path = "/tmp/youtube-notes/transcript.txt"
with open(sys.argv[1]) as f:
content = f.read()
blocks = re.split(r'\n\n+', content)
seen = set()
lines = []
for block in blocks:
rows = block.strip().splitlines()
ts_line = next((r for r in rows if '-->' in r), None)
if not ts_line:
continue
start = ts_line.split('-->')[0].strip()
# Convert HH:MM:SS.mmm → HH:MM:SS
start = re.sub(r'\.\d+$', '', start)
text_rows = [r for r in rows if '-->' not in r and not r.strip().isdigit() and r.strip()]
text = ' '.join(text_rows).strip()
if text and text not in seen:
seen.add(text)
lines.append(f"[{start}] {text}")
with open(vtt_path, 'w') as f:
f.write('\n'.join(lines))
print(f"Wrote {len(lines)} lines to {vtt_path}")
EOF
python3 /tmp/youtube-notes/parse_vtt.py "$VTT_FILE"
The result at /tmp/youtube-notes/transcript.txt is the input for summarization.
Step 4 — Detect Note Mode
Use YOUTUBE_NOTES_MODE if set. Otherwise auto-detect from metadata:
| Signal | Mode |
|---|
| Title contains "how to", "tutorial", "step by step", "build", "install", "setup" | tutorial |
| Title contains "lecture", "course", "explained", "introduction to", "deep dive" | lecture |
| Channel is a conference or event (TED, GOTO, Strange Loop, etc.) | talk |
| Duration > 45 min and has chapters | lecture |
| Default | talk |
Each mode shapes the output sections (see Step 5).
Step 5 — Generate Notes
Apply the prompt template from prompts/extract.md with the transcript, metadata, video ID, and detected mode.
Produce the following sections based on mode:
All modes include:
- Overview (3–4 sentences): What the video is about, who it's for, and the core argument or outcome.
- Key Points with Timestamps: Each point is a concise insight or claim, linked to where it appears in the video.
- Resources Mentioned: URLs, books, tools, papers, or people referenced in the video.
Mode: lecture
Additional sections:
- Concept Index: Each major concept introduced, with a one-line definition and its timestamp.
- Prerequisites: What prior knowledge is assumed.
Mode: tutorial
Additional sections:
- Steps Summary: Numbered list of the main steps demonstrated.
- Commands & Code: Any shell commands, code snippets, or config values shown. Include the timestamp where each appeared.
- Prerequisites: Tools or setup required before following along.
Mode: talk
Additional sections:
- Central Argument: The speaker's main thesis in 1–2 sentences.
- Notable Quotes: 2–4 verbatim quotes with timestamps.
- Counterarguments Addressed: Points the speaker anticipated or rebutted.
Step 6 — Build Timestamp Links
For every timestamp [HH:MM:SS] in the output, convert to a YouTube deep-link:
HH:MM:SS → total seconds
link = https://www.youtube.com/watch?v=<VIDEO_ID>&t=<SECONDS>
Format in markdown as: [[HH:MM:SS]](link) so each timestamp is clickable.
Python helper:
def ts_to_seconds(ts):
parts = ts.split(':')
if len(parts) == 3:
h, m, s = parts
return int(h)*3600 + int(m)*60 + int(s)
elif len(parts) == 2:
m, s = parts
return int(m)*60 + int(s)
return 0
Step 7 — Write the Note
Resolve output path:
NOTES_DIR="${YOUTUBE_NOTES_DIR:-$HOME/youtube-notes}"
mkdir -p "$NOTES_DIR"
DATE=$(date +%Y-%m-%d)
TITLE_SLUG=$(echo "<TITLE>" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-\|-$//g' | cut -c1-60)
OUTPUT_FILE="$NOTES_DIR/${DATE}-${TITLE_SLUG}.md"
Write the note using the template below:
# <Title>
> **URL**: [Watch on YouTube](<URL>)
> **Channel**: <channel>
> **Duration**: <HH:MM:SS>
> **Published**: <YYYY-MM-DD>
> **Mode**: <lecture | tutorial | talk>
> **Notes taken**: <today's date>
---
## Overview
<3–4 sentence overview>
---
## Key Points
- [[00:01:23]](https://youtube.com/watch?v=ID&t=83) <key point>
- [[00:05:47]](https://youtube.com/watch?v=ID&t=347) <key point>
- [[00:12:10]](https://youtube.com/watch?v=ID&t=730) <key point>
...
---
## <Mode-specific section(s)>
...
---
## Resources Mentioned
- [<name>](<url or search term>) — <brief context>
...
---
## Chapters
| Chapter | Start | Link |
|---------|-------|------|
| <Chapter title> | 00:00:00 | [[▶]](https://youtube.com/watch?v=ID&t=0) |
...
*(section omitted if video has no chapters)*
---
*Generated by youtube-notes skill · [youtube-notes](https://github.com/openclaw/skills)*
Step 8 — Respond to the User
Send a confirmation message:
📝 Notes saved!
""
<Channel> · <duration> · Mode: <mode>
Overview:
key points with timestamps · Saved to: <OUTPUT_FILE>
Want me to read out the key points, jump to a specific section, or search the notes?
Error Handling
| Situation | Action |
|---|
| Not a YouTube URL | Reply: "This skill only supports YouTube URLs. For other video sources, try podcast-recap." |
yt-dlp not installed | Reply: "Install yt-dlp first: brew install yt-dlp" |
| No captions available | Use title + description + chapters only; flag in note with ⚠️ |
| Video is private or age-restricted | Report the yt-dlp error; suggest the user check access |
| Video is a live stream (ongoing) | Reply: "Live streams cannot be noted until after broadcast ends." |
| Transcript is under 100 words | Warn: "Transcript is very short — notes may be incomplete." |
| Output directory not writable | Fall back to ~/Downloads/youtube-notes/; inform user |
Cleanup
After writing the note, remove temp files:
rm -rf /tmp/youtube-notes/
