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

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:

ffmpeg -version

If not found, install it: brew install ffmpeg (macOS) or sudo apt install ffmpeg (Linux).

Step 2: Create config with default voices

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:

Go to https://fish.audio and create a free account

Go to https://fish.audio/app/api-keys/ and create an API key"

Then create the .env file and open it:

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:

DATA_DIR/venv/bin/python SKILL_DIR/scripts/speak.py --script <path_to_script.json>

This outputs the path to the generated MP3 file.

Step 4: Play the audio

IMMEDIATELY open the audio file for the user:

open <path_to_mp3>

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:

gh repo create USERNAME/podcast-feed --public --description "Personal podcast feed"

2. Enable GitHub Pages

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:

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:

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:

Make sure owner_email is set in config.yaml. If not, ask for their email and add it.
Go to podcasters.spotify.com and sign in
Click "Add existing podcast"
Paste the feed URL
Spotify sends a verification email - click to verify
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:

DATA_DIR/venv/bin/python SKILL_DIR/scripts/publish.py --mp3 <path_to_mp3> --title "<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.