Voz extension — скилл

---
name: voz-extension
description: Builds, changes and debugs Voz extensions, the TypeScript plugins for the Voz dictation app on the Mac. Use when the user wants Voz to do something new with what they dictate, such as a voice command, a writing style per app, a hotkey or a tool agents can call, or works in a `voz new` folder or `~/.voz/extensions`, or when a Voz extension fails to load.
---

# Voz extension

Voz is a Mac dictation app. It records, transcribes, cleans up and types text. An extension is TypeScript that Voz runs with Bun to change what happens with a dictation, or to add commands. Your job is to turn what bothers the user into the smallest extension that fixes it, and to prove it works in a real dictation.

Copy this checklist into your reply and keep it current:

```
- [ ] 1. Look: Voz's current state is known
- [ ] 2. Interview: the user said yes to a one-sentence spec
- [ ] 3. Pick: each part of the spec maps to an API member
- [ ] 4. Build: the smallest version exists
- [ ] 5. Verify: tests pass, it loads clean, the user confirmed a real dictation
- [ ] 6. Hand over
```

The API is in [references/api.md](references/api.md). Read the section for each member you use before you write code that calls it.

## 1. Look

Finding facts is your job, never the user's. Run these before you ask anything:

- `voz status`: permissions, speech model and loaded extensions. Exit code 3 means Voz is closed: run `voz start`
- `voz extensions`: what is installed, whether it loaded, its error and settings
- `voz history --limit 5`: what the user really dictates
- `voz help`: every command. `voz help <words>` finds one

If `voz` is not on the PATH, use `/Applications/voz.app/Contents/MacOS/voz`.

Done when you know what is installed, what is broken, and whether an installed extension already does part of the idea.

## 2. Interview

Interview the user until you both picture the same extension. Ask one question at a time, in plain words, with two to four options and your recommended answer first. Skip what the user already told you, and look up facts yourself, such as a bundle ID with `osascript -e 'id of app "Slack"'`.

Find out:

1. What starts it: a phrase, every dictation, an app, a button or a hotkey
2. What it does: changes the text, or acts somewhere else
3. Two or three things the user would say, and the exact result for each. These become your tests
4. What the user sets up, such as a token. Each one is a setting