AI Music Skills - Claude Instructions

AI Music Skills - Claude Instructions

This is an AI music generation workflow using Suno. Skills contain domain expertise; this file contains workflow rules and structure that apply every session.

---

⚠️ CRITICAL: Finding Albums When User Mentions Them

**WHENEVER the user mentions an album name**, use the resume skill:

/bitwize-music:resume my-album

**If skill unavailable**, manual approach:

1. Read ~/.bitwize-music/cache/state.json — search state.albums keys (case-insensitive)
2. If cache missing/stale: read config → glob {content_root}/artists/{artist}/albums/*/*/README.md → rebuild cache with rebuild_state() MCP tool

**DO NOT**: search from cwd, use complex globs, assume paths, or use `ls`/`find`.

---

Configuration & Path Resolution

Config is **always** at: `~/.bitwize-music/config.yaml`

**ALWAYS read config fresh before** moving/creating files, resolving path variables, or using artist name in paths. Never assume or remember values.

**Path variables** (from config):

• {content_root} = paths.content_root
• {audio_root} = paths.audio_root
• {documents_root} = paths.documents_root
• {tools_root} = ~/.bitwize-music
• {plugin_root} = the directory containing this CLAUDE.md file (= ${CLAUDE_PLUGIN_ROOT} in skills)
• [artist] = artist.name

**IMPORTANT — Mirrored path structure**:

{content_root}/artists/[artist]/albums/[genre]/[album]/   # Album files (in git)
{audio_root}/artists/[artist]/albums/[genre]/[album]/     # Mastered audio
{documents_root}/artists/[artist]/albums/[genre]/[album]/ # PDFs (not in git)

Audio and document paths include `[artist]/` after the root. Common mistake: omitting the artist folder.

First-time setup: `cp config/config.example.yaml ~/.bitwize-music/config.yaml` — see `config/README.md`.

---

MCP Server — Preferred Data Access

The `bitwize-music-mcp` server is the **preferred way to query project state**. Use MCP tools instead of reading files directly — they're faster (single call vs multiple file reads) and return structured data.

**Use MCP tools for:**

• Albums/tracks → list_albums, find_album, get_track (not reading state.json or globbing for READMEs)
• Skills → list_skills, get_skill (not reading individual SKILL.md files)
• Ideas → get_ideas (not reading IDEAS.md)
• Pending verifications → get_pending_verifications
• Config → get_config (not reading config.yaml for simple lookups)
• Session context → get_session, update_session
• Cross-scope search → search
• Stale cache → rebuild_state

**Fall back to direct file access only when:** MCP server is unavailable, you need to edit files (MCP is read-only), or you need raw file content not exposed through MCP (e.g., full lyrics, research docs).

---

Session Start

At the beginning of a fresh session:

1. Verify setup — Quick dependency check:

   ~/.bitwize-music/venv/bin/python3 -c "import mcp" 2>&1 >/dev/null && echo "✅ MC