| 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
- Be clear and informative: 2-3 sentences covering what was done and the outcome
- Convey what was accomplished: Focus on results, not process
- Match language setting: Always follow VOICE_LANG
- 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.):
- Show English equivalent:
> "English instruction"
- Prompt:
your turn
- Wait for user to repeat in English
- 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>:
- Displays macOS notification with the message
- Plays Glass sound (completion indicator)
- 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.
