A complete AI music production workflow for Suno. Install as a Claude Code plugin or clone the repo and start making albums.
Note
This is a personal project I built to streamline my own music production workflow with Claude Code and Suno. It's being shared publicly in case others find it useful. Active development happens on the develop branch — main only receives tested, stable releases.
If you run into issues, feel free to open an issue or submit a PR.
Warning
Claude Code Max plan recommended ($200/month). This plugin uses 50 specialized skills that spawn subagents across Opus, Sonnet, and Haiku models. Session startup, automatic lyric reviews, multi-agent research workflows, and full album production pipelines are all token-intensive. The standard Pro plan will hit rate limits quickly during any multi-track session.
This is a collection of 50 specialized skills that turn Claude Code into a full music production assistant. It handles everything from album concept development to lyrics, Suno prompts, mastering, and release.
What you get:
- Structured workflow from idea to released album
- Lyrics with prosody checks, rhyme analysis, and pronunciation fixes
- Optimized Suno V5 prompts for better generations
- Research tools for documentary/true-story albums
- Audio mastering scripts for streaming platforms
- Quality gates at every stage
See CHANGELOG.md for full history.
| Version | Highlights |
|---|---|
| 0.69 | Target Duration planning — per-album/track duration targets threaded through planning, writing, prompting, and review; duration-to-word-count mapping |
| 0.68 | Suno target duration guidance — word count targets updated for 3:30–5:00 min tracks, instrumental tag runtime, under-200-word "too short" flag |
| 0.67 | Sheet music URL persistence to frontmatter, prepare_singles.py replaces fix_titles.py, songbook title page/TOC/footers, musicxml key naming |
| 0.66 | 12-stem pipeline (full Suno split_stem), guitar/keyboard/strings/brass/woodwinds/percussion as first-class stems, instrument-name keyword routing, percussion/drums separation fix |
| 0.65 | Reverted 0.61 audio pipeline changes (originals layout, fade-out, character effects) — keeps 0.62–0.63 infrastructure |
| 0.63 | Venv health check, debug logging, reset mastering tool, cleanup legacy venvs |
| 0.62 | develop/main branch model, CI streamlined to Python 3.11, plugin version in /about |
| 0.60 | Suno stem discovery + mastering auto-recovery for dynamic range issues |
| 0.59 | mix-engineer skill — per-stem audio polish pipeline (noise reduction, EQ, compression, click removal) |
| 0.58 | ship skill — automated code release pipeline (branch → PR → CI → merge → version bump → release) |
| 0.55 | 4 lyrics analysis MCP tools — syllable counting, Flesch readability, rhyme scheme detection, section structure validation |
| 0.54 | extract_distinctive_phrases MCP tool + plagiarism-checker skill — web search + LLM lyrics plagiarism checking |
| 0.53 | check_cross_track_repetition MCP tool — detect overused words/phrases across album tracks |
| 0.52 | get_python_command MCP tool, skills migrated from bare python3 to MCP tools |
| 0.51 | Mirrored path structure for audio/documents, per-track stems subfolders in import-audio |
| 0.50 | Audio QC tool (7 checks), qc_audio and master_album MCP tools, end-to-end mastering pipeline |
| 0.49 | K-pop genre research with 27 artist deep-dives, artist blocklist, Suno V5 K-pop tips |
| 0.48 | Promo writer skill for social media copy generation, best practices reference, Twitter hashtag fixes |
| 0.47 | 9 processing MCP tools, Suno auto-fill clipboard + Tampermonkey script, album streaming block |
| 0.45 | Promo reviewer skill for social media copy polish, cross-file count consistency fixes |
| 0.43 | MCP server expanded to 30 tools, 160 integration tests, 843 total tests |
| 0.39 | Setup skill with auto dependency detection, improved MCP error handling |
| 0.38 | MCP server for instant state queries, Claude 4.6 upgrade, lyric writer examples |
| 0.37 | Security hardening (6 fixes), prompt quality improvements across 30+ skill/reference files |
| 0.34 | Python 3.9–3.12 CI matrix, bandit/pip-audit security scanning, path traversal fixes |
| 0.33 | Pronunciation table enforcement — table entries must be applied to Suno lyrics |
| 0.29 | Suno verse length limits by genre and BPM across all 67 genres |
| 0.25 | Genre-specific lyric conventions (rhyme schemes, structures) for all 67 genres |
| 0.21 | 46 artist deep-dives, genre keyword indexes for lazy-loading |
| 0.20 | Python logging, progress bars, concurrent processing, 180 tests at 91% coverage |
| 0.18 | State cache layer — fast session startup (2-3 file reads vs 50-220) |
| 0.17 | Test automation, genre INDEX, model strategy docs, 64 quick-start guides |
Want to know how this project came together? Read the full story:
The Story Behind bitwize-music
Not required, but I'd love to hear what you create with this. Drop a tweet with your album:
#ClaudeCode #SunoAI #AIMusic @bitwizemusic
# Add the marketplace
/plugin marketplace add bitwize-music-studio/claude-ai-music-skills
# Install the plugin
/plugin install bitwize-music@claude-ai-music-skillsPlatform: Linux or macOS (Windows users: use WSL)
Core workflow (album planning, lyrics, Suno prompts):
- Claude Code
- That's it
MCP server (fast state queries, auto-enabled):
- Python 3.10+
mcp[cli]>=1.2.0,pyyaml— install with:pip install --user "mcp[cli]>=1.2.0" pyyaml
Audio mastering (optional):
- Python 3.8+
- pip packages:
matchering,pyloudnorm,scipy,numpy,soundfile
Document hunting (optional, for research):
- Python 3.8+
- Playwright (
pip install playwright && playwright install chromium)
Install all optional dependencies at once:
pip install --user -r requirements.txt
pip install --user -r requirements.txt
playwright install chromiumClaude Code will prompt you to install these when needed.
New to the plugin? Follow these steps to get up and running:
-
Install the plugin
/plugin marketplace add bitwize-music-studio/claude-ai-music-skills /plugin install bitwize-music@claude-ai-music-skills
-
Run setup assistant (detects your environment and installs dependencies)
/bitwize-music:setup
-
Configure your workspace
/bitwize-music:configure
-
Edit config with your settings
nano ~/.bitwize-music/config.yaml # or your preferred editor
Required settings:
artist.name- Your artist/project name (e.g., "bitwize", "my-band")paths.content_root- Where albums will be stored (e.g.,~/music-projects)paths.audio_root- Where mastered audio goes (e.g.,~/music-projects/audio)paths.documents_root- Where research PDFs go (e.g.,~/music-projects/documents)
-
(Optional) Install mastering dependencies
pip install matchering pyloudnorm scipy numpy soundfile
Only needed if you plan to master audio for streaming platforms.
-
(Optional) Install document hunter dependencies
pip install playwright playwright install chromium
Only needed if you plan to do research for documentary/true-story albums.
-
Start Claude Code and begin
claude
Then say: "Let's make a new album"
That's it! Claude will create the album directory structure and guide you through the 7 planning phases.
Next steps:
- Read the Tutorial below for a walkthrough
- Run
/bitwize-music:helpto see all available skills - Check the Troubleshooting section if you hit issues
┌─────────┐ ┌──────────┐ ┌───────┐ ┌──────────┐ ┌────────┐ ┌─────────┐
│ Concept │ -> │ Research │ -> │ Write │ -> │ Generate │ -> │ Master │ -> │ Release │
└─────────┘ └──────────┘ └───────┘ └──────────┘ └────────┘ └─────────┘
│ │ │ │ │ │
v v v v v v
Plan album Gather sources Create lyrics Generate on Optimize Upload &
Define theme Verify facts Check quality Suno V5 audio for distribute
Tracklist Citations Pronunciation Iterate streaming to platforms
Each phase has specialized skills and quality gates:
| Phase | What Happens | Skills Used |
|---|---|---|
| Concept | Define album theme, tracklist, sonic direction | /bitwize-music:album-conceptualizer |
| Research | Gather sources (for true-story albums) | /bitwize-music:researcher, /bitwize-music:document-hunter |
| Write | Create lyrics with quality checks | /bitwize-music:lyric-writer, /bitwize-music:pronunciation-specialist |
| Generate | Create tracks on Suno | /bitwize-music:suno-engineer |
| Polish | Fix Suno artifacts, per-stem cleanup | /bitwize-music:mix-engineer |
| Master | Optimize audio for streaming | /bitwize-music:mastering-engineer |
| Release | QA, upload, distribute | /bitwize-music:release-director |
Skills are invoked with /bitwize-music:skill-name. They can be called explicitly or Claude will use them automatically when relevant.
Example explicit call:
/bitwize-music:lyric-writer Write verse 2 for track 3
Example automatic use:
When you say "let's write the lyrics for track 1", Claude automatically applies /bitwize-music:lyric-writer expertise including rhyme checks, prosody analysis, and pronunciation scanning.
The plugin separates plugin files (skills, templates, reference docs) from your content (albums, artists). Your content lives in {content_root} (configured in ~/.bitwize-music/config.yaml).
{content_root}/ # Your workspace
└── artists/your-artist/
├── README.md # Artist profile
└── albums/hip-hop/my-album/ # Album by genre
├── README.md # Album concept, tracklist
├── RESEARCH.md # Sources (if true-story)
├── SOURCES.md # Citations
└── tracks/
├── 01-first-track.md
├── 02-second-track.md
└── ...
Set content_root in your config to point to your workspace. You can keep it in the plugin folder (with artists/ gitignored) or set a separate path to keep content independent.
Each track file contains:
- Concept and narrative role
- Full lyrics
- Suno Style Box (copy to Suno's style field)
- Suno Lyrics Box (copy to Suno's lyrics field)
- Generation log
Let's walk through creating an album from scratch.
You say:
Let's make a new album
Claude will ask about:
- Artist (existing or new?)
- Genre and sonic direction
- Album concept and theme
- Track count and structure
- Track concepts (what's each song about?)
Claude presents the full plan. Review and confirm:
Ready to start writing
You say:
Let's write track 1
Claude drafts lyrics and automatically:
- Checks for repeated rhymes
- Analyzes prosody (stressed syllables on beats)
- Scans for pronunciation risks
- Suggests fixes for any issues
Review and iterate:
The second verse feels weak, can we make it more visual?
Once lyrics are approved, Claude fills in:
- Style Box: Genre tags, vocal description, instrumentation
- Lyrics Box: Lyrics with section tags and phonetic fixes
Example Style Box:
[your genre], [vocal style],
[instruments], [mood], [tempo] BPM
Example Lyrics Box:
[Verse 1]
Your lyrics here
With section tags
[Chorus]
Hook goes here
...
- Open suno.com
- Copy Style Box → "Style of Music" field
- Copy Lyrics Box → "Lyrics" field
- Generate and listen
- Tell Claude the result:
Track 1 generation 1: vocals too quiet, otherwise good
Claude logs the attempt and suggests prompt adjustments.
Keep generating until you have a keeper:
Track 1 is done, this one is perfect: [suno-link]
Claude marks it complete and you move to track 2.
Work through each track. Claude maintains context across the full album.
Download WAV files from Suno, then:
Master the tracks in ~/Music/your-album/
Claude runs the mastering scripts:
- Analyzes loudness (LUFS)
- Applies EQ and limiting
- Targets -14 LUFS for streaming
- Creates
mastered/folder with final files
Release the album
Claude runs the release checklist:
- Verifies all tracks are final
- Prepares streaming lyrics for distributors
- Guides you through SoundCloud/distributor upload
- Updates album status and documentation
Done! Your album is live.
| Skill | Description |
|---|---|
/bitwize-music:lyric-writer |
Write/review lyrics with prosody and rhyme checks |
/bitwize-music:album-conceptualizer |
Album concepts, tracklist architecture |
/bitwize-music:suno-engineer |
Technical Suno V5 prompting |
/bitwize-music:pronunciation-specialist |
Prevent Suno mispronunciations |
/bitwize-music:album-art-director |
Album artwork concepts and AI art prompts |
For documentary or true-story albums:
| Skill | Description |
|---|---|
/bitwize-music:researcher |
Coordinates specialized researchers |
/bitwize-music:document-hunter |
Automated document search from public archives |
/bitwize-music:researchers-legal |
Court documents, indictments |
/bitwize-music:researchers-gov |
DOJ/FBI/SEC press releases |
/bitwize-music:researchers-journalism |
Investigative articles |
/bitwize-music:researchers-tech |
Project histories, changelogs |
/bitwize-music:researchers-security |
Malware analysis, CVEs |
/bitwize-music:researchers-financial |
SEC filings, market data |
/bitwize-music:researchers-historical |
Archives, timelines |
/bitwize-music:researchers-biographical |
Personal backgrounds |
/bitwize-music:researchers-primary-source |
Subject's own words |
/bitwize-music:researchers-verifier |
Quality control, fact-checking |
| Skill | Description |
|---|---|
/bitwize-music:lyric-reviewer |
QC gate before Suno - 9-point checklist |
/bitwize-music:explicit-checker |
Scan lyrics for explicit content |
/bitwize-music:verify-sources |
Human source verification gate — timestamps and records verification |
/bitwize-music:validate-album |
Validate album structure, file locations, content integrity |
| Skill | Description |
|---|---|
/bitwize-music:mix-engineer |
Per-stem audio polish (noise reduction, EQ, compression) |
/bitwize-music:mastering-engineer |
Audio mastering for streaming |
/bitwize-music:promo-director |
Generate promo videos for social media |
/bitwize-music:promo-reviewer |
Review and polish social media copy before release |
/bitwize-music:cloud-uploader |
Upload promo videos to Cloudflare R2 or AWS S3 |
/bitwize-music:sheet-music-publisher |
Convert audio to sheet music, create songbooks |
/bitwize-music:release-director |
QA, distribution prep |
| Skill | Description |
|---|---|
/bitwize-music:resume |
Resume work on an album - finds album, shows status and next steps |
/bitwize-music:tutorial |
Interactive guided album creation and getting started |
/bitwize-music:album-ideas |
Track and manage album ideas — brainstorming, planning, status |
/bitwize-music:new-album |
Create album directory structure with templates |
/bitwize-music:configure |
Set up or edit plugin configuration |
/bitwize-music:import-audio |
Move audio files to correct album location |
/bitwize-music:import-track |
Move track .md files to correct album location |
/bitwize-music:import-art |
Place album art in audio and content locations |
/bitwize-music:clipboard |
Copy track content to clipboard (macOS/Linux/WSL) |
/bitwize-music:test |
Run automated tests to validate plugin integrity |
/bitwize-music:ship |
Automate full release pipeline (branch → PR → CI → merge → version bump → release) |
/bitwize-music:skill-model-updater |
Update Claude model references |
/bitwize-music:help |
Show available skills, workflows, and quick reference |
/bitwize-music:about |
About bitwize and this plugin |
Skills use different Claude models optimized for quality vs cost. On Claude Code Max plans, critical creative outputs use the best models available.
| Model | When Used | Skills |
|---|---|---|
| Opus 4.6 | Critical creative outputs (6 skills) | /bitwize-music:lyric-writer, /bitwize-music:suno-engineer, /bitwize-music:album-conceptualizer, /bitwize-music:lyric-reviewer, /bitwize-music:researchers-legal, /bitwize-music:researchers-verifier |
| Sonnet 4.5 | Reasoning and coordination (29 skills) | /bitwize-music:researcher, /bitwize-music:pronunciation-specialist, /bitwize-music:explicit-checker, and most other skills |
| Haiku 4.5 | Rule-based operations (15 skills) | /bitwize-music:validate-album, /bitwize-music:test, imports, clipboard, help |
Why different models?
- Opus 4.6 for lyrics, Suno prompts, album concepts, lyric review, and legal/verification research — these define the final music and have high error cost
- Sonnet for planning, research coordination, and most tasks — excellent quality at lower cost
- Haiku for mechanical operations (imports, validation, clipboard) where speed matters more than creativity
Checking models: Run /bitwize-music:skill-model-updater check to verify all skills use current Claude models. The updater can automatically update model references when new versions release.
All in tools/. Python 3.8+ required for optional tools.
| Directory | Purpose | Key Scripts |
|---|---|---|
mastering/ |
Audio mastering for streaming | master_tracks.py (genre presets, -14 LUFS), analyze_tracks.py, reference_master.py |
promotion/ |
Social media promo videos | generate_promo_video.py, generate_album_sampler.py |
cloud/ |
Cloud storage uploads | upload_to_cloud.py (R2/S3) |
sheet-music/ |
Sheet music generation | transcribe.py |
state/ |
State cache for fast session startup | indexer.py (rebuild, update, validate, session) |
tests/ |
Automated test suite | run_tests.py (180 tests, 91% coverage) |
shared/ |
Common utilities | logging_config.py, progress.py |
All in reference/ (46+ files). Key references:
| Path | Contents |
|---|---|
suno/v5-best-practices.md |
Comprehensive Suno V5 prompting guide |
suno/pronunciation-guide.md |
Phonetic spelling for tricky words |
suno/structure-tags.md |
Song section tags ([Verse], [Chorus], etc.) |
suno/genre-list.md |
500+ genre tags |
suno/voice-tags.md |
Vocal style tags |
mastering/mastering-workflow.md |
Full mastering guide |
model-strategy.md |
Skill-to-model assignments and rationale |
workflows/ |
Checkpoint scripts, album planning, source verification, error recovery |
promotion/ |
Promo video workflow, social media specs |
release/ |
Platform comparison, distributor guide, metadata |
quick-start/ |
First album, true-story album, bulk releases |
Copy these for new content:
| Template | Purpose |
|---|---|
templates/track.md |
Track structure with Suno inputs |
templates/album.md |
Album planning template |
templates/artist.md |
Artist profile |
templates/genre.md |
Genre documentation |
templates/ideas.md |
Album ideas tracking |
templates/research.md |
Research documentation |
templates/sources.md |
Citation tracking |
Config file location: ~/.bitwize-music/config.yaml
| Setting | Purpose | Default |
|---|---|---|
artist.name |
Your artist/project name | (required) |
artist.genres |
Primary genres | [] |
paths.content_root |
Where albums/artists are stored | (required) |
paths.audio_root |
Where mastered audio goes | (required) |
paths.documents_root |
Where PDFs/primary sources go | (required) |
urls.soundcloud |
SoundCloud profile URL | (optional) |
generation.service |
Music generation service | suno |
Mirrored structure: audio_root and documents_root use the same [artist]/[album]/ structure as content_root.
Tools directory: ~/.bitwize-music/ also contains the shared mastering venv and cache files.
See config/README.md for details.
- Put vocal description FIRST in the style prompt
- Be specific: "raspy male vocals" not just "male vocals"
- Use section tags:
[Verse],[Chorus],[Bridge] - Avoid artist names (against Suno TOS) - describe the style instead
- Watch your rhymes - no self-rhymes, no lazy patterns
- Check prosody - stressed syllables should land on strong beats
- Use phonetic spelling for names: "Rah-mohs" not "Ramos"
- Spell out acronyms: "F-B-I" not "FBI"
- Capture sources FIRST, write lyrics SECOND
- Human verification required before generation
- Never impersonate - narrator voice only
- Every claim must trace to a captured source
Problem: "Config not found at ~/.bitwize-music/config.yaml"
Solution:
mkdir -p ~/.bitwize-music
cp config/config.example.yaml ~/.bitwize-music/config.yaml
# Edit with your settings
nano ~/.bitwize-music/config.yamlOr use the interactive config tool:
/bitwize-music:configure
Problem: /bitwize-music:resume my-album can't find the album
Possible causes:
- Wrong album name - Album names are case-sensitive. Try:
/bitwize-music:resume(without name) to see all albums - Wrong path in config - Check
paths.content_rootin~/.bitwize-music/config.yamlpoints to where your albums live - Album in wrong location - Albums must be in:
{content_root}/artists/{artist}/albums/{genre}/{album}/
Debug steps:
# Check config
cat ~/.bitwize-music/config.yaml
# List all album READMEs
find ~/your-content-root/artists -name README.md -path "*/albums/*"Problem: Files created in wrong locations, "path not found" errors
Common mistakes:
- Using relative paths instead of reading config
- Forgetting to include artist name in audio/documents paths
- Hardcoding paths instead of using
{content_root}from config
The rule: Always read ~/.bitwize-music/config.yaml first to get paths. Never assume or hardcode.
Correct path structure:
{content_root}/artists/{artist}/albums/{genre}/{album}/ # Content
{audio_root}/artists/{artist}/albums/{genre}/{album}/ # Audio (mirrored structure)
{documents_root}/artists/{artist}/albums/{genre}/{album}/ # Documents (mirrored structure)
Problem: Mastering fails with import errors
Solution: Install mastering dependencies:
pip install matchering pyloudnorm scipy numpy soundfileOr use a virtual environment (recommended):
python3 -m venv ~/.bitwize-music/venv
source ~/.bitwize-music/venv/bin/activate
pip install matchering pyloudnorm scipy numpy soundfileProblem: /bitwize-music:document-hunter fails with browser errors
Solution: Install Playwright and browser:
pip install playwright
playwright install chromiumProblem: After updating the plugin, things don't work
Common causes:
- Config schema changed - Compare your
~/.bitwize-music/config.yamlwithconfig/config.example.yaml - Template changes - Existing albums may use old template format
- Skill renamed or removed - Check CHANGELOG.md for breaking changes
Solutions:
- Backup your config before updating
- Review CHANGELOG.md after updates
- Keep content in separate
content_rootto avoid conflicts
Problem: Skills don't appear in / menu or can't be invoked
Check:
- Plugin installed correctly:
/plugin list - Skill files exist:
ls ~/.claude/plugins/bitwize-music@claude-ai-music-skills/skills/ - Try restarting Claude Code
Open an issue with:
- What you tried to do
- What happened (error messages, unexpected behavior)
- Your OS and Claude Code version
- Relevant config (redact personal info)
CC0 - Public Domain. Do whatever you want with it.
PRs welcome! Please read CONTRIBUTING.md for our development workflow and guidelines.
Artist and song references in the genre documentation are for educational and reference purposes only. This plugin does not encourage creating infringing content. Users are responsible for ensuring their generated content complies with applicable laws and platform terms of service.