Voz extension skill
A skill that takes an agent from an idea to a working TypeScript extension for Voz, so Mac dictation becomes commands or notes.
- 55 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Extensions run with the user permissions and can reach apps, files, the terminal and the network.
- An extension may read text from the front window and send dictated content outside.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/voz-extensionDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Extensions run with the user permissions and can reach apps, files, the terminal and the network.
- An extension may read text from the front window and send dictated content outside.
This is third-party code. Review the repository files before installing.
What it does
Voz is a free dictation app for Mac: the right Command key starts recording and text appears at the cursor. Recognition runs on the computer itself. The `voz-extension` skill in the repository teaches an agent to write TypeScript extensions for the app, which run through Bun and change what happens to dictated text. The skill follows a six-step checklist: look, interview, pick, build, verify and hand over. First the agent learns the app state itself with `voz status`, `voz extensions` and `voz history`. Then it asks one question at a time and writes the extension only after the user confirms a one-sentence description. A table helps choose the API, for example `registerCommand` for voice commands or `beforeCleanup` for a per-app writing style.
Who it is for. Voz users on Mac who want their own commands and rules in dictation and want an agent to write the code.
Good fit when
- A voice phrase "send it" should perform an action in mail or a messenger.
- A dictation such as "todo call Milan tomorrow" should become an entry in a to-do list.
- Notes need minimal text edits and the work chat a business style.
- All dictated messages should go to a file or service after insertion.
Not a fit when
- The Voz app is not installed: the skill only writes code for it.
- The device is not an Apple Silicon Mac running macOS 26.
- A ready-made feature from the extension catalogue is enough: it installs with `voz install`.
Example request
Build a Voz extension: the phrase "note" saves the dictated text to my Markdown notes folder, and ask me what exactly I need before writing code.Limitations
The skill only works with Voz, which needs macOS 26 and Apple Silicon. Extensions run with your permissions: they can reach apps, files, the terminal and the network, so install only ones you trust. An extension can read the front window only when its package declares it, and the list of such extensions is visible in `voz extensions`. The app collects anonymous counts that cannot be turned off. If `voz` is not on the `PATH`, run the command by the path `/Applications/voz.app/Contents/MacOS/voz`. Publishing an extension to npm needs the `voz-package` keyword.
How to disable. Remove the skill from the agent directory (a global one when installed with `-g`). Disable created extensions with `voz disable` and delete them from `~/.voz/extensions`. The app itself is removed like any Mac program.
FAQ
How do I install the voz-extension skill?
Run `npx skills add Joelheile/voz -g`. With the app, the skill installs through the Build your own button on the Extensions page, which copies a prompt for the agent.
What kinds of extensions can be written?
Voice commands, writing styles for apps and sites, regex text rules, a final say before insertion and actions after insertion. The skill table picks the right API.
Where do extensions live?
They are TypeScript files in `~/.voz/extensions`. If an extension is slow or crashes, dictation keeps working. With no extensions installed the app runs nothing extra.
How do I share an extension?
Publish the package to npm with the `voz-package` keyword and it appears on the Extensions page. Others install it from the menu or with `voz install voz-meeting`.
Does dictation audio go to the cloud?
Speech recognition runs on the computer with the Parakeet model, and Apple's on-device model cleans the text. Data leaves only if an installed extension does it or an AI service you choose.
Discussion
No questions or reviews yet.
Related
SkillsLocal transcription of Apple Voice Memos on a Mac: utterance tables, daily reports and meeting notes for an agent
18 portable skills for work where AI is weakest: messy voice input, message tone, small trend tests and safe shipping.
Local voice layer for Claude Code and Codex on macOS: when the agent finishes or fails, it says in a sentence or two what happened
Local dictation for macOS with Claude Code and Codex plugins: speech becomes prompt text that recognizes your files.
Thirteen agent skills: stickers, speech synthesis and recognition, SearXNG search, Atlassian design and Claude Code operation.
A skill and MCP for voiced screen recordings: the agent turns a spoken bug walkthrough into tasks with screenshots and code
README in short
The README presents Voz as a free open-source app where an agent writes missing features as extensions. It covers installation, `voz` commands, privacy and permissions, and names the skill as the way to connect an agent to extension development.
README badge
Original SKILL.md
--- 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