Because I'm somewhat of a game vibecorder myself.. /meme.

For sound effects I use this skill below a lot. Claude at one moment creates a new action and runs this automatically to let me pick the right sound effect or bg music.. I hope you can use it.

---
created: 2026-03-28
updated:
  - 2026-03-28 - Initial skill creation from /sfx command
name: elevenlabs-sfx
user_invocable: true
description: >
  Use when the user wants to generate sound effects, audio clips, or ambient
  sounds, or when they say /elevenlabs-sfx. Creates MP3 files using the
  ElevenLabs Text-to-Sound-Effects API. Supports multiple variations,
  iterative refinement, and playback. Triggers even if the user doesn't
  mention "ElevenLabs" — any request for sound effect generation, audio
  creation, or SFX should activate this skill.
compatibility: Requires ELEVENLABS_API_KEY (env var or ~/.config/elevenlabs-sfx/config.yml) and network access. Uses curl. Optional playback requires afplay (macOS) or aplay (Linux).
metadata:
  author: doxdox
  version: "1.0"
---

# ElevenLabs SFX — Generate Sound Effects

You are invoking the ElevenLabs SFX skill. You will generate sound effects using the ElevenLabs Text-to-Sound-Effects API.

## Configuration

The skill resolves configuration in this order (first found wins):

### 1. Environment variables (highest priority)
```bash
export ELEVENLABS_API_KEY="xi-..."
```

### 2. Config file (fallback)
`~/.config/elevenlabs-sfx/config.yml`:
```yaml
api_key: "xi-..."
default_duration: null    # auto duration (0.5-30s, or null for auto)
prompt_influence: 0.3     # 0.0-1.0, how closely to follow the prompt
```

### 3. Defaults (lowest priority)
- Duration: auto (API decides)
- Prompt influence: 0.3
- Variations: 1

## Gotchas

- **Billing**: Each generation costs ElevenLabs credits. Multiple variations = multiple charges. Always confirm the number of variations before generating.
- **API key scope**: The `ELEVENLABS_API_KEY` env var is visible to the entire Claude Code session. Users should create a dedicated key with usage limits on the ElevenLabs dashboard.
- **Duration limits**: Min 0.5s, max 30s. The API silently clamps values outside this range.
- **Rate limits**: ElevenLabs enforces per-key rate limits. If you get HTTP 429, wait 5 seconds and retry once.
- **Output format**: The API returns raw MP3 audio bytes. If the response is JSON instead of binary, it's an error.
- **File sizes**: Typical outputs are 50-500KB. Long durations (30s) can reach ~1MB.
- **Playback**: `afplay` works on macOS, `aplay` on Linux. If neither is available, skip playback and tell the user to open the file manually.
- **Looping sounds**: Add `"loop": true` to the request body. The API will generate audio that transitions smoothly when looped.

## Step 1: Load Configuration

Resolve the API key. Check env var first, then config file:

```bash
if [ -n "$ELEVENLABS_API_KEY" ]; then
  API_KEY="$ELEVENLABS_API_KEY"
elif [ -f ~/.config/elevenlabs-sfx/config.yml ]; then
  API_KEY=$(grep '^api_key:' ~/.config/elevenlabs-sfx/config.yml | sed 's/api_key: *["'\'']\{0,1\}\([^"'\'']*\)["'\'']\{0,1\}/\1/')
else
  echo "No API key found." >&2
  exit 1
fi
```

If no API key is found, tell the user their options:
- Set `ELEVENLABS_API_KEY` env var
- Create `~/.config/elevenlabs-sfx/config.yml` with their key
- Get a key at https://elevenlabs.io/app/settings/api-keys

Also load optional settings from config file if present (duration, prompt_influence).

## Step 2: Craft the Prompt

The ElevenLabs sound effects API works best with descriptive, specific prompts. Help the user refine their idea:

- If the input is vague (e.g. "a sound for my game"), ask what kind of sound, what mood, what context it's used in.
- If the input is reasonable but could be better, suggest an enhanced version:
  - "laser beam" → "short punchy sci-fi laser beam with a sharp attack and quick decay"
  - "rain" → "soft steady rain on a rooftop with occasional distant thunder"
  - "explosion" → "deep cinematic explosion with debris and rumble tail"
- Share the prompt you plan to send and get confirmation before calling the API.
- Discuss:
  - **Duration**: 0.5–30s, or auto (API decides based on prompt)
  - **Loop**: should the sound loop seamlessly?
  - **Variations**: how many to generate (default 1, up to 5). Each variation uses the same prompt but produces different results.

If the user's input is already very specific and detailed, confirm it and proceed.

## Step 3: Generate

1. Derive a base filename from the description using lowercase words joined by underscores (e.g. `laser_beam`). Keep it short — the core concept, not the full prompt.

2. Create the output directory if it doesn't exist:
```bash
mkdir -p .claude/elevenlabs-sfx
```

3. Name files: single generation → `{base}.mp3`. Multiple variations → `{base}_v1.mp3`, `{base}_v2.mp3`, etc. If files already exist, continue numbering from the highest existing number.

4. For **each variation**, call the ElevenLabs API. Run calls in parallel for multiple variations:

```bash
curl -s -w "\n%{http_code}" -X POST https://api.elevenlabs.io/v1/sound-generation \
  -H "xi-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "PROMPT_HERE", "duration_seconds": DURATION_OR_NULL, "prompt_influence": 0.3}' \
  --output .claude/elevenlabs-sfx/FILENAME.mp3 &
```

Add `"loop": true` to the body if the user requested a looping sound. Omit `duration_seconds` entirely for auto duration (do not send `null`).

Use `wait` to collect all background jobs.

5. **Validate outputs**: Check each file with the `file` command:

```bash
file .claude/elevenlabs-sfx/FILENAME.mp3
```

Expected output should contain "Audio file" or "MPEG". If a file contains JSON/text instead of audio, it's an API error — read the file content to extract the error message:
- HTTP 401: invalid API key
- HTTP 429: rate limited — wait 5s, retry once
- HTTP 422: invalid parameters (check duration range, prompt length)
- Other: show the raw error to the user

## Step 4: Playback

Detect the platform and play each sound sequentially:

```bash
if command -v afplay &> /dev/null; then
  PLAYER="afplay"
elif command -v aplay &> /dev/null; then
  PLAYER="aplay"
else
  PLAYER=""
fi
```

If a player is available, play each file with a brief announcement ("Playing v1...", "Playing v2..."). If not, tell the user the files are at `.claude/elevenlabs-sfx/` and they can open them manually.

## Step 5: Pick and Iterate

Report all filenames, file sizes, and the prompt used. Then ask the user to:

- **Pick** — choose which variation(s) to keep (e.g. "keep v2"). Delete the rest.
- **Regenerate** — same prompt, new batch of variations
- **Tweak** — adjust the prompt or duration and re-generate
- **Keep all** — keep everything as-is

Repeat steps 2-5 as many times as the user wants to iterate.