The gencast skill automates the transformation of static documents into engaging, conversational podcasts. By utilizing the gencast CLI, it converts Markdown and PDF files into high-quality audio with customizable styles—such as educational, interview, or debate—and tailored audience levels. This tool is ideal for creators and educators looking to repurpose text-based content into accessible, multi-modal audio formats for on-the-go consumption.

When should I use gencast?

gencast is useful in the following scenarios: • Educational Repurposing: Convert lecture notes, study guides, or textbooks into educational podcasts to facilitate auditory learning for students. • Technical Documentation: Transform complex API docs or technical manuals into professional interview-style audio for easier developer onboarding and knowledge sharing. • Academic Research: Turn dense research papers into conversational debates or academic discussions to make complex findings more digestible for a wider audience. • Content Marketing: Repurpose blog posts, whitepapers, or company reports into casual, host-driven audio versions for social media and multi-channel distribution. • Accessibility Enhancement: Provide an audio alternative for text-heavy documents, ensuring content is accessible to users with visual impairments or those who prefer listening.

name	gencast
description	Auto-invoke gencast to generate podcasts from documents when user mentions podcast, audio, or dialogue generation
allowed-tools	Bash, Read

gencast - Podcast Generation from Documents

Generate conversational podcasts from documents using gencast CLI. ALWAYS uses --minimal flag to reduce context usage.

When to Use This Skill

Auto-invoke when the user mentions:

"podcast", "generate podcast", "convert to podcast"
"audio", "convert to audio", "make an audio version"
"dialogue", "conversation", "generate dialogue"
"lecture recording", "educational audio"
Document conversion to spoken format

How to Use

CRITICAL: ALWAYS include --minimal flag in every gencast command to avoid context bloat.

Basic Pattern

gencast <input-file> --minimal -o <output.mp3>

With Style and Audience

gencast document.md --minimal --style educational --audience general -o podcast.mp3

With Planning for Comprehensive Coverage

gencast document.md --minimal --with-planning --save-plan -o podcast.mp3

Core Workflows

1. Check gencast Installation

Before running gencast, verify it's installed:

which gencast

If not found, inform the user:

gencast is not installed. Install with: pip install gencast

2. Validate Input File

Check the input file exists before running:

if [[ -f "document.md" ]]; then
  gencast document.md --minimal -o podcast.mp3
else
  echo "[ERROR] Input file not found: document.md"
fi

3. Generate Basic Podcast

Default style (educational) and audience (general):

gencast lecture.md --minimal -o lecture_podcast.mp3

4. Generate with Custom Style and Audience

# Interview style for technical audience
gencast chapter.md --minimal --style interview --audience technical -o chapter.mp3

# Casual style for beginners
gencast intro.md --minimal --style casual --audience beginner -o intro.mp3

# Debate style for academic audience
gencast paper.md --minimal --style debate --audience academic -o paper.mp3

5. Generate with Planning

For comprehensive coverage of complex documents:

gencast complex_doc.md --minimal --with-planning --save-dialogue --save-plan -o output.mp3

This creates:

output.mp3 - The podcast audio
output_plan.txt - The planning document
output_dialogue.txt - The generated dialogue script

6. Multiple Input Files

Gencast concatenates multiple inputs:

gencast chapter1.md chapter2.md chapter3.md --minimal -o full_course.mp3

7. Custom Voice Selection

gencast doc.md --minimal --host1-voice nova --host2-voice echo -o podcast.mp3

Available voices: alloy, echo, fable, onyx, nova, shimmer (see references/voices.md)

Minimal Output Format

With --minimal flag, gencast only shows:

Milestones (plan generation, dialogue generation, audio synthesis)
Final output path
Duration

No spinners or progress bars - keeps context clean.

Progress Reporting

After running gencast, report to the user:

[OK] Podcast generated

Output: podcast.mp3
Duration: 5m 32s
Style: educational
Audience: general

Additional files:
- podcast_dialogue.txt (if --save-dialogue used)
- podcast_plan.txt (if --save-plan used)

Edge Cases

PDF Input

PDFs require MISTRAL_API_KEY environment variable:

if [[ ! -z "$MISTRAL_API_KEY" ]]; then
  gencast document.pdf --minimal -o podcast.mp3
else
  echo "[WARN] PDF input requires MISTRAL_API_KEY environment variable"
  echo "Set with: export MISTRAL_API_KEY=your_key"
fi

Output File Exists

Gencast will overwrite existing files. Warn the user if needed:

if [[ -f "podcast.mp3" ]]; then
  echo "[WARN] Output file podcast.mp3 already exists and will be overwritten"
fi
gencast doc.md --minimal -o podcast.mp3

No Input Files

if [[ $# -eq 0 ]]; then
  echo "[ERROR] No input files provided"
  echo "Usage: gencast <input-files> [options]"
  exit 1
fi

Best Practices

Always use --minimal - Required for context management
Validate inputs first - Check files exist before running
Provide clear output paths - Use descriptive names (lecture_01.mp3, not output.mp3)
Save dialogue for review - Use --save-dialogue for complex topics
Use planning for long documents - --with-planning ensures comprehensive coverage
Match style to content - educational for lectures, interview for Q&A, debate for contrasting views
Consider audience level - beginner vs technical vs academic affects language complexity

Reference Documentation

Voice Options: references/voices.md (6 voices with character descriptions)
Styles and Audiences: references/styles.md (4 styles x 4 audiences matrix)

User Commands

For explicit invocation, users can use:

/gencast:podcast <input> [options] - Full control over all options
/gencast:plan <input> - Generate planning document only (no audio)

Examples

Example 1: Simple Lecture Podcast

gencast CS101_lecture_notes.md --minimal -o CS101_lecture.mp3

Example 2: Technical Interview Style

gencast API_documentation.md --minimal --style interview --audience technical --save-dialogue -o API_podcast.mp3

Example 3: Beginner-Friendly Casual Style

gencast intro_to_programming.md --minimal --style casual --audience beginner -o intro_podcast.mp3

Example 4: Academic Debate

gencast research_paper.md --minimal --style debate --audience academic --with-planning --save-plan -o research_podcast.mp3

Example 5: Multi-Chapter Course

gencast week1.md week2.md week3.md --minimal --style educational --audience general -o course_weeks_1-3.mp3

gencast

When & Why to Use This Skill

Use Cases