Understanding Agents and Skills
Relevant source files
The following files were used as context for generating this wiki page:This document provides a technical overview of the Agent and Skill architecture within the voice-elevenlabs plugin. This system is designed to provide conversational voice capabilities to Claude Code, primarily through the voice-assistant agent and its associated voice-responses skill, which leverage the ElevenLabs API for Text-to-Speech (TTS) functionality.
The core concept is an "agent" that defines a persona and behavior, which in turn utilizes "skills" to perform specific actions. The voice-assistant agent is a conversational entity that speaks its responses aloud. It achieves this by using the voice-responses skill, which determines when and what to speak. This functionality is further extended by a set of commands for direct voice control and automated hooks for event-driven voice notifications.
Sources: agents/voice-assistant.md, skills/voice-responses.md
System Architecture Overview
The system is composed of an Agent, a Skill, a set of Commands, and automated Hooks. The Agent acts as the high-level controller, the Skill provides the logic for when to speak, the Commands offer direct user control over voice features, and the Hooks provide automated, non-interactive voice feedback.
The following diagram illustrates the relationship between these components.
This diagram shows how the User interacts with the Agent and Commands, which in turn use the Skill and claude-voice-notifications utility to interact with the ElevenLabs API.
Sources: agents/voice-assistant.md, skills/voice-responses.md, README.md:23-32, hooks/hooks.json
The Voice Assistant Agent
The voice-assistant is the central component, defined as a conversational agent that speaks its responses aloud. Its primary purpose is to provide a more natural, voice-enabled interaction model.
Sources: agents/voice-assistant.md:2-5
Behavior Flow
The agent follows a specific sequence after generating a text-based response to a user's query.
- Generate Text Response: The agent first formulates a standard text response.
- Create Spoken Summary: It then creates a concise summary of the response, limited to 1-3 sentences.
- Speak Summary: The agent uses the ElevenLabs TTS service to speak this summary aloud.
Sources: agents/voice-assistant.md:10-14
The following flowchart visualizes this behavior.
This flow ensures that the user receives both a detailed text response and a brief, audible summary for a natural conversational experience.
Sources: agents/voice-assistant.md:10-14, 25-28
Guidelines and Settings
The agent operates under a set of guidelines to ensure the voice interaction is effective:
- Brevity: Spoken responses must be brief and conversational.
- Clarity: Use natural language and avoid technical jargon in spoken summaries.
- Pacing: Speak at a natural, measured pace with a helpful, friendly tone.
- Voice: Use the voice configured via the
ELEVENLABS_VOICE_IDenvironment variable.
Sources: agents/voice-assistant.md:18-23, commands/voices.md:18-22
The Voice Response Skill
The voice-responses skill provides the underlying logic that enables the agent to speak. It determines when a verbal response is appropriate.
Sources: skills/voice-responses.md:2-7
Activation Triggers
The skill is activated under specific conditions:
- The user explicitly asks to "speak," "read aloud," or "tell me."
- The user mentions accessibility or hands-free needs.
- The agent completes a significant task and an announcement is appropriate.
Sources: skills/voice-responses.md:11-15
Spoken Response Guidelines
When activated, the skill follows strict guidelines for the spoken output:
- Length: Maximum of 50 words.
- Content: Avoid code syntax, file paths, or technical notation.
- Pronunciation: Acronyms should be pronounced (e.g., "A P I" for API).
Sources: skills/voice-responses.md:21-25
The following sequence diagram shows the interaction when the skill is activated.
This diagram illustrates the process from user request to the final audio playback, highlighting the skill's role in the decision-making process.
Sources: skills/voice-responses.md:11-19, agents/voice-assistant.md:25-28
Automated Voice Hooks
The plugin uses automated hooks to provide voice notifications for background events, enhancing user awareness without direct interaction. These are defined in hooks/hooks.json.
| Event | Script | Description |
|---|---|---|
Stop | stop-voice.sh | Announces "[project]: done" when Claude finishes a task. |
SubagentStop | subagent-voice.sh | Announces "[project]: [task]" when a subagent completes its task. |
Notification | claude-voice-notifications | Announces when Claude requires permission or user input. |
Sources: hooks/hooks.json:2-17
Hook Script Logic
The shell scripts (stop-voice.sh and subagent-voice.sh) dynamically construct a concise message based on the current context.
- They parse the input to get the current working directory (
cwd). - The project name is extracted from the
cwd. subagent-voice.shalso attempts to extract the task description from the agent's transcript.- A short message is constructed (e.g.,
"my-project: done"or"api-refactor: updated docs"). - This message is then piped to
claude-voice-notificationsto be spoken.
Sources: hooks/scripts/stop-voice.sh:5-19, hooks/scripts/subagent-voice.sh:5-32
Here is a code snippet from subagent-voice.sh showing how the message is built:
# hooks/scripts/subagent-voice.sh:21-29
if [ -n "$project" ] && [ -n "$description" ]; then
# Shorten description to ~30 chars
short_desc=$(echo "$description" | cut -c1-30 | sed 's/[[:space:]]*$//')
message="$project: $short_desc"
elif [ -n "$description" ]; then
short_desc=$(echo "$description" | cut -c1-40 | sed 's/[[:space:]]*$//')
message="Done: $short_desc"
elif [ -n "$project" ]; then
message="$project task done"
else
message="Task completed"
fi
Sources: hooks/scripts/subagent-voice.sh:21-29
Summary
The voice-elevenlabs plugin implements a robust system for voice interaction through its voice-assistant agent and voice-responses skill. The agent defines the "who" (a helpful voice assistant), while the skill provides the "when" (in response to specific conversational cues). This core functionality is supported by a suite of direct commands for granular control over speech and automated hooks for ambient, event-driven notifications. Together, these components create a seamless and natural voice experience within the Claude Code environment.
Sources: README.md, agents/voice-assistant.md, skills/voice-responses.md