Guide · Agent skill
How to use the Music Generation agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The music-generation skill lets an AI agent write and produce a short song, jingle or instrumental track from a plain-language description, and return it as an MP3 file. It is useful for creators and marketers who need draft background music or a theme song for a video, podcast or sonic logo. By the end of this guide you will know what the skill does, how to install it, how to ask for music in natural language, and what it needs to run.
Music Generationbytedance/deer-flow · MIT Download the skill Quick start
- 1Download the ZIP. Download the music-generation skill ZIP from this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. You can also upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Set your MiniMax key. Set MINIMAX_API_KEY to your MiniMax interface key. The script cannot run without it.
- 4Make sure Python and requests are available. Confirm Python 3 is installed with the requests library and that the machine can reach api.minimaxi.com.
- 5Describe the music you want. Ask in plain language, covering style, mood, scene, vocals or instrumental, and any lyrics.
- 6Review the MP3. Listen to the returned file in the outputs folder and ask for changes to style or lyrics if needed.
What is an agent skill and what does this one do?
An agent skill is a folder of instructions and optional scripts that an AI agent can load when a task matches its description. This skill is named music-generation and is meant for requests to generate, create, compose or produce music or songs, such as background music, theme songs, jingles or instrumental tracks.
The agent turns your request into a small JSON spec file with a style and mood prompt and, optionally, lyrics. It then sends that spec to the MiniMax music API through a bundled Python script, which calls the /v1/music_generation endpoint and saves the returned audio as an MP3.
Install the music-generation skill
Download the skill ZIP from this page. Then choose one of the two installation routes below.
For a personal install across all your projects, unzip the file into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Either way the skill folder should contain SKILL.md and scripts/generate.py.
In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Set up the requirements
The script needs Python 3 with the requests library, a MiniMax API key, and network access to api.minimaxi.com. Without the key the script cannot run.
The skill reads these environment variables. MINIMAX_API_KEY is required. MINIMAX_API_HOST is optional and defaults to https://api.minimaxi.com. MINIMAX_MUSIC_MODEL is optional and defaults to music-2.6-free, which the source says works for all API-key users; paid or Token-Plan users can set music-2.6 for higher limits.
- Python 3 with the requests library
- MINIMAX_API_KEY set to your MiniMax interface key (required)
- Network access to api.minimaxi.com
- Optional: MINIMAX_API_HOST and MINIMAX_MUSIC_MODEL
Ask for music with natural requests
You do not need to name the skill. Describe the music you want, including the style, mood and scene. Say whether you want vocals or an instrumental. If you have lyrics, include them; if not, the model can write them from your prompt.
The agent decides whether to supply lyrics or let the model write them, and it will usually ask about language and vocals first if those are unclear.
- "Make a 30-second upbeat jingle for a coffee shop podcast intro."
- "Compose an instrumental lo-fi track for background music in my tutorial videos."
- "Write a theme song with these lyrics: ... in indie folk style."
- "Create a melancholic indie folk song about walking home in the rain, with auto-written lyrics."
How the agent builds the spec and runs generation
The agent writes a JSON file in /mnt/user-data/workspace/ named after the song. The prompt field holds style, mood and scene. The lyrics field holds the sung words, with \n between lines and structure tags such as [Verse] and [Chorus]. Setting is_instrumental to true produces a track with no vocals.
If you provide lyrics, those are sung. If you set is_instrumental to true, no vocals are generated. If you give neither, the model writes lyrics from the prompt. The agent then runs the script with --prompt-file for the spec and --output-file for the MP3.
- title (optional): a readable name
- prompt (required): style, mood and scene
- lyrics (optional): sung words with structure tags
- is_instrumental (optional): true for a pure instrumental
python /mnt/skills/public/music-generation/scripts/generate.py \
--prompt-file /mnt/user-data/workspace/rainy-night-cafe.json \
--output-file /mnt/user-data/outputs/rainy-night-cafe.mp3Check the output and iterate
The script saves the result as an MP3, typically in /mnt/user-data/outputs/. Before saving, it checks that the returned audio decodes to non-empty bytes and has an ID3 tag header or MPEG frame signature. The source describes this as a header sanity check, not full audio decoding, so listen to the file yourself before using it.
If the API returns no audio, the script reports "MiniMax returned no audio data". If the audio decodes to empty bytes, it reports "MiniMax audio decoded to empty bytes". Rejected audio is not written, and an existing output file is kept. The agent shares the file with you and can revise the style or lyrics.
- Keep style words in prompt and put sung words in lyrics
- For non-English songs, write lyrics in the target language
What people use it for
- Background music for YouTube videos, tutorials or presentations
- Short jingles or sonic logos for a brand prototype
- Theme songs for a podcast or series, with lyrics you wrote
- Quick instrumental beds for social media clips
- Draft songs where the model writes lyrics from a mood description
Frequently asked questions
How do I install the music-generation agent skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
What do I need to run the music generation skill?
You need Python 3 with the requests library, a MiniMax API key set as MINIMAX_API_KEY, and network access to api.minimaxi.com. The script cannot run without the API key.
Is the music-generation skill free?
The source does not state pricing or licence terms for MiniMax output. The skill itself is listed under the MIT licence, and the MiniMax default model is music-2.6-free, but check MiniMax's own terms for costs and usage rights.
Can I use the generated songs commercially?
The skill does not explain who owns or may use the output under MiniMax's terms. Check those terms before releasing any commercial music made with it.
Are my prompts and lyrics private?
No. The prompt and lyrics are sent to a third-party cloud API, MiniMax, so do not use this skill if you must keep that text private.
Why does generation fail with 'MiniMax returned no audio data'?
That message means the API response contained no audio. Check that MINIMAX_API_KEY is set correctly and that the machine can reach api.minimaxi.com, then try again.
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 need quick draft music, jingles or instrumental beds for videos, podcasts or prototypes, and you have a MiniMax API key. Pick another option if you need guaranteed commercial rights to the output, or if your lyrics and prompts must stay private.
Download the skill