Generate Podcast

Purpose

Generate audio content — podcasts, audio briefings, narrated summaries, or any spoken audio. Use this skill for all generated audio, not just podcasts. The podcast-helper script handles synthesis, catalog management, cover art generation, and publishing.

Workflow

1. Plan

• Topic and angle
• Speaker names and voices — prefer the Meta AI voices by default (the MAI_01 and MAI_03 catalog ids: Warm and Smooth); they are the recommended, production-quality set and the right pick most of the time. Default to Warm (avocado_v2:MAI_01) and Smooth (avocado_v2:MAI_03). When the topic, tone, or user request steers toward a different catalog voice — an accent, a character fit, or more distinct speakers — it's perfectly fine to pick it from the catalog. The full voice catalog is at /opt/hatch/skills/voice-selector/voice_source.json — pick by the entry's display name and pass its id (colon form like avocado_v2:MAI_01 is fine). Any number of speakers is supported. ("MAI" is the internal id prefix only — say "Meta AI voices" or display names to the user, never "MAI".)
• Host names — give each speaker a real first name (e.g. Alex, Jordan). These are the show's own character names, chosen by you and separate from the voice display names: never label a speaker with a voice name like "Warm" or "Smooth". Remember the name you give each voice — record the pairing in ~/MEMORY.md (e.g. "podcast host Alex = avocado_v2:MAI_01") and, before naming a new host, check there for a name you've already used for that voice. Reuse the same name whenever you use that voice again, so a given voice is always the same character to the user. For a recurring series, reuse the same host names and the same voice assignments in every episode so it sounds like the same show — pin them in the cron task body (see Scheduling).
• Target length — 5–15 minutes; ~130 words/minute
• Avoid repeating past episodes — before settling the topic and angle, run podcast-helper manifest read and look at each recent episode's topics field (a short summary of what that episode already covered). Steer the new episode toward fresh material or a genuinely new angle rather than re-covering ground. This matters most for a recurring series.

2. Write the script

Write the full dialogue. Label each turn with the speaker name followed by a colon:

Alex: Welcome to the podcast. Today we're diving into async Rust.
Jordan: Great topic. Let's start with why async matters.
Alex: The big advantage is zero-cost abstractions...

Write the script to a file (e.g. /tmp/script.txt).

The script goes directly to a TTS model — write it in spoken form. The text will be read aloud exactly as written. Follow these guidelines:

• Numbers: write out in full — "one hundred thousand", "forty-two dollars and fifty cents", "three point five percent"
• Times: "ten o'clock A M", "three thirty P M", "noon", "midnight"
• Years: "twenty twenty-five", "nineteen ninety-nine"
• Abbreviations: spell out — "U S A", "A P I" (pronounceable acronyms like "NASA" can stay)
• URLs: simplify — "example dot com link" instead of raw URLs
• Email: "john at company dot com"
• Lists/data: convert to natural sentences, limit to top 3–5 items
• Punctuation: use commas for natural pauses. If a sentence runs long, split it into two complete sentences — do not clip it into fragments.
• Never include: stage directions like (pause), sound effects, markup, emoji, citation numbers like [1], math symbols, or visual separators like ---

Write complete, conversational sentences — not headlines. Every line a host speaks should be a full grammatical sentence with a subject and a verb, the way people actually talk out loud. Avoid telegraphic, verbless fragments and stat-ticker read-outs; this is a conversation, not a wire report or a scoreboard. An occasional short line for emphasis ("Unbelievable.") is fine, but never string clipped fragments together.

• Avoid: Second assist of the night for Messi. Two one Argentina. Full time. Heartbreak for England.
• Prefer: That's Messi's second assist of the night, and it puts Argentina up two to one. When the whistle went, it was heartbreak for England.

When you present a stat or a scoreline, fold it into a spoken sentence ("England had just forty-four percent of the ball") rather than dropping it in as a bare fragment ("England, forty-four percent possession").

3. Generate

Write a topics summary for dedup. Before generating, write a short bulleted summary of the major topics and key points this episode covered to a file (e.g. /tmp/topics.md) and pass it with --topics-file. Keep it concise — a handful of bullets naming the subjects and any specific stories, guests, or angles, not a full transcript. It is persisted alongside the episode and read by future generations (via the topics field in manifest read) to avoid repeating material. Example:

- Async Rust fundamentals: futures, executors, zero-cost abstractions
- Tokio vs async-std tradeoffs
- Common pitfalls: blocking in async contexts, .await forgetting

Default: generate only, do not publish. Only add --publish when the user explicitly asked to publish or when the podcast catalog already has an RSS feed — a "feed" object with a non-empty feed_url (meaning they've published to a feed before and want new episodes added). A "feed" object that has only a spotify_show_url (from a personal Save to Spotify) is not an RSS feed and must not trigger --publish; publishing is public and requires explicit consent.

Always pass --cover-prompt with a short description of the episode's theme so podcast-helper can generate cover art automatically.

Do not pass --cover-image. Publishing accepts only generated cover art or the bundled default, so an episode published with --cover-image fails. Use --cover-prompt instead; if the user hands you an image file, generate a cover from a prompt describing it and say you did. The flag still parses and will be reconnected later — it just cannot reach the feed today.

Language: unless the user asks for another language, write the title, description, feed copy, and script in the language of the current conversation. podcast-helper defaults synthesis to the request's JARVIS_PRESENTATION_LOCALE; pass --language only to honor an explicit user choice (e.g. --language es, --language pt, or a locale like pt_BR). Quality varies significantly across languages — English is highest quality; other languages can be rough (mispronunciations, accent), and some voices handle a given language better than others (try a different --speaker voice from voice_source.json if one sounds wrong). Tell the user non-English audio may be imperfect. See the tts skill's Language section for details.

One-off episode:

podcast-helper generate \
  --script /tmp/script.txt \
  --title "Deep Dive into Async Rust" \
  --description "Alex and Jordan explore async patterns in Rust" \
  --speaker Alex=avocado_v2:MAI_03 \
  --speaker Jordan=avocado_v2:MAI_01 \
  --cover-prompt "async Rust programming, gears and lightning bolts" \
  --topics-file /tmp/topics.md

Cron/recurring episode — pass --series-id matching the cron job ID so episodes in the same series share cover art:

podcast-helper generate \
  --script /tmp/script.txt \
  --title "Morning News - June 2, 2026" \
  --description "Today's top stories" \
  --speaker Alex=avocado_v2:MAI_03 \
  --speaker Jordan=avocado_v2:MAI_01 \
  --series-id daily-news \
  --cover-prompt "morning news briefing, sunrise and newspaper" \
  --topics-file /tmp/topics.md

With --series-id, cover art is generated once for the first episode and reused for all subsequent episodes in the series.

If the user asked to publish, or the podcast catalog already has an RSS feed — run podcast-helper manifest read and check for a "feed" object with a non-empty feed_url (a feed with only spotify_show_url does not count):

podcast-helper generate \
  --script /tmp/script.txt \
  --title "Deep Dive into Async Rust" \
  --description "Alex and Jordan explore async patterns in Rust" \
  --speaker Alex=avocado_v2:MAI_03 \
  --speaker Jordan=avocado_v2:MAI_01 \
  --cover-prompt "async Rust programming" \
  --topics-file /tmp/topics.md \
  --publish --feed-title "Daily with Alex"

Returns JSON with path, duration_secs, slug, cover, and (if published) feed_url, episode_url, and subscription_links.

4. Deliver to chat

Always present the title as plain text above the playable link:

{title}
[{title}](sandbox://workspace/podcasts/{slug}/{slug}.mp3)

The first time you mention publishing, a personal feed, or subscription in a conversation, briefly explain what the feed is: a personal RSS podcast feed they can add to a podcast app, and future published episodes will show up there automatically. After that first explanation, use shorter wording.

If the episode was published, mention it was published and that it will appear in their feed. Note that published episodes are public. If the result has published: false with publish_error, the audio was generated locally but publication failed: relay publish_error to the user and do not claim it reached the feed. If it also has blocked: true, apply the content-review stop rule in step 5 and skip the publish follow-up below: do not retry, reword the script, or use another publish path. If it has retryable: true, content review could not run; tell the user publication can be retried later using the full step 5 podcast-helper publish command. Before retrying, run podcast-helper manifest read and reuse the target feed's existing feed_title exactly when one exists; never invent or alter a title for an existing feed.

After delivering, present applicable follow-ups:

1. If not published and not blocked: "Want me to publish this to a personal podcast feed? It's an RSS feed you can add to Apple Podcasts, Overcast, Pocket Casts, or most other podcast players, and future published episodes will show up there automatically. Note: published episodes are public — anyone with the link can listen."
2. If no cron job exists: "Generate a new episode every day?"

5. Publish (if not done in step 3)

podcast-helper publish \
  --slug {slug} \
  --feed-title "Daily with Alex" \
  --feed-description "Daily news and tech updates"

Returns JSON with feed_url, episode_url, and subscription_links.

Public publishing is content-reviewed. If the output has "blocked": true, the episode was not published: the audio and catalog entry still exist locally, but it cannot go to the public feed. Relay the returned error message to the user plainly and stop — do not retry, reword the script to get around it, or fall back to another publish path. Saving to the user's own Spotify show is unaffected by this review.

A publish that brings a new show cover unifies artwork across that show — its episodes' covers are replaced with it in the podcast catalog. A series show keeps its series cover, and an episode whose cover was changed with update-cover keeps the show's existing cover when published. Another feed's episodes keep their own artwork.

After publishing, always re-present the listen link and confirm publication:

{title}
[{title}](sandbox://workspace/podcasts/{slug}/{slug}.mp3)

Published to your personal feed, which is the RSS feed you can subscribe to in your podcast app so future published episodes show up there automatically.
Published episodes are public — anyone with the feed link can listen.

6. Subscribe (after publishing)

On the first episode published to a feed, present subscription links from the output JSON:

Subscribe to your personal feed:

RSS feed URL (copy and paste into any podcast player):
`{subscription_links.rss}`

Or open directly in a podcast app:
- [Open in Apple Podcasts]({subscription_links.apple_podcasts})
- [Open in Overcast]({subscription_links.overcast})
- [Open in Pocket Casts]({subscription_links.pocket_casts})

This is the RSS feed for your generated episodes, and once you add it to a podcast app, future published episodes will appear there automatically.

Important — how to render the feed URL: The RSS feed URL is for the user to copy and paste, never to click. Always present any published https:// URL (feed URL, episode link) wrapped in backticks as code — either inline `https://…` or inside a fenced code block. Never emit it as a bare URL (a bare https://… auto-linkifies on native clients) and never as a [label](https://…) markdown link; either form may fail to open on native clients and invites a click instead of a copy. Do not offer direct episode download links. The only clickable links should be local sandbox:// listen links and the podcast-app protocol links (podcast://, overcast://, pktc://).

On subsequent episodes to the same feed, skip — the user is already subscribed.

Feed Organization

Always use a single feed unless the user explicitly asks for a separate one. Before publishing, run podcast-helper manifest read. feeds lists every feed on this VM and feed is whichever was published to most recently; if either has a non-empty feed_url, reuse that feed's feed_title exactly.

When the user does keep more than one show, the title is what picks the feed: publishing with a --feed-title that matches an existing feed adds to it, and any other title creates a new one. So reuse a title character for character when adding to a show, and never reuse one for a different show.

On the first publish (no feed_url in the podcast catalog yet — a feed object that only carries a spotify_show_url still counts as no RSS feed), choose a personal feed title based on the user's Muse name — e.g. "Today with Alex", "News with Alex".

Add to your Spotify (personal, optional)

When the user explicitly asks to put a generated episode on their Spotify, use podcast-helper save-to-spotify to add it to the user's own Spotify account. This is a personal save to the user's own Spotify library/show — it is NOT the public/subscribable RSS feed publishing described above, and does not use podcast-helper --publish. Only do this on an explicit request; do not offer it proactively.

Run the upload through podcast-helper (not the raw save-to-spotify CLI): the helper uploads via the bundled save-to-spotify CLI and records the resulting Spotify show link into the podcast catalog so it shows up on the library podcasts page. See references/save-to-spotify.md for the underlying CLI, the connect flow, and rules.

1. List shows / check connection: run save-to-spotify --json shows — it lists existing shows and confirms Spotify is connected. If it fails with a token / "not connected" error, tell the user to connect Spotify in Settings → Connections → Spotify (the shared Spotify connection), then retry. This tool has no auth subcommands or connect link. Ask the user whether to reuse an existing show or create a new one; don't silently pick.
2. Upload + record with podcast-helper (confirm title, target show, and summary with the user first — this writes to their account). The helper reads the audio/title/cover from the podcast catalog by slug; pass a cover only to override (must be JPEG/PNG ≤ 1 MB — convert .webp/other formats first):

   podcast-helper save-to-spotify \
     --slug {slug} \
     [--show-id <id> | --new-show "<show title>"] \
     [--title "{title}"] [--summary "{description}"] [--image {cover}]
   

   Returns JSON with episode_id, episode_uri, spotify_show_id, and spotify_show_url.
3. Wait for readiness: save-to-spotify --json episodes status <episode-id> --wait (use the episode_id from step 2). Processing is server-side and takes a few minutes; a returned episode_uri means it was accepted. If it stalls in NOT_READY (Spotify occasionally 503s), it's a Spotify-side delay — tell the user it's processing and retry later rather than polling indefinitely.
4. Tell the user it's on their Spotify and may take a few minutes to appear in the app. Because the show link is now recorded, the Spotify option on the podcasts library page will link to their show. Refer to the show and episodes by title and summarize readiness in plain language. Spotify show IDs, episode IDs, and spotify:show: / spotify:episode: URIs are internal CLI handles: use them for subsequent commands, but never include them in a user-facing response.

For deletion, use the raw save-to-spotify CLI, not podcast-helper, spotify-api, podcasters.spotify.com, or creators.spotify.com. Start with save-to-spotify --json shows, resolve the requested show by title, and inspect it with shows get <show-id>. Use episodes --show-id <show-id> followed by episodes delete <episode-id> to remove one episode. To remove the entire show, confirm that all its episodes will be deleted and run shows delete <show-id>; that command removes the episodes too. Treat {"status":"deleted"} as accepted, then poll the relevant shows or episodes --show-id inventory for up to 60 seconds. Confirm deletion only after the item is absent; otherwise tell the user Spotify is still propagating the accepted deletion and do not repeat it. Deleting the Spotify copy does not delete local audio or an RSS feed. See references/save-to-spotify.md for the full command flow.

Cover Art

Cover art is handled automatically by podcast-helper during generation. You control it with two flags:

• --cover-prompt — a short description of the episode theme (e.g. "morning news briefing, sunrise and cityscape"). podcast-helper shells out to media-generation to create a square icon-style image. Always provide this.
• --series-id — groups episodes that share the same cover art. Use the cron job ID for recurring episodes. Without this, each episode gets unique art.

How artwork flows:

Scenario	Behavior
One-off episode	Unique cover generated per episode from --cover-prompt
Recurring/cron episode	First episode generates cover; subsequent episodes with same --series-id reuse it
Published episode	A new show cover replaces that feed's episode covers; a series show, or an episode changed with update-cover, keeps the show's cover

Fallback when no --cover-prompt is provided: the bundled default cover (/opt/hatch/skills/generate_podcast/default-cover.jpg). The user's avatar is also tried first, but an avatar cover cannot currently be published — one more reason to always pass --cover-prompt on an episode headed for a feed.

You do NOT need to call media.generate_image yourself for cover art — podcast-helper handles it internally.

--cover-image is not available right now: publishing takes only generated cover art or the bundled default. The flag is still accepted so it can be reconnected later, but an episode published with it fails, so do not use it.

Changing the cover

When the user asks to change an episode's cover — a new prompt, a variation, or an image they hand you — regenerate through the helper so the catalog reference moves to a new file:

podcast-helper update-cover \
  --slug {slug} \
  --cover-prompt "starry night sky over a mountain lake"

This generates new artwork to a fresh path, updates the episode's cover reference to it, and prints the new path as cover. Present that new path in chat.

Hard rules:

• Never overwrite the current cover file. Do not cp, move, or rename a new image over the old cover path, do not call media.generate_image for covers, and do not present the old path again after changing its bytes. Already-delivered previews and library rows reference the old file by path, and clients cache by path — rewriting its bytes silently changes what was already shown (or shows stale art), which is the failure this flow exists to prevent.
• A user-supplied image is a prompt, not a file. Describe it in --cover-prompt and generate (the same rule as --cover-image at generation time); publishing still takes only generated art.
• Series episodes diverge. update-cover changes only that episode in the local catalog; the show cover, the other episodes, and future --series-id generations keep the shared series cover. Publishing the edited episode keeps the show's cover too, and the public feed shows that cover (a feed has one cover).
• Published feeds keep the previous art, and publish refuses repeats. podcast-helper publish refuses an already-published episode, because publishing appends a NEW episode entry (duplicating the episode in every subscriber's feed) while the catalog row forgets the original. So there is no publish path that pushes a cover change: a cover-only refresh does not exist yet, and cover edits on published shows stay local to the catalog and chat.

Scheduling

When a user asks for a recurring podcast, audio briefing, or scheduled audio content:

1. Generate a first episode now — don't just set up the cron and leave them with nothing to listen to. Generate and deliver the first episode immediately so the user has something right away.
2. Ask about publishing — offer to publish to a podcast feed so they can subscribe and listen in their preferred podcast app. If they agree, publish the first episode and present subscription links.
3. Then create the cron job — set up the recurring schedule.

For recurring podcasts, create a cron job using the cron tool. Always set timeout_secs: 1800.

Example cron tool call:

{
  "action": "add",
  "file_name": "daily-podcast__daily@13:00:00.md",
  "id": "daily-podcast",
  "enabled": true,
  "mode": "task",
  "timeout_secs": 1800,
  "schedule": {
    "kind": "daily",
    "timezone": "UTC",
    "time": "13:00:00"
  },
  "body": "Generate a new podcast episode on <topic>. Follow the generate_podcast skill workflow. Keep the same cast every episode: hosts Alex (--speaker Alex=avocado_v2:MAI_01) and Jordan (--speaker Jordan=avocado_v2:MAI_03). Use --series-id daily-podcast and --cover-prompt '<topic description>' when calling podcast-helper generate. Before choosing today's angle, run podcast-helper manifest read and review each recent episode's topics field to avoid repeating what was already covered. Write a short topics summary to /tmp/topics.md and pass it with --topics-file so future episodes can dedup against it. Publish to the feed after generating."
}

Keep cron task descriptions concrete — include the topic angle, the fixed cast (host names and their voice ids, so every episode uses the same hosts and voices), --series-id matching the cron ID, and explicit instructions to research live results at generation time.

Utility Commands

For edge cases and manual operations, podcast-helper exposes sub-commands:

• podcast-helper manifest read — print the current podcast catalog
• podcast-helper manifest add-episode --slug ... --title ... --duration-secs ... --path ... --chunk-count ... — add episode
• podcast-helper manifest update-episode --slug ... [--episode-url ...] [--feed-url ...] — update episode
• podcast-helper update-cover --slug ... --cover-prompt ... — replace an episode's cover with newly generated art (updates the reference; never overwrites the old file)
• podcast-helper generate-slug --title "..." — generate a kebab-case slug with today's date

Listening to Existing Episodes

If the user asks to listen to a podcast, hear their podcast, or asks about their episodes, read the podcast catalog with podcast-helper manifest read and present listen links for the relevant episodes:

[{title}](sandbox://workspace/podcasts/{slug}/{slug}.mp3)

If the feed is published, also include the subscription links (see section 6 format).

Operating Rules

1. Use voices from /opt/hatch/skills/voice-selector/voice_source.json, referenced by their catalog id. Default to the Meta AI voices (catalog ids MAI_01 and MAI_03) most of the time, but pick another catalog voice when the topic, tone, or user request steers that way. Never say "MAI" to the user — call them the Meta AI voices or use display names.
2. If a chunk fails, tts synthesize-script stops — do not deliver a partial episode. Most failures are transient backend issues: retry the same generation later on a bounded backoff (~5m, ~10m, ~30m, ~1h), keeping the same speaker voices. Never swap in a different voice or a different TTS engine to work around a failure. Schedule the retry (a delayed wakeup or short cron) rather than blocking, and tell the user you'll deliver the episode once synthesis recovers. If it still fails after the ~1h retry, stop — cancel the scheduled retry, report the error, and suggest they try again later. (A ... not allowed to use voiceID ... error won't clear on retry — that voice id isn't permitted for this client; pick another from voice_source.json and regenerate. Auth or clear request errors likewise need a fix, not a retry.)
3. On first episode in a new feed, help the user subscribe. On subsequent episodes, skip.
4. Cron runs: Follow whatever the cron task description says. If it says to publish, publish without confirmation.
5. Never present a published https:// feed or episode URL as a bare or clickable link — always as copyable code (wrapped in backticks). Only sandbox:// listen links and podcast-app protocol links (podcast://, overcast://, pktc://) may be clickable.