/claude-music

name: claude-music
description: >
  Music production suite using ACE-Step 1.5 via Python API. Routes /music commands
  for generation, cover, repaint, compose, analyze, export, enhance, random, and
  LoRA training. 50+ languages, up to 10-minute tracks, 48kHz stereo.
when_to_use: >
  Use when the user says /music, asks to generate a song, create music, make a
  track, cover/remix/repaint/edit audio, write lyrics, compose, analyze BPM/key,
  export for Spotify/TikTok, master audio, train a LoRA, or mentions ACE-Step.
compatibility: >
  Requires ACE-Step 1.5 installed locally + NVIDIA GPU with ≥4 GB VRAM
  (≥12 GB recommended). Path configured in skills/claude-music/config.json.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep

claude-music — AI Music Production for Claude Code

Quick Reference

| Command | What it does | |---------|-------------| | `/music` | Interactive mode — describe what you want | | `/music generate` | Text/lyrics to full song (text2music) | | `/music cover` | Style transfer from reference audio | | `/music repaint` | Edit a specific section of a song | | `/music extract` | Separate tracks/stems (base model only) | | `/music lego` | Add instrument layer (base model only) | | `/music complete` | Continue/extend audio (base model only) | | `/music compose` | Songwriting: craft caption + lyrics + params | | `/music analyze` | BPM, key, loudness, duration analysis | | `/music export` | Platform-optimized export (Spotify, YouTube, etc.) | | `/music enhance` | Post-processing: normalize, denoise, stem separate | | `/music random` | Quick random generation with smart defaults | | `/music library` | Browse and manage generated music | | `/music web` | Local browser dashboard: generate, play, rate | | `/music lora` | LoRA/LoKr fine-tuning management | | `/music setup` | Verify installation and dependencies |

Orchestration Logic

Command Routing

When the user provides a specific command, load the matching sub-skill:

• `/music generate` or intent is create song/make music/text-to-music/lyrics-to-music → Read `skills/claude-music-generate/SKILL.md`
• `/music cover` or intent is cover/style transfer/remake/version of → Read `skills/claude-music-cover/SKILL.md`
• `/music repaint` or intent is edit section/fix chorus/change part/modify section → Read `skills/claude-music-repaint/SKILL.md`
• `/music compose` or intent is write lyrics/craft caption/plan song/songwriting → Read `skills/claude-music-compose/SKILL.md`
• `/music analyze` or intent is BPM/key detection/loudness/audio info → Read `skills/claude-music-analyze/SKILL.md`
• `/music export` or intent is export for Spotify/YouTube/platform/format conversion → Read `skills/claude-music-export/SKILL.md`
• `/music enhance` or intent is normalize/denoise/stem separate/master → Read `skills/claude-music-enhance/SKILL.md`
• `/music random` or intent is quick generation/surprise me/random song → Read `skills/claude-music-random/SKILL.md`
• `/music library` or intent is list songs/browse output/manage music → Read `skills/claude-music-library/SKILL.md`
• `/music web` or intent is dashboard/browser app/web UI/visual player → Read `skills/claude-music-web/SKILL.md`
• `/music lora` or intent is train/fine-tune/LoRA/custom style → Read `skills/claude-music-lora/SKILL.md`
• `/music setup` → Run `bash ~/.claude/skills/claude-music/scripts/setup.sh`

Interactive Mode

When user says `/music` without arguments or describes a task in natural language: 1. Run `bash ~/.claude/skills/claude-music/scripts/check_deps.sh` to verify tools 2. Run `bash ~/.claude/skills/claude-music/scripts/detect_gpu.sh` for GPU info 3. Identify intent from the user's description 4. Route to the appropriate sub-skill 5. If ambiguous, ask the user to clarify

Multi-Step Pipelines

For complex requests spanning multiple sub-skills (e.g., "compose lyrics, generate a song, then export for Spotify"): 1. Compose lyrics/caption with `/music compose` 2. Generate with `/music generate` using composed output 3. Export with `/music export` 4. Clean up temp files

Generate-Listen-Iterate Loop

After any generation: 1. Present output file paths and metadata (seed, duration, format) 2. Suggest playback: `ffplay -nodisp -autoexit "<path>"` 3. Ask if user wants to:

• **Re-generate** with different seed (same params)
• **Refine** params (adjust caption, BPM, quality)
• **Repaint** a specific section
• **Cover** to change style while keeping structure
• **Export** for a platform

Safety Rules — MANDATORY

1. **Run preflight before writes**: `bash ~/.claude/skills/claude-music/scripts/preflight.sh "$INPUT" "$OUTPUT"` 2. **Never overwrite source files** — all operations produce new files 3. **Check VRAM before GPU operations**: `bash ~/.claude/skills/claude-music/scripts/detect_gpu.sh` 4. **Confirm before**: batch >4 generations, operations with --quality max (3-5 min) 5. **Auto-execute without confirmation**: single generation (draft/standard), analysis, format conversion, setup 6. **Temp files**: `/tmp/claude-music/` with cleanup trap 7. **Output directory**: `~/Music/claude-music-output/` (auto-created)

ACE-Step Configuration

• **Installation**: Set `ace_step_dir` in `config.json` (default: see config.json)
• **Invocation**: `bash ~/.claude/skills/claude-music/scripts/music_engine.sh <command> [args]`
• **Config**: `~/.claude/skills/claude-music/config.json`
• **Output**: `~/Music/claude-music-output/`

Quality Presets

| Preset | Model | LM | Steps | Speed | Use for | |--------|-------|----|-------|-------|---------| | `draft` | turbo | none | 8 | ~15s | Quick exploration, batch 4 variants | | `standard` | turbo | none | 8 | ~15s | Default, batch 2 variants | | `high` | turbo | 1.7B LM | 8 | ~25s | Better lyrics/structure, thinking mode | | `max` | base | 1.7B LM | 65 | ~3-5min | Highest quality, single output |

VRAM Management (RTX 5070 Ti — 16GB)

| Configuration | VRAM | Offload | Notes | |--------