--- slug: "personalized-podcast" source_type: "skill_md" source_url: "https://cdn.jsdelivr.net/gh/zarazhangrui/personalized-podcast@main/SKILL.md" repo: "https://github.com/zarazhangrui/personalized-podcast" source_file: "SKILL.md" branch: "main" --- --- name: podcast description: Generate a podcast episode from content you provide. Paste text, point to local files, or describe a topic. Two AI hosts discuss it in a natural conversation. Listen locally or in your favorite podcast app via RSS. --- ## Path convention Throughout this file: - `SKILL_DIR` = the directory where this SKILL.md file lives (the skill's install location) - `DATA_DIR` = `~/.personalized-podcast` (where user data, config, and episodes are stored) Resolve these to absolute paths before running any commands. # Personalized Podcast When the user invokes this skill, start by introducing it: > "This skill turns any content into a podcast episode with two AI hosts who discuss it in a natural, conversational style. Think NotebookLM, but you control everything: the script prompt, the hosts' voices, the show format. > > You can use it to: > > - **Listen to anything on the go.** Paste an article, point to a file, drop a URL. Instead of reading, you get two people breaking it down while you walk, commute, or cook. > - **Understand yourself from the outside.** Feed it personal content like meeting transcripts, your resume, or journal entries, and have the hosts share their impressions of you. It's genuinely illuminating. > - **Create your own show.** Set up an RSS feed and new episodes show up in the podcast app you already use (Apple Podcasts, Spotify, Overcast, Snipd). No new app to download. > > Let's get started. What content do you want to turn into a podcast?" If the user already provided content with their `/podcast` command, skip the question and go straight to setup check. --- ## First-time setup If `DATA_DIR/config.yaml` does not exist, run through this setup BEFORE generating. Do each step yourself - don't ask the user to run commands. ### Step 1: Install dependencies ```bash mkdir -p DATA_DIR/{scripts_output,episodes,logs} python3 -m venv DATA_DIR/venv DATA_DIR/venv/bin/pip install httpx pydub pyyaml python-dotenv jinja2 audioop-lts ``` Check ffmpeg is installed: ```bash ffmpeg -version ``` If not found, install it: `brew install ffmpeg` (macOS) or `sudo apt install ffmpeg` (Linux). ### Step 2: Create config with default voices ```bash cp SKILL_DIR/config/config.example.yaml DATA_DIR/config.yaml ``` The config comes with two pre-picked voices that work out of the box. No voice selection needed for first use. ### Step 3: Get Fish Audio API key Tell the user: > "To turn your script into audio, this skill uses Fish Audio for text-to-speech. They have a free tier with 2 million+ voices. You just need an API key: > > 1. Go to https://fish.audio and create a free account > 2. Go to https://fish.audio/app/api-keys/ and create an API key" Then create the .env file and open it: ```bash echo "FISH_API_KEY=your_key_here" > DATA_DIR/.env open DATA_DIR/.env ``` Tell them: "Paste your Fish Audio API key in this file, replacing 'your_key_here'. Save and close." IMPORTANT: Never ask the user to paste API keys in the chat. Always use the .env file. ### Step 4: Done Tell the user: > "You're all set! The default show has two hosts - Alex (curious, energetic) and Sam (analytical, witty) - with voices pre-configured. Let's generate your first episode." Then proceed to generate the episode. Do NOT set up RSS or GitHub Pages during first-time setup. That's optional and comes later. --- ## Generating an episode ### Step 1: Read the content Read all the content the user provided. If they pointed to files, read them with the Read tool. If they pasted a URL, fetch it. Combine everything into your understanding of the source material. ### Step 2: Write the podcast script Read the prompt file at `SKILL_DIR/PROMPT.md` for the hosts, style, structure, and output format. Follow those instructions to write the script. If the user included custom instructions in their `/podcast` message (e.g., "make it a debate" or "hosts should eavesdrop on my conversation"), incorporate those. The user's inline instructions override PROMPT.md for that episode. Save the script as a JSON array using the Write tool to: `DATA_DIR/scripts_output/YYYY-MM-DD.json` (use today's date). If a file for today already exists, append a number (e.g., `2026-04-05-2.json`). ### Step 3: Generate audio Tell the user: "Script written. Now generating audio - this takes about a minute depending on episode length." Run the speak script: ```bash DATA_DIR/venv/bin/python SKILL_DIR/scripts/speak.py --script ``` This outputs the path to the generated MP3 file. ### Step 4: Play the audio IMMEDIATELY open the audio file for the user: ```bash open ``` On Linux use `xdg-open` instead of `open`. ### Step 5: Post-generation tips After the audio plays, tell the user: > "Your episode is ready! A few things you can do from here: > > **Try different show formats.** The default is two hosts chatting, but you can do anything. Just describe it when you run `/podcast`: > > - "/podcast make it a debate about this article" > - "/podcast hosts should eavesdrop on my conversation and share their impressions of me" > - "/podcast interview format, one host asks questions and the other is the expert" > - "/podcast solo narrator, walk me through this research paper" > - "/podcast news roundup, read each tweet aloud then discuss" > > Or edit `PROMPT.md` to permanently change your show's format. > > **Pick your own voices.** The default voices are solid, but Fish Audio has 2 million+ to choose from. Browse https://fish.audio/discovery, find two you like, and update the voice IDs in `DATA_DIR/config.yaml`. > > **Listen in your podcast app.** Want new episodes delivered to Apple Podcasts, Spotify, Overcast, or Snipd automatically? Just ask me to set up an RSS feed for you - takes about a minute." Only show these tips the FIRST time, or if the user asks about customization. --- ## RSS feed setup (only when user asks) When the user wants to set up an RSS feed, explain why it's useful: > "This creates a personal podcast feed that works in any podcast app. Once it's set up, every time you generate a new episode, it gets published to the feed and shows up where you already listen to podcasts. No new app needed." Then walk them through these steps: ### 1. Create a public GitHub repo Ask for their GitHub username, then: ```bash gh repo create USERNAME/podcast-feed --public --description "Personal podcast feed" ``` ### 2. Enable GitHub Pages ```bash cd /tmp && mkdir podcast-feed && cd podcast-feed && git init echo '[]' > episodes.json ``` Generate an initial empty feed.xml using the template, then push and enable GitHub Pages: ```bash gh api repos/USERNAME/podcast-feed/pages -X POST --input - << 'EOF' {"source":{"branch":"main","path":"/"},"build_type":"legacy"} EOF ``` ### 3. Update config Update `DATA_DIR/config.yaml` with: ```yaml publish: github_repo: "USERNAME/podcast-feed" base_url: "https://USERNAME.github.io/podcast-feed" ``` ### 4. Subscribe in a podcast app Tell the user their feed URL and give them the steps for their preferred app: | App | How to subscribe | | ----------------------- | ------------------------------------------------------ | | Apple Podcasts (Mac) | Menu bar: File > Add a Show by URL | | Apple Podcasts (iPhone) | Library > Edit (top right) > Add a Show by URL | | Overcast | "+" (top right) > Add URL | | Pocket Casts | Discover tab > paste URL in search bar > Subscribe | | Castro | Search tab > paste URL in search bar > Add Podcast | | Snipd | Home > Podcasts > three-dot menu (top right) > Add RSS | | Spotify | See Spotify instructions below | Feed URL: `https://USERNAME.github.io/podcast-feed/feed.xml` **Spotify setup (one-time, takes 24-48 hours for approval):** IMPORTANT: Before proceeding, warn the user: "Heads up - submitting to Spotify makes your podcast **public**. Anyone on Spotify can find and listen to it. The other apps above are private - only people you share the RSS URL with can find your show. Want to proceed with Spotify?" If they want to proceed: 1. Make sure `owner_email` is set in config.yaml. If not, ask for their email and add it. 2. Go to [podcasters.spotify.com](https://podcasters.spotify.com) and sign in 3. Click "Add existing podcast" 4. Paste the feed URL 5. Spotify sends a verification email - click to verify 6. The show appears on Spotify within 24-48 hours ### 5. Publish episodes After the RSS feed is set up, future episodes can be published with: ```bash DATA_DIR/venv/bin/python SKILL_DIR/scripts/publish.py --mp3 --title "" --description "<description>" ``` --- ## Troubleshooting - **"API key not found"** - Check DATA_DIR/.env has a valid FISH_API_KEY - **"ffmpeg not installed"** - Run: `brew install ffmpeg` (macOS) or `sudo apt install ffmpeg` (Linux) - **"gh not authenticated"** - Run: `gh auth login` - **TTS quota exceeded** - Fish Audio free tier has monthly limits. Wait for reset or upgrade your plan.