voice-integration

Voice Integration Guide

This skill provides guidance on using CVI (Claude Voice Integration) for voice notifications in Claude Code.

MANDATORY: Task Completion Pattern

Every task completion MUST follow this exact pattern:

[detailed task explanation...]

<use Skill tool: skill="cvi:speak" args="2-3 sentences explaining what was done">

CRITICAL: Use Skill tool, NOT text

• ❌ Do NOT write /cvi:speak xxx as text
• ✅ Use Skill tool with skill="cvi:speak" and args="your message"
• ❌ Do NOT use [VOICE] tag - it's deprecated

Why Skill tool only (no [VOICE] tag)?

• The Skill result (Speaking: ...) serves as the visible summary
• Single source of truth - no duplication or mismatch
• Skill tool /cvi:speak: Triggers macOS notification + Glass sound + voice

If you forget to use Skill tool:

• ❌ Stop hook will BLOCK your stop request
• ❌ No voice notification will play
• ❌ User will not hear task completion

Language Configuration

The summary language is controlled by VOICE_LANG in ~/.cvi/config:

VOICE_LANG	Summary Language
ja	Japanese: args="タスクが完了しました。..."
en	English: args="Task completed successfully..."

Important: Always check ~/.cvi/config before calling /cvi:speak.

When to Use /cvi:speak

✅ Always use when:

• File editing/creation completed
• Test execution completed
• Command execution completed
• Research/investigation completed
• Error resolution completed
• Any task completion

❌ Exception (no notification needed):

• When asking user questions/confirmations

Configuration Commands

Command	Purpose
/cvi	Enable/disable voice notifications
/cvi:speed	Adjust speech rate (wpm)
/cvi:lang	Set [VOICE] tag language (ja/en)
/cvi:voice	Select voice for each language
/cvi:auto	Enable language auto-detection
/cvi:check	Diagnose setup issues
/cvi:practice	Toggle English practice mode
/cvi:speak	Directly speak text (bypasses Stop hook timing)

Best Practices

1. Be clear and informative: 2-3 sentences covering what was done and the outcome
2. Convey what was accomplished: Focus on results, not process
3. Match language setting: Always follow VOICE_LANG
4. Avoid technical jargon: Use clear, simple language

Examples

English mode (VOICE_LANG=en):

<use Skill tool: skill="cvi:speak" args="Updated 3 configuration files. All tests passing.">

Japanese mode (VOICE_LANG=ja):

<use Skill tool: skill="cvi:speak" args="設定ファイルを3つ更新しました。テストは全て成功しています。">

English Practice Mode

When ENGLISH_PRACTICE=on in ~/.cvi/config:

If user input contains non-ASCII characters (Japanese, etc.):

1. Show English equivalent: > "English instruction"
2. Prompt: your turn
3. Wait for user to repeat in English
4. Then execute the instruction

Important clarifications:

• This mode affects USER prompts only, not Claude's response language
• Claude responds in the language set by Claude Code's language setting
• If user's English is unclear, ask for clarification before acting
• When user asks "How do you say X in English?", answer the question

Voice Notification with /cvi:speak

For task completion, use the Skill tool to call /cvi:speak:

[detailed task explanation...]

<use Skill tool: skill="cvi:speak" args="2-3 sentence summary">

CRITICAL: Do NOT write /cvi:speak as text. You MUST use the Skill tool.

This approach:

• Single source of truth: No [VOICE] tag duplication
• Visible summary: The Skill result (Speaking: ...) is shown to user
• Uses CVI settings: Language, voice, and speed settings are respected
• Includes all notifications: macOS notification, Glass sound, and voice

Important: The Stop hook will BLOCK if /cvi:speak is not called via Skill tool.

What /cvi:speak Does

When you call /cvi:speak <message>:

1. Displays macOS notification with the message
2. Plays Glass sound (completion indicator)
3. Reads the message aloud using configured voice settings

All three happen together, providing a complete notification experience.

Fallback Behavior

If /cvi:speak is not called, the Stop hook will block and remind you to call it. Always use the Skill tool for task completion notifications.