Read Aloud Skill

Read any markdown or text file aloud using Kokoro TTS. Zero config — auto-installs on first use, no API keys, runs entirely locally.

Install

npx skills add agairola/life-skills --skill read-aloud

When to Use

Trigger this skill when the user:

• Asks to read a file aloud or "read this to me"
• Wants text-to-speech for a document
• Says "listen to this", "play this", "say this"
• Wants to convert text or markdown to audio
• Mentions TTS or text-to-speech
• Wants to review content by listening instead of reading
• Asks for an audio version of a document

Prerequisites

• uv — brew install uv (macOS) or pip install uv (all platforms)
• Kokoro TTS — auto-installed on first run via uv tool install kokoro-tts
• Models — auto-downloaded on first run (~335MB total, stored in ~/.config/read-aloud/models/)
• API keys — not needed. Everything runs locally.
• Dependencies — declared inline (PEP 723), installed automatically by uv run.

Setup Status

!command -v uv > /dev/null 2>&1 && echo "uv: installed" || echo "uv: NOT INSTALLED — run: brew install uv" !command -v kokoro-tts > /dev/null 2>&1 && echo "kokoro-tts: installed" || echo "kokoro-tts: not installed (will auto-install on first use)" !test -f ~/.config/read-aloud/models/kokoro-v1.0.onnx && echo "models: downloaded" || echo "models: not yet downloaded (will auto-download on first use, ~335MB)"

Command Template

uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" <INPUT> [OPTIONS]

Options

Flag	Values	Default	Purpose
input	file path or -	required	Path to .md or .txt file, or - for stdin
--voice	see voice list	af_heart	Voice to use
--speed	float	1.0	Speech speed (0.5 = slow, 1.5 = fast)
--output	file path	(plays audio)	Save to .wav file instead of playing
--max-lines	integer	0 (all)	Only read the first N lines
--max-time	integer	0 (no limit)	Stop playback after N seconds
--no-play	flag	off	Generate .wav without playing (use with --output)
--list-voices	flag	—	Print available voices as JSON and exit

Only parse stdout (JSON). Stderr contains progress messages and diagnostics only.

Common Commands

# Read a markdown file aloud
uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" /path/to/document.md

# Use a male voice
uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" /path/to/notes.md --voice am_adam

# Read faster
uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" /path/to/doc.md --speed 1.3

# Save to file instead of playing
uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" /path/to/doc.md --output ~/Desktop/speech.wav

# Read just the first 10 lines
uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" /path/to/doc.md --max-lines 10

# Stop after 60 seconds
uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" /path/to/doc.md --max-time 60

# Read from stdin
echo "Hello, this is a test" | uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" -

# List available voices
uv run "${CLAUDE_SKILL_DIR}/scripts/read_aloud.py" --list-voices

Presenting Results

After Streaming Audio

The default mode streams audio — playback starts within seconds even for large files. Confirm and offer follow-up:

Reading "document.md" aloud (Heart voice, 1.0x speed).

Want me to:
- Read it again with a different voice?
- Save it as a .wav file? (use --output)
- Read a specific section?

After Saving to File

When the user explicitly asks to save audio (using --output):

Saved audio to ~/Desktop/speech.wav (Heart voice, 1.0x speed, ~45 seconds).

First Run

On first use, the setup takes 1-2 minutes (installing kokoro-tts + downloading ~335MB of models). Let the user know:

Setting up text-to-speech for the first time (downloading voice models, ~335MB). This only happens once.

After the first run, subsequent reads start in seconds.

Handling Edge Cases

• First run (no kokoro-tts, no models): The script auto-installs everything. Tell the user it's a one-time setup taking 1-2 minutes.
• Large files: Kokoro processes in chunks. For very large files (>50KB of text), warn the user it may take a moment to generate.
• No audio player (headless/remote): The script auto-saves to a .wav file in the current directory and returns the path. Tell the user where the file is.
• Unsupported file types: The script reads any text file. For non-text files, suggest converting first.
• Empty content: If markdown stripping removes all content (e.g., a file with only code blocks), the script returns an error. Suggest the user try with a different file or pass specific text via stdin.
• Chat platforms (Telegram, WhatsApp, etc.): Audio playback only works in terminal environments. On chat platforms, use --output to save the file and tell the user where to find it.

Voice Reference

American English

Voice ID	Name	Gender
af_alloy	Alloy	Female
af_aoede	Aoede	Female
af_bella	Bella	Female
af_heart	Heart (default)	Female
af_jessica	Jessica	Female
af_kore	Kore	Female
af_nicole	Nicole	Female
af_nova	Nova	Female
af_river	River	Female
af_sarah	Sarah	Female
af_sky	Sky	Female
am_adam	Adam	Male
am_michael	Michael	Male

British English

Voice ID	Name	Gender
bf_emma	Emma	Female
bf_isabella	Isabella	Female
bm_george	George	Male
bm_lewis	Lewis	Male