ha-voice — Claude Code skill: what it does, how to install
ha-voice guides Home Assistant Assist setup: voice pipelines, wake words, custom sentence intents, and ESP32 voice satellites.
MIT 226 installs ★ 19 updated 2026-04-20
npx skills add nodnarbnitram/claude-code-extensions --skill ha-voice -a claude-codeWhat ha-voice does
The skill provides patterns and rules for Home Assistant Assist voice pipelines. It guides your coding agent in connecting speech-to-text engines like Faster Whisper and text-to-speech tools like Piper inside configuration.yaml.
Intent creation rules mandate placing custom sentence files in custom_sentences/ with a version: 1 header. Instead of hardcoding entity IDs into command patterns, configurations must use dynamic slot lists like {name:list}. Local Piper voice models require over 100 MB of storage each, which you need to allocate before enabling the engine.
The documentation also covers hardware voice satellites powered by ESPHome and ESP32-S3 boards. It provides I2S pin mappings for INMP441 microphones and MAX98357A speaker amplifiers.
What it helps with
- configure Home Assistant Assist pipelines with Faster Whisper and Piper
- define custom voice sentences and slot lists in
custom_sentences/ - set up openWakeWord or Porcupine wake word detection
- write ESPHome configs for ESP32-S3 satellites with I2S audio
Example prompts for the agent
- Set up a local Assist voice pipeline using Piper and Faster Whisper
- Create custom sentence intents in
custom_sentences/for room lighting - Generate an ESPHome voice assistant config for an ESP32-S3 board with an INMP441 mic
How to install ha-voice
1Skills CLI (Vercel)
npx skills add nodnarbnitram/claude-code-extensions --skill ha-voice -a claude-code2Manually: put the files in place
~/.claude/skills/ha-voice/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ha-voice/
1Skills CLI (Vercel)
npx skills add nodnarbnitram/claude-code-extensions --skill ha-voice -a codex2Manually: put the files in place
.agents/skills/ha-voice/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nodnarbnitram/claude-code-extensions --skill ha-voice -a cursor2Manually: put the files in place
.cursor/skills/ha-voice/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nodnarbnitram/claude-code-extensions plugins/cce-homeassistant/skills/ha-voice2Manually: put the files in place
.github/skills/ha-voice/SKILL.md1Skills CLI (Vercel)
npx skills add nodnarbnitram/claude-code-extensions --skill ha-voice -a gemini-cli2Platform CLI
gemini skills install https://github.com/nodnarbnitram/claude-code-extensions --path plugins/cce-homeassistant/skills/ha-voiceManually: put the files in place
.devin/skills/ha-voice/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nodnarbnitram/claude-code-extensions --skill ha-voice -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ha-voice
How do I install ha-voice in Claude Code?
Run npx skills add nodnarbnitram/claude-code-extensions --skill ha-voice -a claude-code. The file will be placed in ~/.claude/skills/ha-voice/SKILL.md.
What does the ha-voice skill do?
It provides templates and syntax constraints for Home Assistant voice pipelines. The agent learns how to structure custom intents and format ESPHome voice satellites.
Where should custom intent files be stored?
Place them in the custom_sentences/ directory with version: 1 in the YAML header. The older sentences/ directory is deprecated.
Source text
SKILL.md · MIT
---
name: ha-voice
description: "Configure Home Assistant Assist voice control with pipelines, intents, wake words, and speech processing. Use when setting up voice control, creating custom intents, configuring TTS/STT, or building voice satellites. Activates on keywords: Assist, voice control, wake word, intent, sentence, TTS, STT, Piper, Whisper, Wyoming."
---
# Home Assistant Voice Control
> Configure Assist pipelines, custom intents, wake words, speech processing, and voice satellites for local voice control.
## Quick Start
### Setting up Assist Pipeline
```yaml
# configuration.yaml
assist_pipeline:
pipelines:
- language: en
name: Default Pipeline
stt_engine: faster_whisper # Local STT
tts_engine: tts.piper # Local TTS
conversation_engine: conversation.home_assistant
wake_word_entity: binary_sensor.wake_word
```
**Why this matters:** The pipeline connects all components (STT, TTS, intent, conversation agent) into a single voice workflow.
### Creating Custom Intents
```yaml
# custom_sentences/en/turn_on.yaml
language: en
version: 1
intents:
TurnOn:
data:
- sentences:
- "turn on the [area] {name:list}"
- "turn on {name:list}"
- "[please] activate {name:list}"
lists:
name: light_names
lists:
light_names:
- "bedroom light"
- "kitchen overhead"
- "living room"
```
**Why this matters:** Custom sentence patterns enable natural voice commands tailored to your home.
### Configuring Text-to-Speech (TTS)
**Local Option - Piper:**
```yaml
tts:
- platform: piper
language: en_GB
voice: jenny_dioco
```
**Cloud Option - OpenAI:**
```yaml
tts:
- platform: tts
service: google_translate_say # or openai, google cloud
language: en
```
**Why this matters:** TTS gives voice feedback; local options require no cloud dependencies.
### Configuring Speech-to-Text (STT)
**Local Option - Faster Whisper:**
```yaml
stt:
- platform: faster_whisper
language: en
```
**Cloud Option - Google Cloud Speech:**
```yaml
stt:
- platform: google_cloud
language_code: en-US
```
**Why this matters:** STT converts spoken commands to text; local options provide privacy.
## Critical Rules
### ✅ Always Do
- ✅ Use `custom_sentences/` directory for intent configuration (not deprecated `sentences/`)
- ✅ Test intents with Assist Developer Tools before deploying
- ✅ Use `{name:list}` syntax for slot-based entity matching
- ✅ Configure both STT and TTS engines in the same pipeline
- ✅ Verify wake word entity exists before enabling in pipeline
- ✅ Document intent lists so voice commands are discoverable
### ❌ Never Do
- ❌ Don't hardcode entity IDs in sentence patterns (use lists and slots)
- ❌ Don't forget `version: 1` in custom_sentences YAML files
- ❌ Don't mix old `sentences/` directory with new `custom_sentences/` (use `custom_sentences/` only)
- ❌ Don't enable Piper TTS without adequate disk space (models are 100+ MB)
- ❌ Don't use wildcard `{query}` for every slot (makes intents ambiguous)
- ❌ Don't skip testing with Assist Developer Tools
### Common Mistakes
**❌ Wrong - Hardcoded entity IDs:**
```yaml
intents:
TurnOn:
data:
- sentences:
- "turn on light.bedroom"
- "turn on light.kitchen"
```
**✅ Correct - Using slot lists:**
```yaml
intents:
TurnOn:
data:
- sentences:
- "turn on [the] {name:list}"
lists:
name: light_names
lists:
light_names:
- "bedroom"
- "kitchen"
```
**Why:** Lists are dynamic and can be generated from Home Assistant entities programmatically.
## Sentence Pattern Syntax
### Slots
**Named slots** match list values:
```yaml
sentences:
- "turn on {name:list}" # Matches list value, captures as 'name' slot
```
### Lists
**List matching** provides slot values:
```yaml
lists:
room:
- "bedroom"
- "kitchen"
- "living room"
```
### Optional Groups
**Square brackets** make words optional:
```yaml
sentences:
- "[please] turn on the {name:list}"
- "activate [the] {device:list}"
```
### Wildcards
**Wildcard slots** capture any text:
```yaml
sentences:
- "remind me {reminder:text}" # Captures any text as 'reminder'
- "set a timer for {duration:text}"
```
### Combined Pattern Example
```yaml
intents:
TurnOn:
data:
- sentences:
- "[please] [turn on | switch on | activate] [the] {area} {name:list}"
- "[please] turn on {name:list}"
- "activate {name:list} [in the] {room:list}"
lists:
name: light_names
room: room_names
Reminder:
data:
- sentences:
- "remind me {reminder:text}"
- "[please] [create | set] a reminder [for me] [to] {reminder:text}"
lists:
light_names:
- "bedroom light"
- "kitchen overhead"
- "living room lamps"
room_names:
- "bedroom"
- "kitchen"
- "living room"
```
**Why this matters:** Flexible patterns enable natural phrasing while maintaining intent recognition accuracy.
## Built-In Intents Reference
Home Assistant provides default intents:
### Navigation Intents
- `HassTurnOn` / `HassTurnOff` - Control devices
- `HassToggle` - Toggle switches/lights
- `HassOpenCover` / `HassCloseCover` - Control covers
- `HassSetClimate` - Control climate (heat/cool)
### Information Intents
- `HassGetState` - Get entity state
- `HassGetHistory` - Query automation history
### Home Control Intents
- `HassArmAlarm` / `HassDisarmAlarm` - Arm/disarm alarms
- `HassLockDoor` / `HassUnlockDoor` - Control locks
### Custom Intents
You create additional intents in `custom_sentences/` by defining new intent blocks:
```yaml
intents:
CustomIntentName:
data:
- sentences: [...]
```
## Wake Word Configuration
### openWakeWord (Local)
```yaml
conversation:
engine: openai
# Enable openWakeWord
binary_sensor:
- platform: openwakeword
models:
- alexa # "Alexa, help"
- hey_google # "Hey Google, ..."
- hey_siri
```
### Porcupine (Local, Paid)
```yaml
binary_sensor:
- platform: porcupine
access_key: !secret porcupine_key
keywords:
- hey_home_assistant
```
## Voice Satellite Setup
### Hardware Requirements
- **Microphone:** INMP441 (I2S digital) or similar
- **Speaker:** MAX98357A amplifier or similar
- **Board:** ESP32-S3, ESP32-S3-BOX-3 preferred
- **Connectivity:** WiFi required
### ESPHome Voice Assistant Config
```yaml
# ESPHome device
packages:
voice_assistant: !include packages/voice_assistant.yaml
# Or inline configuration:
i2s_audio:
i2s_lrclk_pin: GPIO33
i2s_bclk_pin: GPIO34
i2s_mclk_pin: GPIO32
microphone:
- platform: i2s_audio
id: mic
adc_type: external
i2s_din_pin: GPIO35
pdm: false
speaker:
- platform: i2s_audio
id: speaker
dac_type: external
i2s_dout_pin: GPIO36
mode: mono
voice_assistant:
microphone: mic
speaker: speaker
noise_suppression_level: 2
auto_gain: 80dB
volume_multiplier: 0.8
```
**Why this matters:** Voice satellites extend Assist to multiple rooms with local processing.
## Speech Processing Configuration
### Language Support
**Full Support (20+ languages):** en, de, fr, it, es, nl, pl, pt, ru, sv, tr, uk, zh, ja, ko, and more
**Partial Support (40+ languages):** Regional variants and additional languages with varying STT/TTS availability
**Community Support (80+ languages):** Community-contributed sentence templates
**Language Config:**
```yaml
assist_pipeline:
pipelines:
- language: de # German
name: Deutsche Pipeline
tts_engine: tts.piper # Set voice per language
```
### Performance Tuning
**STT (Faster Whisper):**
```yaml
stt:
- platform: faster_whisper
language: en
model: base # tiny, base, small, medium, large
acceleration: gpu # CPU or GPU
```
**TTS (Piper):**
```yaml
tts:
- platform: piper
voice: en_GB-jenny
rate: 11025 # Audio sample rate
volume_normalize: true
```
### Conversation Agent Integration
**Built-in Agent:**
```yaml
conversation:
engine: home_assistant
```
**OpenAI Agent:**
```yaml
conversation:
engine: openai
api_key: !secret openai_api_key
model: gpt-4
```
**Custom Conversation Agent:**
```yaml
conversation:
engine: custom
module: custom_components.my_agent
```
## Common Intent Patterns
### Device Control Pattern
```yaml
intents:
TurnOn:
data:
- sentences:
- "turn on [the] {name:list}"
- "[please] activate {name:list}"
lists:
name: light_names
```
### Climate Control Pattern
```yaml
intents:
SetClimate:
data:
- sentences:
- "set [the] {room:list} [thermostat] to {temp:number} degrees"
- "make it {temp:number} in [the] {room:list}"
lists:
room: room_names
```
### Query Pattern
```yaml
intents:
GetState:
data:
- sentences:
- "what is the temperature [in the] {room:list}"
- "is [the] {name:list} on"
lists:
room: room_names
name: device_names
```
## Testing with Developer Tools
1. Go to **Developer Tools** → **Assist**
2. Enter test sentence: "turn on the bedroom light"
3. Check:
- ✅ Intent matched correctly
- ✅ Slots extracted properly
- ✅ Audio plays (if TTS configured)
4. Debug mismatches by:
- Reviewing sentence patterns
- Checking list values
- Verifying slot names
## Troubleshooting
### Intent Not Recognized
**Symptoms:** Voice command doesn't match any intent
**Solution:**
```yaml
# Check custom_sentences directory structure
ls -R config/custom_sentences/
# Verify YAML syntax
cat config/custom_sentences/en/custom.yaml
# Test in Assist Developer Tools with exact phrase
# Adjust sentence patterns to match expected phrasing
```
### TTS/STT Engine Not Working
**Symptoms:** "Engine not available" error in Assist
**Solution:**
```yaml
# Verify engine is configured
service: tts.piper # Must exist
# Check dependencies installed
pip install piper-tts # for Piper
pip install faster-whisper # for Whisper
# Restart Home Assistant to load engines
```
### Wake Word Not Triggering
**Symptoms:** Binary sensor stays off despite noise
**Solution:**
```yaml
# Verify entity_id is correct
service: homeassistant.update_entity
target:
entity_id: binary_sensor.wake_word
# Check binary sensor configuration
# Review noise levels and model sensitivity
# Test microphone separately
```
### Voice Satellite Connection Issues
**Symptoms:** ESP32 disconnects from WiFi or Assist pipeline
**Solution:**
```bash
# Check WiFi signal strength in ESPHome logs
# Reduce WiFi distance or add access point
# Update ESPHome firmware
esphome run voice_assistant.yaml --upload-speed 115200
```
## Dependencies
### Required
| Component | Version | Purpose |
|-----------|---------|---------|
| Home Assistant | 2024.1+ | Assist platform |
| Faster Whisper | 0.5+ | Local STT engine |
| Piper TTS | 1.0+ | Local TTS engine |
### Optional
| Component | Version | Purpose |
|-----------|---------|---------|
| OpenWakeWord | 0.3+ | Wake word detection |
| Porcupine | Latest | Premium wake word |
| ESPHome | 2024.1+ | Voice satellite devices |
## Official Documentation
- [Home Assistant Voice Control](https://www.home-assistant.io/voice_control/)
- [Assist Pipeline Configuration](https://www.home-assistant.io/integrations/assist_pipeline/)
- [Intent Recognition Guide](https://developers.home-assistant.io/docs/voice/intent-recognition)
- [Conversation Integration](https://www.home-assistant.io/integrations/conversation/)
## Setup Checklist
Before using voice commands, verify:
- [ ] Assist pipeline configured with STT, TTS, and conversation engine
- [ ] `custom_sentences/en/` directory created with intent definitions
- [ ] Sentence patterns tested in Assist Developer Tools
- [ ] Wake word entity exists (if using wake word)
- [ ] Microphone and speaker working (test via Developer Tools)
- [ ] Intent lists contain correct entity aliases
- [ ] Language setting matches your configuration
- [ ] All YAML syntax is valid (no tabs, proper indentation)
© nodnarbnitram · MIT · nodnarbnitram/claude-code-extensions