Adding a New Command

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• commands/speak.md
• commands/dialogue.md
• commands/create-voice.md
• commands/transcribe.md
• commands/voices.md
• commands/voice-config.md
• hooks/hooks.json

This document outlines the process for adding new custom commands to the Voice ElevenLabs plugin for Claude Code. The plugin uses a file-based system where each command is defined by a single Markdown file within the commands/ directory. This approach allows for extending the plugin's functionality by defining the command's interface, documentation, and execution logic in a structured text format that Claude can interpret and act upon.

The core principle is that each .md file serves as a set of instructions for the LLM. It defines what the command does, what tools it can use (like Bash), and how to process user arguments to achieve a result, typically by interacting with the ElevenLabs API.

Command Architecture

A command is defined by a single Markdown file placed in the commands/ directory. The system discovers and registers commands based on the presence of these files. The overall flow from command creation to execution is illustrated below.

This diagram shows the developer's workflow for adding a new command and the subsequent execution flow when a user invokes it.

Command File Structure

Each command .md file consists of two main parts: a YAML frontmatter block for metadata and a Markdown body for instructions and documentation.

This diagram breaks down the essential components of a command definition file.

YAML Frontmatter

The frontmatter is a YAML block at the very top of the file, enclosed by ---. It contains essential metadata for the Claude Code environment.

Key	Type	Description	Example Source
description	String	A concise summary of the command's function. This is displayed in help menus.	commands/speak.md:2
allowed-tools	Array of Strings	Specifies which built-in tools the command is permitted to use. Typically ["Bash", "Read"].	commands/dialogue.md:3

Markdown Body

The body of the file contains natural language instructions for the LLM. It should be structured to be easily understood by both human developers and the AI.

A typical structure includes:

1. Title: A main # heading for the command.
2. Usage/Examples: Sections demonstrating how to use the command with different arguments.
3. Instructions: A dedicated section, often titled "Instructions", that explicitly tells the LLM how to execute the command. This is the most critical part for functionality.

For example, the /create-voice command instructs the LLM to use the ElevenLabs Voice Design v3 API and handle the response.
Sources: commands/create-voice.md:31-36

Argument Handling

Commands can accept arguments from the user. These arguments are made available to the LLM through a special variable, $ARGUMENTS. The specific argument is accessed by its name.

• /dialogue "Alice: Hi!" -> $ARGUMENTS.script contains "Alice: Hi!"
• /create-voice "description" -> $ARGUMENTS.description contains "description"
• /transcribe file:/path/to/audio.mp3 -> $ARGUMENTS.file contains /path/to/audio.mp3

The "Instructions" section in the command's markdown file must specify how to use these arguments.
Sources: commands/dialogue.md:39, commands/create-voice.md:38, commands/transcribe.md:40

Execution Flow

When a user invokes a command, the LLM reads the corresponding .md file and follows its instructions. The allowed-tools field grants the necessary permissions to execute shell commands.

The following sequence diagram illustrates the execution of the /speak command.

This flow is based on the implementation details provided in the /speak command definition.
Sources: commands/speak.md:28-33

Using Bash and External APIs

The primary mechanism for command execution is through the Bash tool. The markdown instructions guide the LLM to construct and execute shell commands. Most commands in this plugin use curl to interact with the ElevenLabs API.

An API key is required and is expected to be available as an environment variable, $ELEVENLABS_API_KEY.

Example curl command to fetch available voices:

curl -s "https://api.elevenlabs.io/v1/voices" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" | jq '.voices[] | {name, voice_id}'

Sources: commands/voices.md:20-22

Alternatively, commands can use the claude-voice-notifications CLI tool, which acts as a wrapper for specific voice events.

echo '{"hook_event_name": "Stop", "message": "TEXT_HERE"}' | claude-voice-notifications

Sources: commands/speak.md:24-26

Registering the New Command

To add a new command:

1. Create a new file, such as my-command.md, inside the commands/ directory.
2. Populate the file with the required YAML frontmatter and a Markdown body containing clear instructions, as detailed above.
3. Optionally, update the command table in README.md to make the new command discoverable to users.

The plugin system will automatically detect the new file and make the /my-command available for use within Claude Code.
Sources: README.md:20-33