video-notes-creator
Skill1 starsChanged 3 days agoMITView on GitHub
Turn one video into visual study notes (PDF). Uses the speaker's own slides as figures and draws a concept diagram only where no usable slide exists.
In this repositoryOne other file it gives its agents.
- my-skillSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
43 rules. About 0 are common, 36 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈36
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Do not fetch the video, run a script, or write a file until you know these two things.
- Distinctive: line 19
Keep work files (scan sheets, frames, transcript, virtual environment) in a temporary or scratch folder, not in the output path.
- Distinctive: line 22
If the request already gives one of them, use it.
- Very specific: line 23
If a file reader-profile.md is next to this SKILL.md, read it.
- Distinctive: line 27
Create the output folder if it does not exist.
- Distinctive: line 28
If the user does not answer, or tells you to continue, use the defaults.
- Distinctive: line 29
Do not guess a profile from the user's name, email, or other personal data.
- Distinctive: line 32
Write for the reader profile from "Before you start".
- Distinctive: line 35
If the goal is given, give the most depth to the parts that serve it.
- Distinctive: line 40
If you cannot read the transcript, stop and ask for it.
- Distinctive: line 41
If you cannot get frames from the video, say so.
- Distinctive: line 42
Do not download the video file.
- Distinctive: line 45
Follow the speaker. Keep the speaker's order of ideas.
- Distinctive: line 48
Prefer the speaker's visuals.
- Distinctive: line 49
Keep the examples. For each demo, record the input, the action, and the result.
- Distinctive: line 53
Do not invent. If the video does not support a fact, write "Not stated".
- Very specific: line 62
Do these steps in order. Do the full job in one session.
- Distinctive: line 67
If the transcript is too long to read in one step, read it in parts.
- Very specific: line 72
Look at the contact sheets one time.
- Very specific: line 76
Write each time as it is in inventory.txt (mm:ss, or h:mm:ss for a video longer than one hour).
- Very specific: line 78
Look at check.jpg one time to confirm the frames.
- Distinctive: line 84
Do the figure review (see "Figure review").
- Very specific: line 86
If slide_tools.py is not available, do the same steps by hand:
- Distinctive: line 90
If the video has no storyboard, or is not on YouTube, ask me before you download the video file.
- Distinctive: line 94
Use the script. Do not write new scan or grab code.
- Distinctive: line 95
Look at each image one time.
- Distinctive: line 98
If you can start a subagent, do steps 2 and 3 there.
- Distinctive: line 100
Do not paste the full notes in chat.
- Distinctive: line 105
No slide. The speaker explains the idea in words only: generate a card diagram from the concept.
- Distinctive: line 110
Use the frame where the slide is complete (all build steps are visible).
- Distinctive: line 113
Do not use frames of the speaker, the audience, or the stage.
- Distinctive: line 114
Put two related slides side by side when you must compare them (before and after, input and output).
- Distinctive: line 115
Do not use a slide that is only a title or a decoration.
- Distinctive: line 125
Use only content from the video.
- Distinctive: line 134
Do and do not: two cards, red and green.
- Distinctive: line 156
If the slide needs data that it does not show, add max one more sentence.
- Distinctive: line 163
If the speaker shows a recap slide, add it as Figure 2.
- Distinctive: line 175
Only where the video compares options.
- Distinctive: line 186
Start with one line: "Click a number in the text to jump here.
- Distinctive: line 194
If you cannot find a link that you are sure of, write "No link found".
- Distinctive: line 201
No filler, no idioms, no em dashes.
- Distinctive: line 208
If you cannot make files: write the notes as Markdown in chat.
- Distinctive: line 209
If the video is longer than 60 minutes, or your output limit is small, write sections 0 to 2 first.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Role
You are a principal technical writer. Turn one video into visual reference notes that the reader can study and reuse.
Before you start (mandatory)
Do not fetch the video, run a script, or write a file until you know these two things. You may read reader-profile.md (see below).
- Reader profile
- Role and field (for example: backend engineer, product manager, biology student).
- Level in the topic of the video: new, working knowledge, or expert.
- What the reader already knows, so that you do not explain it.
- Optional: the goal for this video, and sections to skip.
- Output path
- The folder for the notes. Make one subfolder per video, named from the video title (lowercase, hyphens). Put the Markdown, the PDF, and a
figuresfolder in it. - Keep work files (scan sheets, frames, transcript, virtual environment) in a temporary or scratch folder, not in the output path.
- The folder for the notes. Make one subfolder per video, named from the video title (lowercase, hyphens). Put the Markdown, the PDF, and a
How to get them:
- If the request already gives one of them, use it. Do not ask again.
- If a file
reader-profile.mdis next to this SKILL.md, read it. Show it in one line and ask the user to confirm or change it. The file can also give a default output path. Seereader-profile.example.mdfor the format. - Else ask the user. Ask both questions in one message. Use a question tool if one is available. Offer two choices for each question: the default and one realistic alternative. A question tool usually needs at least two options.
- Profile: default "Technical professional, new to this topic". Alternative, for example: "Software engineer, working knowledge of the topic".
- Path: default a
video-notesfolder in the current working folder. Alternative:~/Documents/video-notes.
- Create the output folder if it does not exist. A folder outside the current working folder can need the user's approval for access. Ask for it before you start the long steps.
- If the user does not answer, or tells you to continue, use the defaults. Write the profile and the path that you used in the Summary box.
- Do not guess a profile from the user's name, email, or other personal data.
Reader
Write for the reader profile from "Before you start".
- Explain each term that the reader does not know at first use. Do not explain what the reader already knows.
- Select examples, comparisons, and actions from the reader's field when the video supports them. Tag them [Inference] if the speaker does not make the link.
- If the goal is given, give the most depth to the parts that serve it.
Input
- Video link or transcript.
- The reader profile and the output path (see "Before you start").
- If you cannot read the transcript, stop and ask for it. Do not write notes from the title or from memory.
- If you cannot get frames from the video, say so. Then continue with generated diagrams only.
- Do not download the video file. Read the storyboard and single frames only (see "Workflow").
Core principles
- Follow the speaker. Keep the speaker's order of ideas.
- Find the core. Most videos have 3 to 7 main ideas. Give them the most depth.
- Show, then tell. Each main idea gets one or two visuals. The text explains only what the visual cannot show.
- Prefer the speaker's visuals. A slide from the video is better than a diagram that you draw.
- Keep the examples. For each demo, record the input, the action, and the result. If the speaker explains why the result happens (a failure, a fix, or a surprise), write that reason with its [mm:ss]. A result without its reason is incomplete. If the speaker gives no reason, write "Reason not stated". Do not add your own reason unless you tag it [Inference].
- Show evidence. Put [mm:ss] on each main claim (use [h:mm:ss] for a video longer than one hour). Tag each claim: [Speaker] (said), [Slide] (shown on a slide), [Demo] (shown live on screen), [Inference] (your conclusion). An analogy is [Speaker], not [Demo].
- Flag dated facts. Mark prices, model names, versions, and benchmarks "As of
<video date>". - Do not invent. If the video does not support a fact, write "Not stated".
- Cite resources. Each time a claim, example, figure, table row, rule, or action uses a resource from section 8, put its number after the name, for example "Tiktokenizer [3]". Each number links to its resource row.
Adapt to video type
- Tutorial: add exact commands, code, and setup steps.
- Lecture or talk: keep the argument chain from premise to conclusion.
- Interview or panel: group the content by question, and name who says what.
Workflow
Do these steps in order. Do the full job in one session. Do "Before you start" first.
Setup: slide_tools.py and build_pdf.py are in the scripts folder of this skill. Install requirements.txt from this skill folder in a virtual environment in a scratch or temporary folder. If ffmpeg is not installed, the imageio-ffmpeg package supplies it.
- Get the transcript with timestamps, and the title, channel, date, length, chapter list, and video description. Run:
python <skill folder>/scripts/slide_tools.py transcript <url> <work_dir>It writestranscript.txt(one line per minute) andmeta.json. The description often lists the links to the resources. If the transcript is too long to read in one step, read it in parts. After each part, save a digest to disk: time, claim, example, numbers, names. - Find the slides. Do not save the video. Run:
python <skill folder>/scripts/slide_tools.py scan <url> <scan_dir>The script reads the smallest video stream one time (about 0.2 to 0.8 MB per minute of video) and looks at one frame each 2 seconds. It keeps the last frame of each picture that stays on screen, so slide builds are complete and times are exact to 2 seconds. It drops camera views that keep coming back. It writes contact sheets of slide candidates andinventory.txt. If the stream cannot be read, it uses the storyboard (one picture each 10 seconds). A page that shows for less than 4 seconds is kept and marked "(brief page)" ininventory.txt. These are often paper title pages, posts, or articles. Check them for names, titles, and URLs. - Look at the contact sheets one time. Make a slide inventory: time, slide title, and the idea it supports.
inventory.txtalso lists the camera-view ranges, where a slide can show only on the stage screen. - Outline the main ideas in video order. For each idea, select the visual with the rules below.
- Get only the selected slides at full resolution. Use the end time of each candidate. Run:
python <skill folder>/scripts/slide_tools.py grab <url> <figures_dir> --match <scan_dir>/tiles <time> <time> ...Write each time as it is ininventory.txt(mm:ss, or h:mm:ss for a video longer than one hour). The script reads only the bytes near each frame (about 0.3 to 2 MB per frame, depending on the stream). It compares each frame with its scan tile and corrects the time if necessary. Use the matched time in the caption. - Look at
check.jpgone time to confirm the frames. Open a slide at full size only when you must read small text from it. - Correct the notes where a slide gives more exact data than the transcript (names, numbers, URLs). Auto-captions often misspell names. Check each speaker and product name against name captions, posts, and pages on screen, and the description. Mark a name that you cannot confirm "(spelling from captions)".
- Make the resource list (see "8. Resources"). Number it in video order. Then write the notes with the citations. Build the PDF:
python <skill folder>/scripts/build_pdf.py <notes.md> <notes.pdf>The script makes the[[n]](#ref-n)citations, the[text](url)links, and the "Cited in" section links clickable. - Do the figure review (see "Figure review"). Correct each figure that fails.
If slide_tools.py is not available, do the same steps by hand:
- Dense scan: get the URL of the smallest video stream from
yt-dlp -J <url>. Read it in chunks of 8 MB with HTTP Range requests (one long request is throttled) and pipe it intoffmpeg -i pipe:0 -vf fps=1/2. - Storyboard (fallback):
yt-dlp -J <url>lists formatssb0tosb3. Usesb0. Each fragment is one image with a grid of tiles. - One frame:
ffmpeg -ss <seconds> -i <stream url from yt-dlp> -frames:v 1 out.jpg. Put-ssbefore-i. If the video has no storyboard, or is not on YouTube, ask me before you download the video file.
Token rules
Images and long sessions cost the most tokens. Obey these rules.
- Use the script. Do not write new scan or grab code.
- Look at each image one time. Do not open an image again.
- Image budget for slides: the scan sheets (max 3), one
check.jpg, and max 5 slides at full size. - Let code do each check that code can do (same picture, image size, page count). Use your eyes only for meaning.
- If you can start a subagent, do steps 2 and 3 there. Get back only the slide inventory as text. Then the scan images do not stay in the main conversation.
- Preview the PDF pages on one low-resolution sheet. Zoom in on max 2 pages.
- Do not paste the full notes in chat.
Visual selection (use the first rule that applies)
- Clean slide. The video shows a full-frame slide for the idea: use the frame as the figure. Do not redraw it.
- Unusable slide. The slide shows only at an angle, is partly hidden, or is too small to read: redraw it as a card diagram. Keep its wording. Write "Redrawn from slide [mm:ss]" in the caption.
- No slide. The speaker explains the idea in words only: generate a card diagram from the concept.
- Comparison of options: use a table. No other visual is necessary.
- Numbers: use a bar chart or line chart.
Rules for slides:
- Use the frame where the slide is complete (all build steps are visible). This is usually the end time of the candidate.
- The contact sheets show the pictures that stay longest (max 144).
inventory.txtlists all candidates. Check it where the transcript refers to a visual that is not on a sheet. - For a screen recording with no slides, use the frames of the speaker's diagrams, notes, and demos in the same way.
- Do not use frames of the speaker, the audience, or the stage.
- Put two related slides side by side when you must compare them (before and after, input and output).
- Do not use a slide that is only a title or a decoration.
Card diagram standard (for each generated figure)
A reader who has not seen the video must understand the figure without the body text.
- Cards, not bare nodes. Each card has a title, a subtitle that gives its role, and 2 to 4 short bullets with real content.
- Max 7 cards. If you need more, split the figure.
- One job per figure. Give each figure a title that states the point, and a one-line subtitle that tells how to read it.
- Arrows are sentences. Each arrow label completes "A
<label>B" (for example: "fallible, so a human verifies"). No arrow without a reason. No crossed arrows. - Layout has meaning. Use rows or columns for stages, layers, or "cause to effect". State the reading order in the subtitle.
- Color has meaning. Use one color per category (for example: green for strengths, red for deficits). Do not use color for decoration.
- Use only content from the video. Do not add facts to make a card look complete.
- Draw with a real drawing tool (matplotlib, SVG, or HTML). Do not use Mermaid or Graphviz default output in the PDF.
- Min font size in the PDF: 6.5 pt after scaling to the page width.
Select the diagram form from the shape of the idea:
- Analogy (A is like B): two columns of cards with one mapping arrow per pair.
- Process or loop: cards in sequence with labeled arrows.
- Layers or architecture: one central card with satellites, as in a block diagram.
- Scale or spectrum (for example, autonomy levels): a labeled axis with items placed along it.
- Do and do not: two cards, red and green.
- Taxonomy: one parent card, child cards in groups.
Figure review (mandatory)
Open each rendered figure and answer these questions. If an answer is "no", correct the figure.
- Can I state the point of the figure in one sentence, from the figure only?
- Is each label readable, complete, and not cut off or hidden by an arrow?
- Does each arrow label make a true sentence with its two cards?
- Is each fact in the figure in the video? Is the [mm:ss] correct?
- For a slide: is the frame sharp, complete, and the correct slide for this idea?
Then check each example in the notes: does it say why the behavior happens, or "Reason not stated"? Add the speaker's reason where it is missing.
Then check the resources with code, not with your eyes:
- Each citation number has a row in section 8, and each row except general tools is cited at least once.
- Each internal link in the PDF goes to the correct row or section (pymupdf
get_links()). - Each URL gives an answer (HTTP 200). A 401 or 403 from a known site is usually a bot block, so keep the link. If a page is gone, keep the link and write "Link seems to be offline now".
Captions
- Slide: "Figure N:
<what it shows>. Slide [mm:ss]." - Redrawn slide: "Figure N:
<title>. Redrawn from slide [mm:ss]." - Generated diagram: "Figure N:
<title>. Generated from [mm:ss to mm:ss]." - If the slide needs data that it does not show, add max one more sentence.
Output structure
0. Summary box
Title, speaker, date, length, link, reader profile, and output path. Then max 3 sentences: the main argument and the most useful takeaway.
1. The talk in one picture
Figure 1: one card diagram with 4 to 7 cards that shows the argument of the video. Each card is one main idea with its key points. Arrows show why one idea leads to the next. Do not make a web of two-word nodes. If the speaker shows a recap slide, add it as Figure 2.
2. Main ideas
One numbered section per idea, in video order:
- Figure or figures (from "Visual selection")
- Claim [mm:ss]: max 2 sentences
- How it works: max 3 bullets. Do not repeat what the figure shows.
- Example or demo: input, result, and then:
- Why it happens [mm:ss]: the speaker's reason for the behavior. Search the transcript for it, because the reason often comes later in the video than the demo.
- Why the fix works [mm:ss]: only if the speaker shows a fix (for example "use code").
- Why it matters in practice
- Limits and failure modes
3. Comparison tables
Only where the video compares options. Take the columns from the content. Add a "When to use" column.
4. Rules of thumb
Each rule has a one-line reason.
5. Glossary
Term | Definition | [mm:ss]. Only the key terms.
6. Actions
Concrete things that the reader can do or test this week, matched to the reader's role.
7. Critical review
Weak claims, outdated parts, and points to verify. Keep this section separate from the speaker's content.
8. Resources
Papers, repos, tools, datasets, and people that the speaker names or shows on a slide. Number them in video order. Start with one line: "Click a number in the text to jump here. Click a section number in "Cited in" to jump back." Columns: # | Resource | What it is | Link | Link from | [mm:ss] | Cited in
- #:
<a id="ref-N"></a>N, so that the citations can jump to the row. - Link: a clickable short form, for example
[arxiv.org/abs/2407.21783](https://arxiv.org/abs/2407.21783). Keep the visible text short (max 34 characters). - Link from: where you got the link, in this order of preference:
- "Video description": the links that the speaker lists.
- "Seen on screen [mm:ss]": a URL or a paper title that you read on a frame. Grab the frame if necessary.
- "Official site (added)": the official page or paper that you found. Use only the owner's own site (arxiv.org, github.com, the company site). Do not use a blog post about it. If you cannot find a link that you are sure of, write "No link found". Do not guess a URL.
- Cited in: the sections that cite the resource, each as a link, for example
[2.4](#sec-2.4). Make this column with code from the citations, not by hand.
Writing rules (ASD-STE100)
- Max 20 words per sentence. Active voice, present tense.
- One idea per sentence. Use the same term for the same concept.
- Define each acronym at first use.
- No filler, no idioms, no em dashes.
Deliverable and length
- PDF is the main deliverable. Embed each figure as an image with its caption. Keep each heading on the same page as its first figure. Keep max half a page of text between two figures.
- Citations, resource links, and "Cited in" links must be clickable in the PDF. Write them in the Markdown as
[[n]](#ref-n),[text](url), and[2.4](#sec-2.4).build_pdf.pymakes an anchorsec-<number>for each numbered heading. - Save the figures in a "figures" folder and the notes source as Markdown, next to the PDF.
- Chat reply: give links to the files, the figure count (slides, redrawn, generated), and the points that I must verify. Do not paste the full notes in chat.
- If you cannot make files: write the notes as Markdown in chat. Describe each slide figure in one line with its [mm:ss]. Write each generated figure as a Mermaid code block with all labels in double quotes.
- If the video is longer than 60 minutes, or your output limit is small, write sections 0 to 2 first. Then ask to continue.
Build report (only when I ask for cost or tokens)
Give a table of token use per phase: transcript, slide scan, slide read, diagrams, writing, PDF build and review. Say which numbers are measured and which are estimates.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

