docs(VM-1400): surface permission allow-list in voicemode skill#452
Merged
mbailey merged 2 commits intoMay 28, 2026
Merged
Conversation
The voicemode skill said nothing about Claude Code's permissions system, so an agent using the skill couldn't connect the "Do you want to proceed?" prompt users hit on first voicemode:converse call to the existing fix (documented but buried in docs/guides/permissions.md). - New references/permissions.md: terse, in-session operational doc - snippet, three application paths (/permissions UI, edit settings.json, shell heredoc), and global vs project vs project-local guidance. Links to docs/guides/permissions.md for the fuller user guide rather than duplicating it. - One trigger-aware sentence in SKILL.md near First-Time Setup, naming the symptom so a future agent will follow the link when the user hits the prompt. Refs: VM-1400
This doc is loaded by an agent that already knows how to edit files — it doesn't need three "how to apply" recipes (/permissions UI, $EDITOR, shell heredoc). Cut those plus the redundant tool table and the per-project-prompt UI workaround. Kept: symptom (so the agent knows when to load this), the snippet, the "don't blanket-allow mcp__voicemode__*" guardrail (real failure mode if an LLM tries to be helpful and auto-allows install/uninstall tools), and the three-location table (USER / project / project-local) with pick-when guidance. ~95 lines → ~40 lines.
mbailey
deleted the
docs/VM-1400-surface-permission-allow-list-in-voicemode-skill
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.claude/skills/voicemode/references/permissions.md— terse, in-session operational doc that names the symptom (Claude Code's "Do you want to proceed?" prompt on firstvoicemode:conversein a project) and shows three ways to fix it. Links to the existingdocs/guides/permissions.mdfor the fuller user-guide treatment rather than duplicating it.SKILL.mdnear First-Time Setup pointing at the new reference, so a future agent loading the skill will surface the fix when the user hits the prompt.Why
The skill is the always-loaded surface for an agent. Until now it said nothing about Claude Code's permissions system, so an agent helping a user couldn't connect the prompt the user was staring at to the fix that already exists in the project docs. Found while debugging in
~/Code/github.com/mbailey/keycutter.Design notes
references/chosen overdocs/to match the Anthropic skill convention for progressive-disclosure subfiles. The skill's existingdocs/transcript-visibility.mdis left in place; may migrate later in a separate cleanup.docs/guides/permissions.md— different audience (agent in-session vs user on website), linked rather than copied to avoid drift.Test plan
cat .claude/skills/voicemode/references/permissions.mdrenders cleanlydocs/guides/permissions.mdfrom.claude/skills/voicemode/references/permissions.md(4 levels up)references/permissions.mdresolvesRefs: VM-1400