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.