Guide · Agent skill

How to use the ElevenLabs Voice Generator agent skill

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The elevenlabs-tts skill lets an AI agent turn written text or a script into spoken MP3 audio using the ElevenLabs text-to-speech service. It is aimed at creators who want narration or voiceovers, and at developers who already have an ElevenLabs account and want audio in an app or video pipeline. After this guide you will know how to install the skill, trigger it with plain requests, and keep your voices and account details out of shared code.

ElevenLabs Voice GeneratorMengTo/Skills · MIT Download the skill

Quick start

1Download and unzip the skill. Download the ZIP from this page and unzip the elevenlabs-tts folder.
2Place it in your skills folder. Move the folder to ~/.claude/skills/ for personal use or to .claude/skills/ in a project. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
3Add your API key. Set ELEVENLABS_API_KEY in your environment or in the nearest .env file.
4Create a local voice profile. Make a profile JSON file outside the skill, such as local/elevenlabs/profiles.json, with a default profile and your voice name.
5Preview the request. Ask the agent to list voices or run a dry run so you can confirm the voice and settings before generating audio.
6Generate the voiceover. Ask for TTS audio from your script. The agent saves the MP3 and reports the output path.

What the elevenlabs-tts skill makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent loads when a task matches the skill's description. This one covers ElevenLabs text-to-speech: the agent can take inline text or a script file and produce an audio file.

Your specific voices, account details and defaults are kept in a local config file outside the skill, so the skill stays reusable and free of personal data. The agent can also list available voices and preview the request before any audio is generated.

Generates MP3 audio from inline text or a script file
Uses saved local voice profiles for voice, model and output settings
Can list matching voices without generating audio
Can show the resolved request with a dry run before calling the service

Install the elevenlabs-tts skill

Download the ZIP for the skill from this page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

Personal install: ~/.claude/skills/elevenlabs-tts
Project install: .claude/skills/elevenlabs-tts inside your project

Set up your API key and local voice profile

The skill reads ELEVENLABS_API_KEY from the process environment or from the nearest .env file. Never paste the key into the skill folder or into chat.

Create a local JSON profile file outside the skill. The skill looks for a profile in this order: a path passed with --config, the ELEVENLABS_TTS_CONFIG environment variable, then local/elevenlabs/profiles.json. Project-local files also work if they are gitignored, for example config/local/elevenlabs-tts.json.

A profile file has a default_profile name and a profiles object. Each profile can set a voice_name or voice_id, a model_id, an output_format, voice_settings and an output_dir.

Keep the API key in ELEVENLABS_API_KEY, not in files you share
Name voices in the profile file, not in the skill
Add the profile folder to .gitignore if it lives in a project

{
  "default_profile": "default",
  "profiles": {
    "default": {
      "voice_name": "Voice name from the local account",
      "model_id": "eleven_multilingual_v2",
      "output_format": "mp3_44100_128",
      "output_dir": "outputs/voiceovers"
    }
  }
}

Trigger the skill with natural requests

You do not need to call the script yourself. Ask for the outcome in plain language and include the words the skill responds to, such as ElevenLabs, text-to-speech, TTS, narration, voiceover, speech audio or voice generation.

If you want a specific profile, voice or output location, say so in the request. Otherwise the agent uses the default profile and its output_dir, then outputs/voiceovers/.

"Turn this script into an ElevenLabs voiceover."
"Make TTS audio from the text in script.txt using the default profile."
"List the ElevenLabs voices on my account that match narrator."
"Preview the ElevenLabs request for this paragraph without generating audio."

Generate audio with the helper script

The bundled script scripts/generate_voice.py does the work. The agent normally runs it for you, but you can use the same command to test. It reads text from a file, uses the default profile and writes an MP3.

Other options include --text for inline text, stdin when neither text option is given, --voice-id, --voice-name, --model-id, --output-format and --settings-json for one-off overrides, and --dry-run and --list-voices for checking before you spend credits.

--text "..." for a short inline line
--text-file path.txt for a script file
--profile name to choose a profile
--dry-run prints the request without calling the text-to-speech endpoint
--list-voices lists matching voices without generating audio

python3 <skill-root>/scripts/generate_voice.py --text-file script.txt --profile default --output output.mp3

Safety, network use and privacy

This skill runs a Python script and makes network calls to api.elevenlabs.io. The script text is sent to ElevenLabs, so do not use it for sensitive or confidential material unless you are comfortable with a third-party cloud service handling it.

The skill is written to generate audio with request-level settings and not to change your saved ElevenLabs account or voice settings unless you explicitly ask. Generated audio can count toward paid usage on your account.

Requires Python 3 and an ElevenLabs account with an API key
Network access to api.elevenlabs.io is required
Review the script and profile file before first use
The agent should report output paths and never print secrets

Tips for better results

Keep one profile per voice or use case, such as a narrator for product videos and another for internal training. Switch between them with --profile or by naming the profile in your request.

Run --dry-run or --list-voices first when you change a profile. This confirms the voice and settings before audio is generated. Check the MP3 by listening to it, especially for clipping and unintended pauses.

Use --text-file for longer scripts
Write the script with punctuation for natural pauses
Store each team's voice profiles in separate local files

What people use it for

Narrating a product walkthrough from a written script
Creating a voiceover for a short explainer video
Generating spoken audio for an app that needs speech output
Keeping several team voice profiles in local config without sharing account details

Frequently asked questions

How do I install the elevenlabs-tts skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

What do I need to use it?

You need Python 3, an ElevenLabs account with an API key set as ELEVENLABS_API_KEY, a local JSON voice profile file that is not included in the skill, and network access to api.elevenlabs.io.

Is the elevenlabs-tts skill free?

The skill is released under the MIT licence. ElevenLabs audio generation uses your ElevenLabs account, and generating audio may incur paid usage, so check your own plan before running large jobs.

Where do I store my voice names and API key?

Store the API key in the ELEVENLABS_API_KEY environment variable or a .env file, and store voice names and defaults in a local JSON profile outside the skill. The skill is designed to contain no personal data.

Can the skill change my ElevenLabs voice settings?

The skill is written to use request-level settings and not to mutate saved account or voice settings unless you explicitly ask for that.

Is it safe to send confidential scripts through this skill?

Be cautious. The text is transmitted to ElevenLabs, a third-party cloud service, so avoid sensitive or confidential text unless that is acceptable for your use.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you have an ElevenLabs account and want an agent to turn scripts into MP3 voiceovers while keeping voices and account details in local config. Pick something else if you do not have an API key, or if the text you need to narrate is confidential and cannot leave your machine.

Download the skill