---

name: speak description: Automatically announces plans, issues, and summaries out loud using TTS. Use this skill PROACTIVELY after completing major tasks like finalizing a plan, resolving an issue, or generating a summary. Each project gets a unique voice so users can identify which project is speaking from another room. Providers fallback in order (google, openai, elevenlabs, say) on rate limits.

Speak

Announce plans, issues, and summaries aloud using project-specific voices. Triggered automatically after major milestones.

When to Announce

Announce automatically after:

• Planning complete - When a plan/todo list is finalized
• Issue resolved - When a bug fix or error is resolved
• Summary generated - When completing a sprint or major task

Configuration

Store config at .claude/tts-config.json in the project root:

Copy{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": [],
  "voices": {
    "planning": { "provider": "google", "voice": "Kore", "style": "calm" },
    "issue": { "provider": "google", "voice": "Aoede", "style": "urgent" },
    "summary": { "provider": "google", "voice": "Charon", "style": "satisfied" }
  },
  "assigned_at": "2025-01-15T10:30:00Z"
}

On first use in a new project, auto-generate config by selecting unused voices from the voice pool (see references/voice-pools.json).

Note: say (macOS) requires no API key and should always work as final fallback.

Workflow

1. Detect message type - planning, issue, or summary
2. Load config - Read .claude/tts-config.json or create if missing
3. Select provider - Use first provider from provider_order not in unavailable_providers
4. Transform text - Convert to speech-friendly format (see below)
5. Speak - Call appropriate TTS tool with configured voice
6. Handle failures - See error handling below

Error Handling

When a TTS call fails, check the error type:

Critical: On auth/config errors, immediately update .claude/tts-config.json to add the provider to unavailable_providers. This persists across sessions and prevents wasted attempts.

Example after Google fails due to missing API key:

Copy{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": ["google"],
  ...
}

The agent will now skip Google and start with OpenAI on next announcement.

Text Transformation

Convert verbose output to conversational speech:

Target length: ~15-30 seconds of speech (roughly 50-100 words)

Tone by type:

• Planning: "Here's the plan..." (forward-looking, organized)
• Issue: "Found a problem..." (alert but calm)
• Summary: "All done..." (satisfied, accomplished)

TTS Tools

google_tts (preferred)

Copymcp__mcp-tts__google_tts
- text: string (required)
- voice: string (default: "Kore")
- model: string (default: "gemini-2.5-flash-preview-tts")

Voices: Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Puck, Pulcherrima, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi

openai_tts (fallback 1)

Copymcp__mcp-tts__openai_tts
- text: string (required)
- voice: string (default: "alloy") - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse
- model: string (default: "gpt-4o-mini-tts")
- speed: number (0.25-4.0, default: 1.0)
- instructions: string (voice modulation hints)

elevenlabs_tts (fallback 2)

Copymcp__mcp-tts__elevenlabs_tts
- text: string (required)

say_tts (fallback 3 - local/free)

Copymcp__mcp-tts__say_tts
- text: string (required)
- voice: string (e.g., "Alex", "Samantha", "Victoria")
- rate: integer (50-500 words/min, default: 200)

Auto-Assignment

When creating config for a new project:

1. Read references/voice-pools.json for available voices
2. Check ~/.claude/tts-unavailable.json for globally unavailable providers (shared across projects)
3. Scan ~/.claude/tts-assignments.json for voices already assigned to other projects
4. Select 3 unused voices (one per message type) from first available provider
5. If all voices used, cycle back with provider variation
6. Save assignment to both project config and global assignments file

When a provider is marked unavailable in any project, also update ~/.claude/tts-unavailable.json:

Copy{
  "unavailable": ["google", "elevenlabs"],
  "updated_at": "2025-01-15T10:30:00Z"
}

This prevents new projects from attempting providers known to be unconfigured.

Examples

Planning (after TodoWrite with multiple items):

"Here's the plan for the authentication feature. First, I'll create the login component. Then add session management. Finally, write the tests. Three tasks total."

Issue (after fixing an error):

"Found and fixed an issue. The rate limiter wasn't catching timeout errors. Added a try-catch block in the handler. Tests are passing now."

Summary (after completing a feature):

"All done with the authentication system. Added login, logout, and session management. Created five new files and updated the main router. Ready for review."