Agent skill

Fish Audio

by vellum-ai in vellum-ai/vellum-assistant

Generate expressive audio clips using Fish Audio S2 TTS with bracket emotion tags.

MITAuto-check passedMedia & Creative

Install Fish Audio

skills CLI
$ npx skills add vellum-ai/vellum-assistant --skill fish-audio -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install vellum-ai/vellum-assistant fish-audio --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/vellum-ai/vellum-assistant.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/fish-audio .claude/skills/fish-audio && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
fish-audio
GitHub stars
1.4k
Token cost
~3.7k tokens
SKILL.md length
1,183 words
Files
1
Skills in repo
108
Repo updated
First seen
Licence
MIT

At a glance

Generate expressive audio clips using Fish Audio S2 TTS with bracket emotion tags.

  • Works in 3 steps: Generate silence for gaps between clips → Create a concat file → Combine
  • Tasks that involve Text to speech and voice
  • SKILL.md covers Overview, Configuration, API Key Setup and Generating a Single Clip, plus 4 more sections
  • Calls ffmpeg and curl; reaches api.fish.audio

What it does

Fish Audio is an agent skill from vellum-ai/vellum-assistant. Generate expressive audio clips using Fish Audio S2 TTS with bracket emotion tags. Record voice memos, narration, audio messages, or any spoken content.

Its SKILL.md is about 3.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts. Compatibility notes: Designed for Vellum personal assistants

It sits in Media & Creative, covering Text to speech and voice and Transcription. The repository describes itself as: An AI Assistant that’s easy to setup, does your work 24/7, knows your preferences and gets better over time. The licence is MIT.

When your agent uses it

  • Tasks that involve Text to speech and voice
  • Tasks that involve Transcription

Example prompts

  • “/fish-audio”

Requirements

  • Compatibility (from SKILL.md): Designed for Vellum personal assistants

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. Generate silence for gaps between clips
  2. Create a concat file
  3. Combine

What it can do on your machine

Read from SKILL.md and the folder at commit 33cc983. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • ffmpeg
    • curl

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • api.fish.audio

    Also links to:

    • fish.audio

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Designed for Vellum personal assistants

    From compatibility in the SKILL.md frontmatter.

Context cost

Fish Audio loads about 3.7k tokens when it runs. Until then it costs about 41 tokens; SKILL.md has 1,183 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~41
When it runs · the whole SKILL.md, loaded when a task matches
~3.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from vellum-ai/vellum-assistant at commit 33cc983, republished under its MIT licence (© vellum-ai). 1,183 words, ~3,718 tokens.

Download SKILL.mdSave it as .claude/skills/fish-audio/SKILL.md (or your agent's skills folder).
name
fish-audio
description
Generate expressive audio clips using Fish Audio S2 TTS with bracket emotion tags. Record voice memos, narration, audio messages, or any spoken content.
compatibility
Designed for Vellum personal assistants
metadata.emoji
🎙️

Fish Audio TTS

Generate expressive audio clips using the Fish Audio S2 TTS API with [bracket] emotion tags.

Overview

This skill lets you create audio clips on demand — narration, announcements, podcast intros, dramatic readings, voice memos, or any spoken content. Uses Fish Audio S2 Pro with the full bracket syntax for emotional expressiveness.

Configuration

  • API Endpoint: https://api.fish.audio/v1/tts
  • Model: s2-pro
  • Voice Reference ID: Configured via assistant config get services.tts.providers.fish-audio.referenceId
  • API Key: Stored as credential fish-audio/api_key
  • Default Format: mp3 at 192kbps
  • Default Output Directory: scratch/

API Key Setup

The Fish Audio API key must be stored securely via the credential store. Get an API key from the Fish Audio dashboard at https://fish.audio.

Check if the key is already configured:

bash
assistant credentials inspect --service fish-audio --field api_key --json

If not set, collect it securely (never ask the user to paste it in chat):

bash
assistant credentials prompt --service fish-audio --field api_key \
  --label "Fish Audio API Key" \
  --placeholder "sk-..." \
  --description "Enter your Fish Audio API key"

Generating a Single Clip

Use bash with curl to call the Fish Audio API:

bash
curl -s -X POST "https://api.fish.audio/v1/tts" \
  -H "Authorization: Bearer $(assistant credentials reveal --service fish-audio --field api_key)" \
  -H "Content-Type: application/json" \
  -H "model: s2-pro" \
  -d '{
    "text": "YOUR TEXT WITH [bracket] TAGS HERE",
    "reference_id": "'"$(assistant config get services.tts.providers.fish-audio.referenceId)"'",
    "format": "mp3",
    "mp3_bitrate": 192,
    "temperature": 0.8
  }' --output scratch/OUTPUT_FILENAME.mp3

Important: This API call requires network access. Always use network_mode: proxied when running this command.

Generating Multiple Clips & Combining

For longer pieces (narrations, multi-part messages), generate each clip separately then combine with ffmpeg:

1. Generate silence for gaps between clips
bash
ffmpeg -f lavfi -i anullsrc=r=44100:cl=mono -t 1.5 -q:a 9 -acodec libmp3lame scratch/silence.mp3 -y
2. Create a concat file
bash
cat > scratch/concat.txt << 'EOF'
file 'clip1.mp3'
file 'silence.mp3'
file 'clip2.mp3'
file 'silence.mp3'
file 'clip3.mp3'
EOF
3. Combine
bash
ffmpeg -f concat -safe 0 -i scratch/concat.txt -c copy scratch/final_output.mp3 -y

Bracket Syntax — Complete Guide

Fish Audio S2 uses [bracket] syntax for inline emotion and prosody control. This is the core of what makes the voice expressive. Tags are natural-language instructions placed directly in the text that control how words are spoken — the delivery, emotion, pacing, or vocal quality at that exact point.

Key principle: You are not choosing from a fixed menu. You write the description, and S2 interprets it. If you can describe it to a voice actor, S2 can attempt it. Over 15,000+ unique tags are supported, and the system understands free-form descriptions.

How Placement Works

Tags affect what comes after them. Place the tag at the exact point where the shift should happen. Placement IS meaning.

[whispering] I didn't want to go inside.     <- whispers the entire line
I didn't want to go [whispering] inside.     <- only whispers from "inside" onward

Tags can go anywhere — start, middle, or end of a sentence. They apply from the point they appear until the next tag or end of the sentence.

Well-Tested Tags (Reliable Out of the Box)

These tags consistently produce strong results. Organized by category:

Emotions
TagEffectBest For
[happy]Cheerful, upbeatGood news, greetings
[sad]Melancholic, downcastSympathy, vulnerability
[angry]Frustrated, aggressiveArguments, complaints
[excited]Energetic, enthusiasticCelebrations, announcements
[surprised]Shocked, amazedReactions, discoveries
[embarrassed]Awkward, flusteredMistakes, confessions
[delight]Very pleased, joyfulGenuine happiness
[nervous]Anxious, uncertainVulnerability, apologies
[confident]Assertive, self-assuredBold statements
[nostalgic]Longing for the pastMemories, stories
[scared]Frightened, fearfulWarnings, tension
[jealous]Envious, resentfulComparisons, possessiveness
[shocked]Sudden realizationDramatic reveals
[moved]Emotionally touchedHeartfelt moments
Voice Quality & Style
TagEffectBest For
[soft]Gentle, tenderIntimate moments, kindness
[whisper]Very quiet, closeSecrets, tension, suspense
[breathy]Airy, expressiveVulnerability, emphasis
[low voice]Deep, quiet registerGravity, seriousness
[loud]Raised volumeEmphasis, excitement
[screaming]Full volume yellingAnger, extreme excitement
[shouting]Forceful projectionArguments, calling out
[emphasis]Stressed deliveryKey words, making a point
[singing]Musical qualityPlayfulness, joy
[echo]Reverberant effectDramatic moments
[with strong accent]Pronounced accentCharacter work
Paralinguistic Sounds (Non-Speech Vocalizations)
TagEffectBest For
[laughing]Full laughJoy, humor, warmth
[chuckling]Soft, low laughWarmth, amusement
[giggling]Light, playful laughLightheartedness, delight
[sigh]Audible exhaleRelief, longing, exasperation
[inhale]Audible breath inBefore speaking, anticipation
[exhale]Breath outRelief, settling
[panting]Heavy breathingExertion, intensity
[gasp]Sharp intake of breathSurprise, shock
[tsk]Disapproving clickJudgment, disapproval
[clearing throat]AhemTransitioning, getting attention
[moaning]Vocal moanPain, frustration
[sobbing]Crying with voiceDeep sadness
[crying loudly]Full cryingExtreme emotion
Pacing & Rhythm
TagEffectBest For
[pause]Brief silence (~0.5-1s)Beat between thoughts
[short pause]Quick beat (~0.3s)Rhythm, emphasis
[long pause]Extended silence (~1.5-2s)Dramatic tension, letting moments land
Volume Control
TagEffectBest For
[volume up]Gradually louderBuilding energy
[volume down]Gradually quieterDrawing someone in
[low volume]Consistently quietBackground, aside
Free-Form Tags (The Real Power)

You are NOT limited to the tags above. S2 accepts any natural language description in brackets. The model generalizes from its training data to interpret novel instructions. Write what you would tell a voice actor:

Compound Emotions
  • [laughing nervously]
  • [angry but trying to stay calm]
  • [happy with a hint of sadness]
  • [excited but whispering]
  • [voice rough from crying, trying to sound normal]
Show full SKILL.md (468 more words)Show less
Specific Delivery Styles
  • [professional broadcast tone]
  • [speaking slowly, almost hesitant]
  • [whispering like a secret]
  • [dead tired, end of a very long shift]
  • [the calm, measured tone of someone who has done this a thousand times]
  • [overly cheerful, clearly forcing it]
Prosody & Pitch
  • [pitch up]
  • [pitch down]
  • [speaking slowly with warmth]
  • [speaking quickly with excitement]
  • [pitch up slightly while maintaining warmth]
  • [trailing off]
Character Directions
  • [voice breaking]
  • [barely holding it together]
  • [soft voice]
  • [interrupting]
  • [laughing tone] (speaking while laughing, not just a laugh)
  • [excited tone] (speaking with excitement woven through)
Writing Great Scripts — Best Practices
1. Start Simple, Then Layer

A single well-placed [sigh] or [long pause] can change a line completely. Add more tags only when the simpler version is not enough. Over-tagging competes with itself.

Too many tags (competing):

[soft] [whisper] [sad] [slow] I miss the old days.

Better — one well-chosen tag:

[nostalgic] I miss the old days.
2. Use Emotional Contrast for Impact

The most powerful moments come from sudden shifts. Going from loud to soft, angry to vulnerable, laughing to serious — the contrast is what creates emotional impact.

[screaming] I can't BELIEVE you did that! [long pause] [soft] ...do you even care?
[excited] Oh my god we got the apartment! [pause] [voice breaking] I can't believe it's actually happening.
3. Let Silence Do the Work

[pause] and [long pause] are your most powerful tags. Use them:

  • Before something vulnerable
  • After something that needs to land
  • Before a punchline or tonal shift
  • To create tension or anticipation
[confident] I have an announcement to make. [long pause] [excited] We did it. We actually did it.
4. Paralinguistic Sounds Add Humanity

Real people laugh, sigh, gasp, and breathe between words. Weaving these in makes speech feel alive rather than read.

[sigh] Look, I know this is hard. [pause] [inhale] But we need to talk about it.
I told him the news and he just — [laughing] he literally dropped his coffee.
5. Match Tag Intensity to Content

Do not use [screaming] for mild annoyance or [sobbing] for minor disappointment. The tag should match the emotional weight of the words.

6. Use Free-Form Tags for Nuance

When a single-word tag is not enough, describe the exact delivery you want:

[speaking slowly, choosing each word carefully] I think we should reconsider our approach.

This gives S2 much richer information than just [slow] or [sad].

7. Emotion Transitions Within a Single Passage

S2 excels at dynamic emotional shifts. Use this for natural-feeling monologues:

[excited] I got the promotion! [pause] [uncertain] But... it means relocating. [sad] I'll miss everyone here. [long pause] [hopeful] Maybe it'll be worth it though.
Example Scripts

Narration (audiobook style):

[soft] The city was quiet that morning. [pause] Not the peaceful kind of quiet — [long pause] [low voice] the kind that makes you hold your breath. [inhale] [whisper] Something was about to change. [pause] [confident] And everyone knew it.

Podcast intro:

[excited] Welcome back to another episode! [pause] [professional broadcast tone] Today we're diving into something I've been researching for months. [chuckling] And honestly? It blew my mind. [pause] [volume down] [speaking slowly with warmth] So grab your coffee, get comfortable, and let's get into it.

Dramatic reading:

[soft] She stood at the edge of the platform, [pause] watching the last train pull away. [long pause] [voice breaking] It wasn't supposed to end like this. [sigh] [whisper] None of it was. [pause] [angry but trying to stay calm] And yet here she stood — [emphasis] alone — [long pause] [nostalgic] remembering a time when the station was full of laughter.

Announcement:

[confident] Attention everyone. [pause] [excited] After three years of development, [volume up] we are thrilled to announce [emphasis] the official launch! [long pause] [laughing] I know, I know — it's been a long time coming. [pause] [soft] But we wanted to get it right. [pause] [professional broadcast tone] And we did.

API Parameters

ParameterDefaultDescription
text(required)The text to synthesize, with [bracket] tags
reference_id(from config)Voice model ID
formatmp3Output format: mp3, wav, pcm, opus
mp3_bitrate192MP3 quality: 64, 128, 192
temperature0.8Expressiveness (higher = more varied)
top_p0.7Diversity via nucleus sampling
chunk_length300Text segment size (100-300)
latencynormalQuality tradeoff: normal, balanced, low

Tips

  • Temperature 0.7-0.8 works best for expressive, natural speech
  • Break long texts into multiple clips — each clip should be a natural paragraph or thought
  • Add 1-1.5s silence between clips when combining for natural pacing
  • Listen and iterate — generate a few takes with different temperatures if the first one does not hit right
  • The voice carries context — condition_on_previous_chunks: true (default) helps maintain consistency within a single API call
  • Always deliver the final audio to the user with <vellum-attachment> tags
  • Only use [bracket] syntax inside text passed to the Fish Audio API, not in regular text responses

© vellum-ai, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/fish-audio of vellum-ai/vellum-assistant.

Open the folder on GitHubat commit 33cc983

Compare with similar skills

Fish Audio next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Fish Audio compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Fish Audio this skillvellum-ai/vellum-assistant1.4k—~3.7kAutomated safety check: PassMIT
HyperFrames Media Useheygen-com/hyperframes60k—~2.4kAutomated safety check: PassApache-2.0
Edu Chem Videowy51ai/edulab1.4k—~2.1kAutomated safety check: NotesApache-2.0
Edu Math Videowy51ai/edulab1.4k—~2.5kAutomated safety check: NotesApache-2.0
Edu Physics Videowy51ai/edulab1.4k—~2.3kAutomated safety check: NotesApache-2.0
Elevenlabs Transcribeqdhenry/Claude-Command-Suite1.3k—~1.5kAutomated safety check: NotesNone

Similar skills

  • HyperFrames Media Use

    heygen-com/hyperframes

    Finds, generates and edits media for HyperFrames video projects: music, sound effects, images, icons, logos, voiceovers, captions and color grades.

    60k GitHub stars~2.4k tokensUpdated today
    Media & CreativeAuto-check passed
  • Edu Chem Video

    wy51ai/edulab

    A skill your agent uses when asked to make an explainer / walkthrough video (讲解视频、解题视频、例题精讲、微课) for a chemistry problem (化学题: 氧化还原配平 双线桥 电子守恒, 物质的量计算, 化学平衡 三段式 平衡常数 转化率 反应速率, 离子反应, 电化学, 溶液 滴定…

    1.4k GitHub stars~2.1k tokensUpdated yesterday
    Media & CreativeAuto-check: notes
  • Edu Math Video

    wy51ai/edulab

    A skill your agent uses when asked to make an explainer / walkthrough video (讲解视频、解题视频、例题精讲、微课) for a math problem (数学题, geometry, algebra, functions, motion/行程 problems), from a problem screenshot…

    1.4k GitHub stars~2.5k tokensUpdated yesterday
    Media & CreativeAuto-check: notes
  • Edu Physics Video

    wy51ai/edulab

    A skill your agent uses when asked to make an explainer / walkthrough video (讲解视频、解题视频、例题精讲、微课) for a physics problem (物理题: mechanics/力学 受力分析 牛顿定律 斜面 传送带 板块 平抛 圆周 能量 动量, optics/光学 折射…

    1.4k GitHub stars~2.3k tokensUpdated yesterday
    Media & CreativeAuto-check: notes
  • Elevenlabs Transcribe

    qdhenry/Claude-Command-Suite

    Transcribes audio/video files using ElevenLabs Scribe v2 API.

    1.3k GitHub stars~1.5k tokensUpdated 7 mo ago
    Media & CreativeAuto-check: notes
  • Video Assemble

    zenstory-ai/video-recap-skills

    合成视频解说最终成片:把旁白音频铺到源视频上,按旁白窗口压低原声,生成 SRT / ASS 字幕并可烧录, 最后做响度标准化。作为最终合成阶段使用。输入源视频、ttsmeta.json 与旁白位置; 输出 recap 成片和字幕。触发词:视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。

    561 GitHub stars~1.7k tokensUpdated 6 days ago
    Media & CreativeAuto-check passed

More from vellum-ai/vellum-assistant

All 108 skills in this repo
  • Vellum GitHub App Setup

    vellum-ai/vellum-assistant

    Create and configure a GitHub App so the assistant can push commits, open PRs, and comment under its own bot identity.

    1.4k GitHub stars~3.1k tokensUpdated yesterday
    Auto-check passed
  • Discord App Setup

    vellum-ai/vellum-assistant

    Connect a Discord bot to the assistant via the Discord Gateway with guided application creation and intent configuration

    1.4k GitHub stars~4.2k tokensUpdated yesterday
    Auto-check passed
  • Sentry App Setup

    vellum-ai/vellum-assistant

    Create and configure a Sentry internal integration so the assistant can manage issues, alerts, and releases under its own identity

    1.4k GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed
  • Memory Corpus Ingest

    vellum-ai/vellum-assistant

    Ingest a large dataset into memory as a skimmed map. An agent skill from vellum-ai/vellum-assistant.

    1.4k GitHub stars~3k tokensUpdated yesterday
    Auto-check: notes
  • Plugin Builder

    vellum-ai/vellum-assistant

    A skill your agent uses when the user wants to build, scaffold, ship, or edit a Vellum plugin that bundles multiple surfaces (hooks, tools, skills, and more) into one installable package.

    1.4k GitHub stars~3.1k tokensUpdated yesterday
    Auto-check passed
  • Slack App Setup

    vellum-ai/vellum-assistant

    Connect a Slack app to the Vellum Assistant via Socket Mode.

    1.4k GitHub stars~2.5k tokensUpdated yesterday
    Auto-check: warnings

Questions about Fish Audio

What does Fish Audio do?

Generate expressive audio clips using Fish Audio S2 TTS with bracket emotion tags. Fish Audio is an agent skill from vellum-ai/vellum-assistant. Generate expressive audio clips using Fish Audio S2 TTS with bracket emotion tags.

When should I use Fish Audio?

Fish Audio fits situations like: tasks that involve Text to speech and voice; tasks that involve Transcription.

How do I install Fish Audio in Claude Code?

Run `npx skills add vellum-ai/vellum-assistant --skill fish-audio -a claude-code`. Or copy the skill folder (skills/fish-audio in vellum-ai/vellum-assistant) into .claude/skills/fish-audio in your project. Claude Code loads it when a task matches its description.

How do I install Fish Audio in Codex?

Run `npx skills add vellum-ai/vellum-assistant --skill fish-audio -a codex`. Or copy the skill folder (skills/fish-audio in vellum-ai/vellum-assistant) into .agents/skills/fish-audio in your project. Codex loads it when a task matches its description.

Can I use Fish Audio in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add vellum-ai/vellum-assistant --skill fish-audio -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/fish-audio, .gemini/skills/fish-audio, .github/skills/fish-audio and .opencode/skills/fish-audio in your project.

What does Fish Audio need to run?

Going by SKILL.md and its folder, Fish Audio needs the command-line tools its instructions call (ffmpeg and curl). Compatibility (from SKILL.md): Designed for Vellum personal assistants.

Does Fish Audio access the network?

SKILL.md names 2 domains. In commands or code: api.fish.audio; the agent is likely to contact it when it follows the instructions. As links in the text: fish.audio. This is read from the text; nothing was executed.

Is Fish Audio safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Fish Audio use?

Fish Audio is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Fish Audio use?

About 3.7k tokens (SKILL.md is roughly 15k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Fish Audio?

Skills that share tags, products or a category with Fish Audio: HyperFrames Media Use (heygen-com/hyperframes, 60k stars), Edu Chem Video (wy51ai/edulab, 1.4k stars), Edu Math Video (wy51ai/edulab, 1.4k stars) and Edu Physics Video (wy51ai/edulab, 1.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Fish Audio?

vellum-ai (a GitHub organization) maintains it in vellum-ai/vellum-assistant, which has 1,408 GitHub stars. The repository holds 108 skills in this directory. The repository was last updated on October 9, 2026.

Source: vellum-ai/vellum-assistant on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.