[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DBCMF1PE4W67PM1QPDPKBV":3,"skill-same:01M7DBCMF1PE4W67PM1QPDPKBV":46},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7DBCMF1PE4W67PM1QPDPKBV","voice-help",null,"How to use the Mac Voice speak_and_listen tool well, and how to fix it. Use when talking with the user by voice, when they ask about voice mode, or when voice turns misbehave (silent mic, cut-off replies, wrong words, robotic voice, slow turns).","jeet0007\u002Fmac-voice-mcp","jeet0007","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F32159637?v=4","01M7DBC92GKH5EX8XPTPYG3SP6","Jeet","01M7DBC933C3THTR7RY3K4M7PD",0,"MIT","https:\u002F\u002Fgithub.com\u002Fjeet0007\u002Fmac-voice-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fvoice-help\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: voice-help\ndescription: How to use the Mac Voice speak_and_listen tool well, and how to fix it. Use when talking with the user by voice, when they ask about voice mode, or when voice turns misbehave (silent mic, cut-off replies, wrong words, robotic voice, slow turns).\n---\n\n# Using Mac Voice well\n\nspeak_and_listen says `text_to_speak` out loud, listens for one natural turn (it waits for the user to\nstart and stops when they pause), and returns an on-device whisper.cpp transcript.\n\n## Speaking\n\nWrite for the ear: 1–3 short sentences, outcome first, one question at a time. No markdown, code, paths,\nURLs or tables — describe them and put the details in the on-screen reply. The server also rewrites\nanything unspeakable and says so in a \"voice-mcp note\"; follow those notes.\n\n## Listening\n\n- Transcripts contain homophones and mangled jargon: interpret generously, and confirm by voice before\n  anything destructive or irreversible.\n- \"(No speech detected …)\" is not consent. Ask once more out loud. If there's still no answer, stop: say on\n  screen that voice mode is paused and they can type anything (or run \u002Fmac-voice-mcp:talk) to carry on. Don't\n  tell them to speak: the mic is off until you call speak_and_listen again.\n- Once the user talks by voice, stay in voice: answer every transcript with another speak_and_listen call\n  until they say stop or start typing. The plugin's hook enforces this: if you try to finish with a\n  text-only reply while voice mode is on, you'll be sent back once to answer by voice.\n- To end voice mode, or for a one-way announcement, call speak_and_listen with `listen: false`: it speaks\n  without opening the mic, and returns right away so you can keep working while it plays. A goodbye ends\n  voice mode. Voice mode also ends when the user types, or doesn't answer.\n- The final \"voice-mcp timing\" line is diagnostics. Ignore it unless the user asks why things feel slow.\n\n## Fixing problems\n\n| Symptom | Cause and fix |\n|---|---|\n| Not sure what's wrong | Have the user run `npx -y mac-voice-mcp@latest doctor` in a terminal: it checks setup, voice → transcript, and speakers → mic, each PASS \u002F WARN \u002F FAIL. |\n| \"microphone returned pure digital silence\" | Usually the app running the server lacks mic access: System Settings → Privacy & Security → Microphone, allow it, then restart that app. If the message says it's recording with ffmpeg, suggest `brew install sox` first. |\n| \"voice-mcp is not set up\" | Call voice_setup (check only), tell the user what's missing, install only after they agree. |\n| Reply cut off (\"may be cut off\" note) | They hit the listening limit. Ask them to continue; for long dictation pass a larger `listen_seconds`. |\n| Turn ends while they're still thinking | Set `VOICE_MCP_END_SILENCE_MS` higher (default 1500) in the server's environment. |\n| Misheard in a noisy room (fan, café, open office) | Suggest the bigger model, `small.en`. On real recordings with background noise it made about a third fewer mistakes than the default `base.en` (8% of words wrong instead of 12%), the same in a quiet room, and it still transcribes in about 0.3 s. It's a one-time 466 MB download. To switch: set `VOICE_MCP_WHISPER_MODEL=small.en` (plugin users: the `env` block of `~\u002F.claude\u002Fsettings.json`), restart, then call voice_setup with install=true, after the user agrees, to download it. |\n| Wrong words, names or jargon | Set `VOICE_MCP_WHISPER_PROMPT` to a sentence that uses the names and terms (it replaces the default developer hint), or use a bigger model (`VOICE_MCP_WHISPER_MODEL=small.en`, then voice_setup to download it). |\n| Voice sounds robotic | It uses the System Voice: System Settings → Accessibility → Spoken Content → System Voice. Download a Premium voice (Manage Voices…) and choose it there. `VOICE_MCP_VOICE` picks a specific one, or `best` the most natural installed. Or offer the Kokoro voice: a natural neural voice that runs on the Mac (about 1 GB on disk). With the user's OK, call `voice_setup` with `kokoro=true`. |\n| \"The Kokoro voice didn't work\" | The built-in voice spoke instead, so nothing was lost. Call `voice_setup` to see what's wrong. To reinstall, the user deletes `~\u002F.cache\u002Fmac-voice-mcp\u002Fkokoro\u002F` and you call `voice_setup` with `kokoro=true`. `VOICE_MCP_TTS=say` turns Kokoro off. |\n| Change the Kokoro voice | Set `VOICE_MCP_KOKORO_VOICE` (e.g. `af_bella`, `am_michael`, `bf_emma`) in the MCP server's env, or in Claude Code's `settings.json` `env` block for the plugin, then restart. |\n| Other languages | `VOICE_MCP_WHISPER_MODEL=base` (multilingual) and `VOICE_MCP_LANGUAGE=auto` or a code such as `th`. |\n| Slow turns | Read the timing line: \"spoke\" is the speech length, \"transcribed\" should be well under a second with the warm server. |\n| \"Another voice session on this Mac…\" | Another Claude window, Claude Desktop or Cursor held the speaker and mic for over 2 minutes (`VOICE_MCP_LOCK_WAIT_SECONDS`). Tell the user on screen, and try again once that conversation is over. |\n| Sent back to answer by voice when you meant to stop | The voice-mode hook thinks the conversation is still going. Say goodbye with `listen: false`. The user can switch the hook off with `VOICE_MCP_STAY_IN_VOICE=0` in Claude Code's settings `env`. |\n| An approval prompt on every turn | Add the tool to Claude Code's allow list (README: \"Allow voice turns without prompts\"). |\n","# Using Mac Voice well\n\nspeak_and_listen says `text_to_speak` out loud, listens for one natural turn (it waits for the user to\nstart and stops when they pause), and returns an on-device whisper.cpp transcript.\n\n## Speaking\n\nWrite for the ear: 1–3 short sentences, outcome first, one question at a time. No markdown, code, paths,\nURLs or tables — describe them and put the details in the on-screen reply. The server also rewrites\nanything unspeakable and says so in a \"voice-mcp note\"; follow those notes.\n\n## Listening\n\n- Transcripts contain homophones and mangled jargon: interpret generously, and confirm by voice before\n  anything destructive or irreversible.\n- \"(No speech detected …)\" is not consent. Ask once more out loud. If there's still no answer, stop: say on\n  screen that voice mode is paused and they can type anything (or run \u002Fmac-voice-mcp:talk) to carry on. Don't\n  tell them to speak: the mic is off until you call speak_and_listen again.\n- Once the user talks by voice, stay in voice: answer every transcript with another speak_and_listen call\n  until they say stop or start typing. The plugin's hook enforces this: if you try to finish with a\n  text-only reply while voice mode is on, you'll be sent back once to answer by voice.\n- To end voice mode, or for a one-way announcement, call speak_and_listen with `listen: false`: it speaks\n  without opening the mic, and returns right away so you can keep working while it plays. A goodbye ends\n  voice mode. Voice mode also ends when the user types, or doesn't answer.\n- The final \"voice-mcp timing\" line is diagnostics. Ignore it unless the user asks why things feel slow.\n\n## Fixing problems\n\n| Symptom | Cause and fix |\n|---|---|\n| Not sure what's wrong | Have the user run `npx -y mac-voice-mcp@latest doctor` in a terminal: it checks setup, voice → transcript, and speakers → mic, each PASS \u002F WARN \u002F FAIL. |\n| \"microphone returned pure digital silence\" | Usually the app running the server lacks mic access: System Settings → Privacy & Security → Microphone, allow it, then restart that app. If the message says it's recording with ffmpeg, suggest `brew install sox` first. |\n| \"voice-mcp is not set up\" | Call voice_setup (check only), tell the user what's missing, install only after they agree. |\n| Reply cut off (\"may be cut off\" note) | They hit the listening limit. Ask them to continue; for long dictation pass a larger `listen_seconds`. |\n| Turn ends while they're still thinking | Set `VOICE_MCP_END_SILENCE_MS` higher (default 1500) in the server's environment. |\n| Misheard in a noisy room (fan, café, open office) | Suggest the bigger model, `small.en`. On real recordings with background noise it made about a third fewer mistakes than the default `base.en` (8% of words wrong instead of 12%), the same in a quiet room, and it still transcribes in about 0.3 s. It's a one-time 466 MB download. To switch: set `VOICE_MCP_WHISPER_MODEL=small.en` (plugin users: the `env` block of `~\u002F.claude\u002Fsettings.json`), restart, then call voice_setup with install=true, after the user agrees, to download it. |\n| Wrong words, names or jargon | Set `VOICE_MCP_WHISPER_PROMPT` to a sentence that uses the names and terms (it replaces the default developer hint), or use a bigger model (`VOICE_MCP_WHISPER_MODEL=small.en`, then voice_setup to download it). |\n| Voice sounds robotic | It uses the System Voice: System Settings → Accessibility → Spoken Content → System Voice. Download a Premium voice (Manage Voices…) and choose it there. `VOICE_MCP_VOICE` picks a specific one, or `best` the most natural installed. Or offer the Kokoro voice: a natural neural voice that runs on the Mac (about 1 GB on disk). With the user's OK, call `voice_setup` with `kokoro=true`. |\n| \"The Kokoro voice didn't work\" | The built-in voice spoke instead, so nothing was lost. Call `voice_setup` to see what's wrong. To reinstall, the user deletes `~\u002F.cache\u002Fmac-voice-mcp\u002Fkokoro\u002F` and you call `voice_setup` with `kokoro=true`. `VOICE_MCP_TTS=say` turns Kokoro off. |\n| Change the Kokoro voice | Set `VOICE_MCP_KOKORO_VOICE` (e.g. `af_bella`, `am_michael`, `bf_emma`) in the MCP server's env, or in Claude Code's `settings.json` `env` block for the plugin, then restart. |\n| Other languages | `VOICE_MCP_WHISPER_MODEL=base` (multilingual) and `VOICE_MCP_LANGUAGE=auto` or a code such as `th`. |\n| Slow turns | Read the timing line: \"spoke\" is the speech length, \"transcribed\" should be well under a second with the warm server. |\n| \"Another voice session on this Mac…\" | Another Claude window, Claude Desktop or Cursor held the speaker and mic for over 2 minutes (`VOICE_MCP_LOCK_WAIT_SECONDS`). Tell the user on screen, and try again once that conversation is over. |\n| Sent back to answer by voice when you meant to stop | The voice-mode hook thinks the conversation is still going. Say goodbye with `listen: false`. The user can switch the hook off with `VOICE_MCP_STAY_IN_VOICE=0` in Claude Code's settings `env`. |\n| An approval prompt on every turn | Add the tool to Claude Code's allow list (README: \"Allow voice turns without prompts\"). |\n",{"name":5,"description":7},"main","6fdaefa91fc1f64923a2a2a202665138d1b3f093","skills\u002Fvoice-help","https:\u002F\u002Fgithub.com\u002Fjeet0007\u002Fmac-voice-mcp","https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fmac-voice-mcp","https:\u002F\u002Fgithub.com\u002Fjeet0007","@appman-agm ","2026-11-14 17:08:14",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add jeet0007\u002Fmac-voice-mcp --skill voice-help",{"tool":38,"command":39},"bunx","bunx skills add jeet0007\u002Fmac-voice-mcp --skill voice-help",{"tool":41,"command":42},"pnpm","pnpm dlx skills add jeet0007\u002Fmac-voice-mcp --skill voice-help","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjeet0007\u002Fmac-voice-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fvoice-help\u002FSKILL.md",true,[],[47,54,61,68],{"skillNo":48,"name":49,"nameZh":6,"description":50,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":19},"01M7DBCJAWP4BHEC1XJ5XAT4PQ","talk","Start a hands-free voice conversation with Claude through the speakers and microphone. Optionally name a task to work on.","https:\u002F\u002Fgithub.com\u002Fjeet0007\u002Fmac-voice-mcp\u002Fblob\u002Fmain\u002Fskills\u002Ftalk\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M7DBCEWVM335CM842SHX07Z9","setup","Check what Mac Voice needs (recorder, whisper.cpp, speech model, voice), install what's missing with your OK, then test a spoken turn.","https:\u002F\u002Fgithub.com\u002Fjeet0007\u002Fmac-voice-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fsetup\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M7DBCDBJ6MZZ20NBSVEZHHCB","hangup","End the call with Claude.","https:\u002F\u002Fgithub.com\u002Fjeet0007\u002Fmac-voice-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fhangup\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7DBCB853Y3HVQTSYBSR1GV9","call","Start a call with Claude. The microphone stays open and you talk whenever you like, like on the phone, until you hang up.","https:\u002F\u002Fgithub.com\u002Fjeet0007\u002Fmac-voice-mcp\u002Fblob\u002Fmain\u002Fskills\u002Fcall\u002FSKILL.md",[],[]]