Agent skill

read-aloud

Generate a standalone HTML reader with Kokoro TTS audio and word-synced highlighting from any markdown file. Use when user wants to listen to an essay, proofread by ear, or create an audio reader.

View SKILL.md on GitHub Repository
Stars 25
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/leegonzales/AISkills/tree/main/ReadAloud/read-aloud

SKILL.md

Read Aloud

Generate a standalone HTML reader with high-quality TTS audio and real-time word highlighting from any markdown file.

When to Use

Invoke when user:

  • Asks to "read this aloud" or "generate audio" for a markdown file
  • Wants to proofread by ear (catch awkward phrasing, rhythm issues)
  • Needs a shareable audio reader (single HTML file, no server needed)
  • Uses /read-aloud command

Prerequisites

  • macOS with Apple Silicon (M1+)
  • Python 3.13+ (required for MLX)
  • ffmpeg (for MP3 compression)

Core Command

bash
SKILL_DIR="path/to/read-aloud"
$SKILL_DIR/scripts/read-aloud.sh <markdown-file> [options]

First run auto-installs dependencies to ~/.read-aloud/venv/.

Options

Flag Default Description
--voice af_heart Kokoro voice variant
--speed 1.0 Speech rate (0.5-2.0)
--output-dir ~/.read-aloud/output/<slug>/ Custom output directory
--strip-sections (none) Comma-separated heading names to skip
--no-open (off) Don't open browser after generation

Pipeline

Three-stage process (~2-5 min for a typical essay):

  1. Generate Audio — Kokoro TTS produces per-paragraph WAV chunks
  2. Align Words — Whisper transcribes each chunk for drift-free word timestamps
  3. Build Reader — Assembles standalone HTML with embedded MP3 + word sync

Output

Single reader.html file with:

  • Base64-embedded MP3 audio (fully standalone, no server needed)
  • Per-word highlighting synced to audio playback
  • Sticky playback controls (play/pause, stop, speed, progress bar)
  • Keyboard shortcuts (Space, Escape, Arrow keys)
  • Click any word to seek

Available Voices

Voice Description
af_heart American female, warm (default)
af_bella American female, clear
am_adam American male, deep
am_michael American male, neutral
bf_emma British female, elegant
bm_george British male, distinguished

Examples

bash
# Basic usage — generates reader at ~/.read-aloud/output/my-essay/
$SKILL_DIR/scripts/read-aloud.sh ~/Documents/my-essay.md

# Custom voice and speed
$SKILL_DIR/scripts/read-aloud.sh post.md --voice bm_george --speed 1.1

# Output to specific directory
$SKILL_DIR/scripts/read-aloud.sh draft.md --output-dir ./preview/

# Strip specific sections before generating
$SKILL_DIR/scripts/read-aloud.sh post.md --strip-sections "Brief,Links & Resources"

References

  • Load references/voice-guide.md for detailed voice descriptions and speed tuning
  • Load references/examples.md for worked examples with expected output
  • Load references/troubleshooting.md when errors occur

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

leegonzales/AISkills

context-continuity

High-fidelity context transfer protocol for moving conversations between AI agents. Preserves decision tempo, open loops, and critical context with graceful degradation. Use when the user says "transfer," "handoff," "continue this in another chat," or needs to work around context window limits. Produces structured artifacts (Minimal ~200 words, Full ~1000 words). DO NOT trigger on simple "summarize our conversation" requests—only when transfer intent is explicit.

25 5
Explore
leegonzales/AISkills

codex-peer-review

25 5
Explore
leegonzales/AISkills

silicon-doppelganger

Build psychometrically accurate personal proxy agents for the PAIRL Conductor system. Extracts personality, decision heuristics, and values into portable schemas that enable AI agents to negotiate, filter, and act on a principal's behalf.

25 5
Explore
leegonzales/AISkills

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements. Dispatches three independent reviewers in parallel.

25 5
Explore
leegonzales/AISkills

fabric-patterns

Run danielmiessler/fabric CLI patterns for content analysis, extraction, summarization, writing, security analysis, and more. Use when user asks to "use fabric," "run a pattern," "extract wisdom," "summarize with fabric," or when piping content through AI patterns would be more effective than inline processing. Triggers include "fabric," "pattern," "extract wisdom," "summarize this article," "analyze this threat report," or any reference to a specific fabric pattern name.

25 5
Explore
leegonzales/AISkills

moltbook-enclave

Secure, air-gapped interface for Moltbook (social network for AI agents). Isolates untrusted external content from your main agent's memory and context.

25 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results