podcast_show_notes v1.0.0

name: podcast_show_notes description: Write podcast and video show notes people actually read: a summary that stands alone, chapter titles written for search, verbatim quote picks with timestamps, guest and link sections, and a final accuracy pass against the transcript. Ships a tested formatter that validates chapters, quotes, and links and outputs web notes, a plain-text description, and Podcasting 2.0 chapters JSON. Use when writing or fixing episode notes, show notes, video descriptions, or chapter lists.

Podcast Show Notes

Purpose

Turn a finished episode into notes that do three jobs at once: help a reader decide in seconds whether to play it, help a listener jump to the part they want, and give search engines accurate text to index. This skill covers the writing and the checking. Recording, editing, and feed building live in the podcast production skill. Clip cutting lives in the podcast video clips skill.

The input is a transcript or a timed outline plus the episode facts. The output is one episode spec, three formatted deliverables, and an accuracy pass with every flagged item resolved or reported.

Workflow

1. Gather the episode facts before writing a word

Collect: the final title, the transcript with timestamps, guest name spellings and roles as the guests supplied them, every link mentioned on air, credits, and the one action the episode asks for. Get guest plugs at this stage. Chasing a guest for a link after publishing costs goodwill and delays the notes.

Work from the final cut only. Notes written against an early cut carry timestamps and quotes for audio that no longer exists.

2. Write a summary that stands alone

Write the summary for a reader who will never press play. Three to five sentences, in this order:

1. Who is in the episode and what situation they are in.
2. What they did, decided, or found, with the concrete detail that proves it.
3. What a listener takes away and can use.

Rules that keep it honest and readable:

• Put the searchable topic words in the first sentence. Apps and search results show the opening lines and cut the rest.
• Skip throat-clearing openers. "In this episode we sit down with" wastes the lines that decide whether anyone reads on.
• Name specific things: numbers, tools, places, decisions. A summary with no specific detail could describe any episode.
• Promise only what the episode delivers. Check each claim in the summary against the transcript at the accuracy pass.

3. Build the chapter list and name chapters for search

Mark a chapter where the topic actually changes, at the first line of the new topic. Place chapters from the transcript, not from the recording plan, because conversations drift from plans.

Format rules, verified against YouTube Help and the Podcasting 2.0 namespace docs:

• First chapter starts at 00:00.
• At least three chapters, in ascending order.
• Each chapter runs at least 10 seconds. In practice, chapters under a minute rarely earn a separate line on a talk episode.
• One chapter per topic. Split a stretch when the title would need two topics joined together.

Title rules, in full in references/chapter-quote-link-rules.md:

• Use the words a listener would search for, with the concrete noun early.
• Name the turn in the story, not the segment number. "The margin mistake on order two" beats "Part 3".
• Match the words used on air so readers recognise the section they heard about.
• Keep titles plain text, no emoji or hashtags.

4. Pick quotes that pass four tests

Choose two or three quotes. Each one must pass the verbatim test, the standalone test, the specific test, and the speaker test, defined in references/chapter-quote-link-rules.md. Attribute every quote with the speaker name and timestamp. Read 30 seconds of transcript on either side of a quote before keeping it, because a quote pulled out of its context can reverse what the speaker meant.

Never paraphrase inside quotation marks. If the spoken line is messy, pick a cleaner line from the same speaker instead of rewriting the one you have.

5. Write the guest and link sections

Guest section: one entry per guest, name spelled as the guest spells it, one line of role as supplied, one primary link. Verify name spellings against the guest's own site or publication, because transcripts misspell names often.

Link section: every resource mentioned on air, in the order it was mentioned, labelled with what the reader gets, with a short note when the destination is not obvious. Disclose affiliate or paid links in plain words next to the link. Credit everyone who worked on the episode.

Add a transcript link when a transcript exists. Transcripts serve readers who cannot listen and give the episode page its full searchable text.

6. Format and validate with the bundled formatter

Fill in templates/episode-spec.json with the episode content, then run:

bash
python3 scripts/format_notes.py templates/episode-spec.json --outdir out
python3 scripts/format_notes.py templates/episode-spec.json --outdir out --check-links

The formatter writes show-notes.md for the episode page, description.txt with the chapter list for YouTube and podcast apps, and chapters.json in Podcasting 2.0 format (version 1.2.0, numeric startTime in seconds) for the RSS podcast:chapters tag. It errors on chapters that start late, run under 10 seconds, fall out of order, quotes with no speaker, and links that are not http or https URLs. It warns on vague chapter titles, quotes that open with an unresolved pronoun, duplicate links, and link labels that tell the reader nothing. Fix every error. Resolve each warning or note why it stands.

Tested in this run: the sample spec in templates/ passes with zero warnings, and a broken spec with a late first chapter, a 5 second chapter, a missing speaker, and a bad URL fails with five errors and writes no files.

7. Run the final accuracy pass

Go through the finished notes line by line against the transcript and the fact list:

• Every quote matches the transcript word for word, with the right speaker and a timestamp that lands on the line.
• Every chapter timestamp lands at the start of its topic in the final cut.
• Every name, title, number, and organisation is spelled as its owner spells it.
• Every claim in the summary happens in the episode, in the order the summary implies.
• Every link opens, goes where its label says, and still points at the thing mentioned on air.
• The chapter list is identical across the web notes, the description, and the chapters JSON. Times or titles that differ between versions send listeners to the wrong place.

Anything that fails gets fixed in the spec, not patched in one output file. Regenerate after fixing so all three outputs stay in sync.

Output Contract

A finished job delivers: (1) the episode spec JSON with all sections filled from the final cut; (2) show-notes.md with summary, chapters, quotes, guests, links, transcript link, and credits; (3) description.txt ready to paste into YouTube or a podcast host; (4) chapters.json in Podcasting 2.0 format; (5) the formatter output showing zero errors, plus a note for any warning left standing; (6) a completed accuracy pass, reported item by item when something had to change.

Operating Rules

• Accuracy rule: every factual claim must be verified via web search or a primary source. Never invent numbers, dates, quotes, or events. Unverifiable means cut it or frame it as opinion.
• Never invent a quote, a timestamp, or a resource. If it is not in the transcript or the fact list, it does not go in the notes.
• Never write notes against an unfinished cut. Timestamps from an early edit are wrong timestamps.
• Keep the three output versions in sync by editing the spec and regenerating. Hand edits to one file create drift.
• Platform numbers in this skill (first chapter at 00:00, at least three chapters, 10 second minimum chapter length, Podcasting 2.0 JSON shape) come from YouTube Help and the Podcasting 2.0 namespace docs. When a platform changes its rules, update the formatter and this file together.
• A live link check is a signal, not a verdict. A flagged link gets opened by hand before it is cut or replaced.
• Do not bury the link section above the summary or chapters. Readers come for the summary and the jumps first, links second.