agentleFS
full-aigc-skillsfull-aigc-skills/minimax-skills/skills/minimax-music-playlist/SKILL.md

minimax-music-playlist

Skill4 starsChanged 59 days agoApache-2.0View on GitHub

Generate personalized music playlists by analyzing the user's music taste and generation feedback history. Triggers on any request involving playlist generation, music taste profiling, or personalized music recommendations. Supports multilingual triggers — match equivalent phrases in any language.

  • Installs packages

4 other projects use a version of this, 3 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. 19 are common, 0 are distinctive, and 8 are very specific to this project.

  • 19

    Common

    Most of the 4 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    NOT the user's UI language.

    line 31
  2. Very specific:

    Search for existing exports: find ~ -maxdepth 4 -name "my_spotify_data.zip" -o -name "Streaming_History_Audio_*.json" 2>/dev/null

    line 60
  3. Common:

    If found, ask the user if they want to use it

    line 61
  4. Very specific:

    If ZIP, unzip and locate Spotify Extended Streaming History/Streaming_History_Audio_*.json

    line 62
  5. Very specific:

    If not found, open the Spotify privacy page: open https://www.spotify.com/account/privacy/

    line 63
  6. Very specific:

    Do NOT use or store ip_addr or other sensitive fields.

    line 78
  7. Very specific:

    Check if Apple Music is available (try osascript query)

    line 87
  8. Common:

    Ask if the user has a Spotify data export ZIP to provide

    line 88
  9. Common:

    If no sources available, ask the user to describe their taste manually

    line 89
  10. Common:

    Privacy rule: Never show raw track lists to the user.

    line 91
  11. Very specific:

    Look up artists in the local mapping table at <SKILL_DIR>/data/artist_genre_map.json — this table covers 20,000 popular artists with …

    line 108
  12. Common:

    If MusicBrainz returns no results, skip the artist

    line 114
  13. Common:

    If a profile less than 7 days old exists, reuse it (offer rescan option)

    line 118
  14. Common:

    If older or missing, rebuild

    line 119
  15. Common:

    If invoked by an agent with clear parameters, skip the confirmation and proceed.

    line 131
  16. Common:

    If invoked by a user directly, ask if the profile looks right before continuing.

    line 132
  17. Common:

    If the theme was already provided in the invocation (e.g., the agent or user said "generate a late night chill playlist"), use it directly …

    line 141
  18. Common:

    After showing the plan, proceed directly to generation — no confirmation needed.

    line 205
  19. Very specific:

    Use mmx music generate to create all songs.

    line 212
  20. Common:

    If a song fails, retry once before skipping.

    line 236
  21. Common:

    Do NOT include text or song titles in the image prompt

    line 260
  22. Common:

    Only play the songs generated in this session — if the directory has old files from a previous run, clean them out first or filter by the …

    line 276
  23. Common:

    If no player is found, just show the file paths.

    line 278
  24. Common:

    If the user is present, ask for feedback (per-song or overall).

    line 298
  25. Very specific:

    If asked to play a previous playlist: ls ~/Music/minimax-gen/playlists/, show available ones, and play the selected one.

    line 306
  26. Common:

    No hardcoded scripts: Write scanning/analysis scripts on the fly as needed.

    line 316
  27. Common:

    Use Python stdlib only. Cache results to avoid redundant work.

    line 317

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

MiniMax Music Playlist — Personalized Playlist Generator

Scan the user's music taste, build a taste profile, generate a personalized playlist, and create an album cover. This skill is designed for both agent and direct user invocation — adapt interaction style to context.

Prerequisites

  • mmx CLI — music & image generation. Install: npm install -g mmx-cli. Auth: mmx auth login --api-key <key>.
  • Python 3 — for scanning scripts you write on the fly (stdlib only, no pip).
  • Audio player — mpv, ffplay, or afplay (macOS built-in).

Language

Detect the user's language from their message. All user-facing text must be in the same language as the user's prompt — do not mix languages. If the user writes in Chinese, all output (profile summary, theme suggestions, playlist plan, playback info) must be fully in Chinese. If in English, all in English.

All mmx generation prompts should be in English for best quality. Each song's lyrics language follows its genre (K-pop → Korean, J-pop → Japanese, etc.), NOT the user's UI language.


Workflow

1. Scan local music apps → 2. Build taste profile → 3. Plan playlist
→ 4. Generate songs (mmx music) → 5. Generate cover (mmx image) → 6. Play → 7. Save & feedback

Step 1: Gather Music Listening Data

Collect the user's listening data from available sources.

Supported sources:

SourceMethodData format
Apple Musicosascript to query Music.app (official AppleScript interface)Track name, artist, album, genre, play count
SpotifyUser exports their own data via Spotify Privacy SettingsJSON files in ZIP (Streaming_History_Audio_*.json)
Manual inputUser describes their taste directlyFree text

Spotify data export flow: Spotify does not store useful data locally. To include Spotify listening history, first check if the user already has a Spotify data export:

  1. Search for existing exports: find ~ -maxdepth 4 -name "my_spotify_data.zip" -o -name "Streaming_History_Audio_*.json" 2>/dev/null
  2. If found, ask the user if they want to use it
  3. If ZIP, unzip and locate Spotify Extended Streaming History/Streaming_History_Audio_*.json
  4. If not found, open the Spotify privacy page: open https://www.spotify.com/account/privacy/
  5. Tell the user to log in, scroll to "Download your data", and click "Request data"
  6. Skip Spotify for now and continue with other sources — tell the user they can re-run the playlist skill after the data export arrives (usually a few days)

Spotify data format: The export contains Streaming_History_Audio_YYYY.json files (one per year), each is a JSON array of listening events. Key fields to extract:

  • master_metadata_album_artist_name — artist name
  • master_metadata_track_name — track name
  • master_metadata_album_album_name — album name
  • ms_played — playback duration in milliseconds (use as weight: longer = stronger signal)
  • ts — timestamp

Filter out entries where ms_played < 30000 (less than 30 seconds, likely skipped). Do NOT use or store ip_addr or other sensitive fields.

What to extract from each source:

  • Track names + artist names (primary signal)
  • Playlist names and membership (e.g., a playlist named "Chinese Traditional" tells you genre preference)
  • Play counts or streaming duration if available (weight frequently played tracks higher)
  • Scene/mood tags if available

Approach:

  1. Check if Apple Music is available (try osascript query)
  2. Ask if the user has a Spotify data export ZIP to provide
  3. If no sources available, ask the user to describe their taste manually

Privacy rule: Never show raw track lists to the user. Only show aggregated stats.


Step 2: Build Taste Profile

From the scanned data, build a taste profile covering:

  • Genre distribution — what styles the user listens to (e.g., J-pop 20%, R&B 15%, Classical 10%)
  • Mood tendencies — emotional tone preferences (melancholic, energetic, calm, romantic, etc.)
  • Vocal preference — male vs female voice ratio
  • Tempo preference — slow / moderate / upbeat / fast distribution
  • Language distribution — zh, en, ja, ko, etc.
  • Top artists — most listened artists

How to infer genre/mood from artist names: Most raw data only has artist + track names without genre tags. To enrich this:

  1. Look up artists in the local mapping table at <SKILL_DIR>/data/artist_genre_map.json — this table covers 20,000 popular artists with pre-mapped genres, vocal type, and language
  2. For artists not in the mapping table, query the MusicBrainz API: https://musicbrainz.org/ws/2/artist/?query=artist:<name>&fmt=json — extract genre tags from the response; respect rate limit (1 req/sec) — cache results to <SKILL_DIR>/data/artist_cache.json to avoid re-querying
  3. If MusicBrainz returns no results, skip the artist

Profile caching:

  • Save profile to <SKILL_DIR>/data/taste_profile.json
  • If a profile less than 7 days old exists, reuse it (offer rescan option)
  • If older or missing, rebuild

Show user a summary:

Your Music Profile:
  Sources: Apple Music 230 | Spotify 140
  Genres: J-pop 20% | R&B 15% | Classical 10% | Indie Pop 9%
  Moods: Melancholic 25% | Calm 20% | Romantic 18%
  Vocals: Female 65% | Male 35%
  Top artists: Faye Wong, Ryuichi Sakamoto, Taylor Swift, Jay Chou, Taeko Onuki

If invoked by an agent with clear parameters, skip the confirmation and proceed. If invoked by a user directly, ask if the profile looks right before continuing.


Step 3: Plan Playlist

Ask the user for a theme/scene before generating. This is the one interactive step in the workflow. All other steps run autonomously.

If the theme was already provided in the invocation (e.g., the agent or user said "generate a late night chill playlist"), use it directly and skip the question. Otherwise, ask:

What theme would you like for your playlist? Here are some suggestions:

- "Late night chill" — relaxing slow songs
- "Commute" — upbeat and energizing
- "Rainy day" — melancholic & cozy
- "Surprise me" — random based on your taste

Or tell me your own vibe!

Once the user picks a theme, proceed automatically through generation, cover, playback, and saving — no further confirmations needed.

Determine playlist parameters:

  • Theme/mood — from user input, or default to top mood from profile
  • Song count — from user input, or default to 5
  • Genre mix — weighted by profile, with variety

Per-song lyrics language follows genre:

GenreLyrics language
K-pop, Korean R&B/balladKorean
J-pop, city pop, J-rockJapanese
C-pop, Chinese-style, MandopopChinese
Western pop/indie/rock/jazz/R&BEnglish
Latin pop, bossa novaSpanish/Portuguese
Instrumental, lo-fi, ambientNo lyrics (--instrumental)

Embed language naturally into the mmx prompt via vocal description:

  • Good: "A melancholy Chinese R&B ballad with a gentle introspective male voice, electric piano, bass, slow tempo"
  • Bad: "R&B ballad, melancholy... sung in Chinese"

Show the playlist plan before generating. Display each song with two lines: the first line shows genre, mood, and vocal/language tag; the second line shows a short description of the song. All user-facing text (plan, descriptions, moods, labels) must be in the same language as the user's prompt. Only the actual --prompt passed to mmx should be in English — this is internal and should NOT be shown to the user. Example:

Playlist Plan: Late Night Chill (5 songs)

1. Neo-soul R&B — introspective  English/male vocal
   A mellow neo-soul R&B ballad with warm baritone, electric piano, smooth bass

2. Lo-fi hip-hop — dreamy  Instrumental
   Dreamy lo-fi with sampled piano, vinyl crackle, soft electronic drums

3. Smooth jazz — romantic  English/female vocal
   Silky female voice, saxophone, piano, romantic starlit night

4. Indie folk — melancholic  English/male vocal
   Tender male voice, acoustic guitar, harmonica, quiet solitude

5. Ambient electronic — calm  Instrumental
   Soft synth pads, gentle arpeggios, dreamy atmosphere

After showing the plan, proceed directly to generation — no confirmation needed. The user has already chosen the theme; the plan is shown for transparency, not approval.


Step 4: Generate Songs

Use mmx music generate to create all songs. Generate concurrently (up to 5 in parallel).

# Example: 5 songs in parallel
mmx music generate --prompt "<english_prompt_1>" --lyrics-optimizer \
  --out ~/Music/minimax-gen/playlists/<name>/01_desc.mp3 --quiet --non-interactive &
mmx music generate --prompt "<english_prompt_2>" --instrumental \
  --out ~/Music/minimax-gen/playlists/<name>/02_desc.mp3 --quiet --non-interactive &
# ... more songs ...
wait

Key flags:

  • --lyrics-optimizer — auto-generate lyrics from prompt (for vocal tracks)
  • --instrumental — no vocals
  • --vocals "<description>" — vocal style (e.g., "warm Chinese male baritone")
  • --genre, --mood, --tempo, --instruments — fine-grained control
  • --quiet --non-interactive — suppress interactive output for batch mode
  • --out <path> — save to file

File naming: <NN>_<short_desc>.mp3 (e.g., 01_rnb_midnight.mp3)

Output directory: ~/Music/minimax-gen/playlists/<playlist_name>/

If a song fails, retry once before skipping. Log the error and continue with the rest.


Step 5: Generate Album Cover

Generate the album cover concurrently with the songs (Step 4), not after. Launch the mmx image generate call in parallel with the song generation calls.

Craft a prompt that reflects the playlist's theme, mood, and genre mix. The image should feel like an album cover — artistic, evocative, not literal.

mmx image generate \
  --prompt "<cover description based on playlist theme and mood>" \
  --aspect-ratio 1:1 \
  --out-dir ~/Music/minimax-gen/playlists/<playlist_name>/ \
  --out-prefix cover \
  --quiet

Prompt guidance:

  • Abstract/artistic style works best for album covers
  • Reference the dominant mood and genre (e.g., "dreamy late-night cityscape, neon reflections, lo-fi aesthetic")
  • Do NOT include text or song titles in the image prompt
  • Aspect ratio should be 1:1 (square, standard album cover)

Step 6: Playback

Detect an available player and play the playlist in order:

PlayerCommandControls
mpvmpv --no-video <file>q skip, Space pause, arrows seek
ffplayffplay -nodisp -autoexit <file>q skip
afplayafplay <file>Ctrl+C skip

Play all .mp3 files in the playlist directory in filename order. Only play the songs generated in this session — if the directory has old files from a previous run, clean them out first or filter by the known filenames. If no player is found, just show the file paths.


Step 7: Save & Feedback

Save playlist metadata to <playlist_dir>/playlist.json:

{
  "name": "Late Night Chill",
  "theme": "late night chill",
  "created_at": "2026-04-11T22:00:00",
  "song_count": 5,
  "cover": "cover_001.png",
  "songs": [
    {"index": 1, "filename": "01_rnb_midnight.mp3", "prompt": "...", "rating": null}
  ]
}

If the user is present, ask for feedback (per-song or overall). Update the taste profile's feedback section with liked/disliked genres and prompts to improve future playlists.


Replaying Playlists

If asked to play a previous playlist: ls ~/Music/minimax-gen/playlists/, show available ones, and play the selected one.


Notes

  • Agent vs user invocation: The theme/scene question (Step 3) is the single interactive touchpoint. If the theme is already provided in the invocation, skip the question. Everything else runs autonomously.
  • No hardcoded scripts: Write scanning/analysis scripts on the fly as needed. Use Python stdlib only. Cache results to avoid redundant work.
  • Skill directory: <SKILL_DIR> = the directory containing this SKILL.md file. Data/cache files go in <SKILL_DIR>/data/.
  • All mmx prompts in English for best generation quality.
<!-- QUALITY_BASELINE_V1 -->

When to use(什么时候使用)

当用户需要 只读发现、检查或汇总当前资源状态 时加载本技能。先从请求中提取目标、输入、约束、交付格式和验收标准;描述摘要为:Generate personalized music playlists by analyzing the user's music taste and generation feedback history. Triggers on any request involving playlist generation, music taste profiling, or personalized music recommendations. Supports multilingual triggers — match equivalent phrases in any language.。

Rules

  • 先读后写:先确认当前状态与真实能力,再执行会改变外部状态的动作。
  • 权限最小化:只使用完成当前步骤所需的文件、工具、账户与网络范围。
  • 证据优先:运行结果、资源 ID、版本、哈希或测试输出缺失时,明确标记为 NOT_VERIFIED。
  • 幂等优先:保留请求标识与阶段状态;结果不明确时先查询,不进行盲目重试。
  • 隐私安全:日志、示例、回执和错误信息不得包含 token、cookie、密钥或个人敏感数据。

Workflow

Step 1:澄清意图

确认本技能是否匹配目标;若只是相邻需求,交给更精确的技能。

Step 2:执行预检

确认查询范围、身份上下文、分页上限和输出字段;任一关键条件未知时停止在只读阶段。

Step 3:形成计划

列出将调用的工具、会改变的对象、成功标准以及失败后的安全退出方式。

Step 4:执行动作

执行有界只读查询并保留来源标识;每个外部调用均保留可关联的状态或回执。

Step 5:验证交付

返回资源标识、查询条件、分页状态和未验证项,并把事实、推断和未验证项分开陈述。

Validation checklist

  • 技能触发条件与用户意图一致,没有把相邻任务误路由到本技能。
  • 输入、目标对象、版本和输出位置均已明确,且没有使用猜测值替代必填值。
  • 所有写入、付费、发布或不可逆动作都在用户授权范围内。
  • 结果已用独立检查验证;仅有“命令成功”或“文件存在”不算完整验收。
  • 输出包含实际证据、失败/跳过项、剩余风险和可执行的下一步。

Gotchas

  1. 把计划当结果:文档或提示词不等于真实执行;必须标明实际运行层级。
  2. 错误重试:超时或响应丢失可能已经产生远端状态,先查询再决定是否重试。
  3. 隐式扩大范围:批量、全量、发布、覆盖和付费不是普通读写的自然延伸。
  4. 版本漂移:引用外部资源时记录版本、tag 或提交;不要把可变分支当发布证据。
  5. 证据过期:缓存、旧截图和历史测试不能证明当前环境;在交付前刷新关键证据。

不适用与边界

不创建、不修改、不删除资源;若后续需要写操作,先交给对应写入技能并重新确认。 如果请求需要别的技能,不复制其正文;按技能名称进行交接,并保留当前任务上下文。

Progressive disclosure

  • 需要确定输入/输出、状态和授权点时,读取 references/workflow-contract.md。
  • 需要交付前自检时,读取 references/validation-checklist.md。
  • 遇到超时、部分成功或恢复场景时,读取 references/error-recovery.md。
  • 首次运行、拒绝越权和失败恢复分别参考 examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.