personalized-podcast: a coding agent skill that turns your files into a two-host MP3

What personalized-podcast actually is, and who it is for

This is not a podcast app. It is a skill directory you clone into your coding agent, plus a small Python pipeline the agent calls. The README describes the target as anyone who already has a coding agent that supports skills, listing Claude Code, Gemini CLI and Copilot CLI as examples. The pitch is that the agent already writes well and follows instructions, so it can write a two-host script instead of you prompting a chat window and copy-pasting the result into a TTS tool.

The content sources are deliberately broad: a pasted block of text, a local file path, a URL, or a described topic. The README gives newsletter files, PDFs, meeting transcripts, tweets and research papers as inputs. The output is an MP3 that opens locally, and optionally an RSS feed on GitHub Pages that any podcast client can subscribe to.

The second use case in the README is the unusual one. Feed the pipeline your resume, journal entries or meeting transcripts, then ask the hosts to comment on their impressions of you as a person. That is a different product from listening to an article on the train, and it is the part of the README that reads most like a genuine personal motivation rather than a feature list.

The pipeline: agent writes the script, Fish Audio speaks it, ffmpeg stitches it

The README lays out four stages. The agent reads your content and writes a two-host conversation script. Fish Audio generates speech per line, with a different voice per host. The audio is stitched together with pacing and fades. The MP3 opens and plays.

Two details in the repository layout matter more than the diagram. First, script generation happens inside your coding agent, and the README states plainly that no separate LLM API call is needed. That means the skill has no model API key of its own; the intelligence comes from whatever agent you already pay for. Second, the data directory lives at ~/.personalized-podcast/, holding config.yaml, a .env file with the Fish Audio key, scripts_output/ for generated scripts as JSON, and episodes/ for the MP3s.

Audio work is handled by pydub plus ffmpeg, which is why ffmpeg is a hard requirement rather than an optional extra. The default show has two hosts with fixed roles: Alex introduces topics and asks questions, Sam adds depth and opinions. Those roles live in PROMPT.md, which the README calls the big one for customization, and voice selection lives in the config as Fish Audio reference IDs.

Installing the skill and generating a first episode

There is no package index entry and no installer. The README's quick start clones the repository directly into the skills directory your agent reads:

gh repo clone zarazhangrui/personalized-podcast-skill ~/.claude/skills/personalized-podcast

That path is Claude Code specific. If you run Gemini CLI or Copilot CLI, the README lists them as supported agents but does not give an equivalent destination directory, so you will need to find where your agent looks for skills.

Once the directory exists, the entry point is the slash command. The README shows three forms, including a local file and a URL:

/podcast read ~/Downloads/newsletter.txt
/podcast https://some-article-url.com

On the first run, per the README, the agent sets up the Python environment, installs dependencies, and asks for a Fish Audio API key. The free tier is enough to start, and the default voices are pre-configured, so the first episode should generate without you editing anything. Requirements are Python 3.10 or newer, ffmpeg (the README suggests brew install ffmpeg on macOS), and a Fish Audio account.

After the run, look in ~/.personalized-podcast/episodes/ for the MP3 and ~/.personalized-podcast/scripts_output/ for the JSON script. Reading the script before listening is the fastest way to judge whether your PROMPT.md edits are producing the show you wanted.

Customizing hosts, voices and show format

The configuration surface is small and file-based. Show personality is set through show_name and tone in ~/.personalized-podcast/config.yaml. The README points at config/config.example.yaml as the starting point with pre-picked voices, and examples/sample_config.yaml exists in the repository as a second reference. Voice choice is manual: browse fish.audio/discovery, pick voices, and copy their reference IDs into the config.

Format changes are a different lever. PROMPT.md controls how the hosts behave, the show structure and the writing style. The README lists debate, eavesdrop, interview, solo narrator and news roundup as formats you can build by editing that file. This is the trade-off of the design: you get full control, but control means editing prompts and YAML rather than picking from a dropdown. If you do not want to write prompt text, the default two-host conversation is what you get.

One practical note on the eavesdrop format. It is the same pipeline as everything else; the difference is entirely in the prompt and in what content you feed it. There is no separate analysis model.

Where it breaks: free tier limits, agent lock-in and the missing licence

The clearest constraint is the TTS dependency. Every episode goes through Fish Audio, and the README's own requirement list names a Fish Audio account with a free tier. There is no documented local TTS fallback, so if the free tier caps your usage or the API changes, the pipeline stops. The README does not document rate limits, character quotas or what happens when a request fails mid-episode.

Second, this is agent-shaped software. It assumes a coding agent that supports skills and that resolves a /podcast command. The README names three agents but only gives an install path for one. There is no CLI you can run standalone, no server, no web interface. If you want a browser tool that a non-technical colleague can use, this is the wrong project.

Third, the repository has no LICENSE file at the top level, and no licence is stated. That is a real gap for anyone planning to publish episodes commercially or fork the code into a product. Treat the licence question as unresolved until you check the repository yourself.

Finally, the RSS path is the least specified part. The README says you can ask the agent to set up a feed and that it creates a GitHub Pages feed, with publish.py and templates/feed_template.xml in the layout. The README does not document rollback, feed validation, or what happens to already-published episodes when you change show_name.

How it differs from NotebookLM and hosted podcast generators

The obvious comparison is NotebookLM's Audio Overview, which the README itself invokes with the phrase NotebookLM-style. The difference is where control sits. NotebookLM generates a conversation from your sources with a fixed format and voices you do not choose. Here the script prompt, host roles, voices, tone and episode length are all files you edit, and the README frames that as the whole point.

The second difference is delivery. Hosted generators give you a web player. This one writes an MP3 to a local directory and, if you ask for it, publishes an RSS feed on GitHub Pages so episodes land in Apple Podcasts, Overcast, Pocket Casts, Snipd or Spotify. No new app is required, which is the README's stated reason for the RSS route.

The third difference is the execution model. Everything runs locally through your coding agent: no separate backend, no hosted service, no subscription beyond your agent and the Fish Audio key. That is a genuine architectural difference from a SaaS podcast generator, and it is also why the setup is more involved than pasting a link into a website.

Maintenance, upgrade cost and licence status

The last push to the default branch was on 2026-04-08, so the repository has not been touched in roughly five months. The README does not describe a versioning scheme, a changelog or a migration path, and no releases were retrieved. That means upgrades are effectively git pulls, and your local edits to PROMPT.md and config.yaml are the things most likely to conflict.

The dependency surface is small but sharp-edged. Python 3.10+, ffmpeg, pydub, and whatever the bootstrap script installs on first run. ffmpeg is the one that breaks silently across machines, and the README only gives the macOS install command. If you run this on Linux or Windows, you are translating the setup yourself.

The licence is unknown, and the top-level entries include no LICENSE file. Without a stated licence, you cannot assume the right to redistribute the code or the generated feed template. If you plan to publish episodes publicly or embed the skill in a product, resolve that before you build on it. This is not legal advice; it is a note that the repository does not answer the question.

Editorial conclusion

Adopt it if you already run a skill-capable coding agent and want a two-host episode from a file or URL without a hosted service, and if you accept that a free Fish Audio key is a hard dependency. Do not adopt it if you want a web dashboard, a mobile app, or anything that runs without an agent in the loop. Before committing, verify three things in the repository: whether a LICENSE file exists, whether your agent actually resolves the /podcast skill path, and whether SKILL.md documents the RSS publishing step well enough for you to debug it.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. zarazhangrui/personalized-podcast on GitHub