voice-integration

name	voice-integration
description	This skill should be used when the user asks about "[VOICE] tag", "voice notification", "TTS settings", "speech rate", "voice language", "text-to-speech", or mentions CVI configuration. Also use this skill when completing tasks to provide voice notification summaries.
version	1.0.0

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.