jasveerai88/podcast-kit

podcast-kit — agent skill

Purpose

Publishing an episode is a set of small copying jobs from one set of facts: the notes, the YouTube chapters, the Podcasting 2.0 chapters file, and the hunt for the clip-worthy moment. This tool takes ONE episode JSON and produces all of them, so the facts exist exactly once. Pure Python standard library; local only; the episode file is the only thing it reads.

The honesty core of this tool: a chapter list is exported only when it is valid — players silently ignore broken lists, so handing out a broken export is worse than handing out none — and an audiogram score is a ranking of where to look first, computed from transcript text alone. It is never a prediction that a moment will perform, and a plan is never a rendered audiogram.

When to use / not use

Use when:

• An episode exists as (or can be written as) one episode JSON: finishing it means producing show notes, chapters for YouTube and podcast apps, and deciding what to clip.
• A pipeline needs a yes/no chapter gate: chapters exit 0 = the list is valid and the exports are in the output; exit 1 = do not publish the chapters as they stand.
• An editor wants the five timestamps worth listening to before scrubbing a whole recording.

Do NOT use when:

• You need transcription — the transcript is an input here. Produce segments with a transcription tool first.
• You need audio or video rendered — audiogram-plan is a plan (timestamps + words + reasons). Take it to an editor or a rendering tool.
• You need RSS, hosting or batch processing — this tool finishes one episode file at a time, deliberately.

Commands

Every command takes the episode file as a positional argument and supports --json.

# Show notes — Markdown (default) or plain text
python3 src/podcast_kit.py show-notes EPISODE.json \
    [--format md|text]

# Validate + export chapters (exit 1 + no export when invalid)
python3 src/podcast_kit.py chapters EPISODE.json \
    [--format youtube|json|both]

# Rank the moments worth clipping (exit 1 when none qualify)
python3 src/podcast_kit.py audiogram-plan EPISODE.json \
    [--top 5]

Episode fields: show (optional), episode (optional int), title (required by show-notes), published (optional, printed as-is), duration_seconds (required by chapters; seconds or a timestamp string), summary (required by show-notes), guests — list of {"name", "role"?}, links — list of {"label", "url"}, chapters — list of {"start", "title"}, transcript — list of {"start", "end", "speaker"?, "text"}. Timestamps accept seconds (754), "M:SS" or "H:MM:SS" everywhere. The file is validated on every read; structural problems (missing fields, bad timestamps, a segment ending before it starts, a segment running past the duration) are exit-2 errors that name the offending chapter or segment.

Chapter validation (exact)

Problems (exit 1, no export): the first chapter does not start at 0; a start is not strictly after the previous start; a start is at or past duration_seconds (a start at duration − 1 is valid); a title is empty.

Warnings (reported, export still produced): fewer than 3 chapters; a chapter shorter than 10 seconds. Both are YouTube's rules, not Podcasting 2.0's — the export is valid either way, YouTube may ignore it.

Exports: YouTube lines are MM:SS Title (or H:MM:SS when the episode runs an hour or more). Podcasting 2.0 is {"version": "1.2.0", "chapters": [{"startTime", "title", "endTime"}]} — each chapter's endTime is the next chapter's startTime, and the last chapter's endTime is the duration.

The audiogram score (exact)

Per transcript segment, from its text only:

• question marks: +2 each, capped at +4
• numbers (digit runs, e.g. 18, 1,900): +2 each, capped +4
• exclamation marks: +1 each, capped at +2
• strong phrases — the fixed list "the truth is", "biggest mistake", "nobody tells you", "everyone gets wrong", "never", "always", "secret", "myth" (whole-word, case-insensitive): +3 each, capped +6
• segment length 15–60 seconds inclusive: +2

Floor: a segment needs a total of 5 to be listed. Order: score descending, ties by earliest start. --top N limits the list (0 or negative = every qualifying segment). Every listed moment prints its reasons with the actual signals found — a score with no reasons does not exist in this tool.

Output JSON schema (--json)

Common fields: tool ("podcast-kit"), version, command, episode_file (file name).

show-notes: title, format ("markdown" or "text"), notes — the rendered notes as one string, exactly what the text view prints. chapters: title, duration_seconds, valid (bool), problems (list of strings), warnings (list of strings), chapters — each {start_seconds, start, title, end_seconds, end, length_seconds} — youtube (the export text, or null when invalid), podcasting20 (the export object, or null when invalid). audiogram-plan: title, segments_scanned, floor (5), moments — each {rank, start_seconds, start, end_seconds, end, duration_seconds, speaker, text, score, reasons}. When no segment qualifies, moments is [] and a note field explains that the floor was not cleared (exit 1).

On error, stdout is a single object: {"error": "<message>"} with exit code 2 — including argparse usage errors in --json mode. Never plain text, never a traceback.

Exit codes

• 0 — command succeeded; for audiogram-plan, at least one segment cleared the floor.
• 1 — a finding: chapters found validation problems (no export was produced), or audiogram-plan found no segment worth clipping. Neither is a crash — act on the finding.
• 2 — ERROR: episode file missing or not valid JSON, a required field missing, a bad timestamp, a malformed chapter or segment, an invalid flag. No output facts may be quoted from a failed run.

Limits & honesty rules the agent must respect

• Invalid chapters export nothing. When chapters exits 1, do not reconstruct an export from the chapters array in the JSON output and publish it — the problems listed are exactly why players would ignore it. Fix the episode file and re-run.
• Warnings are not problems. A valid list with warnings may be published; say plainly that YouTube might not display the chapters (too few, or one too short) while podcast apps will.
• A score is not a prediction. Report a moment as "ranked first by the text signals", never as "the best moment" or "the clip that will perform". The tool cannot hear the recording; delivery can make a low-scoring segment the right clip, and the plan says so.
• Exit 1 from audiogram-plan is not an empty episode. It means no segment carried the ranked signals. Never report it as "no good moments" without the qualifier that the tool reads text only.
• A plan is not a file. audiogram-plan produces timestamps and text. Never tell the user an audiogram exists until a rendering tool has actually made one from the plan.
• Local only: the tool reads only the episode file named on the command line and sends nothing anywhere.