setup
Detects your Python environment and guides you through installing plugin dependencies. Use on first-time setup or when MCP server fails to start.
How do I install this agent skill?
npx skills add https://github.com/bitwize-music-studio/claude-ai-music-skills --skill setupIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This setup skill helps users configure the bitwize-music plugin environment by performing system checks and installing dependencies. It handles Python virtual environment creation, package installation via pip, and integration with the Suno MCP server and audio utilities. All actions are standard for software setup and target legitimate resources.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Base directory for this skill: ${CLAUDE_PLUGIN_BASE_DIR}
Your Task
Guide the user through installing bitwize-music plugin dependencies based on their Python environment and requested components.
Setup Assistant
You help users install and verify plugin dependencies.
Step 1: Detect Environment
Run these checks in parallel:
# Python version
python3 --version
# Check if externally managed
python3 -c "import sysconfig; print(sysconfig.get_path('purelib'))" 2>&1 | grep -q "/usr" && echo "EXTERNALLY_MANAGED" || echo "USER_MANAGED"
# Check for pipx
command -v pipx >/dev/null 2>&1 && echo "pipx: installed" || echo "pipx: not installed"
# Check for venv support
python3 -m venv --help >/dev/null 2>&1 && echo "venv: supported" || echo "venv: not supported"
# Platform
uname -s
Step 2: Check Component Status
IMPORTANT: Run these checks sequentially, not in parallel. If one check fails, continue with the remaining checks to show complete status.
CRITICAL: Always check the venv, not system Python!
# Set venv path (macOS/Linux/WSL uses bin/python3; native Windows uses Scripts/python.exe)
VENV_PYTHON=~/.bitwize-music/venv/bin/python3
[ -f "$VENV_PYTHON" ] || VENV_PYTHON=~/.bitwize-music/venv/Scripts/python.exe
# Check if venv exists
if [ -f "$VENV_PYTHON" ]; then
echo "✅ Venv exists at ~/.bitwize-music/venv"
# Check each component in the venv
# 2.x serves MCPServer from mcp.server.mcpserver, 1.x serves FastMCP from
# mcp.server.fastmcp; the server takes either, so probe both (#537).
$VENV_PYTHON -c "import mcp.server.mcpserver" 2>/dev/null || $VENV_PYTHON -c "import mcp.server.fastmcp" 2>/dev/null && echo "✅ mcp installed" || echo "❌ mcp not installed (need mcp[cli]>=1.28.1,<3)"
$VENV_PYTHON -c "import matchering; print('✅ matchering installed')" 2>&1 || echo "❌ matchering not installed"
$VENV_PYTHON -c "import boto3; print('✅ boto3 installed')" 2>&1 || echo "❌ boto3 not installed"
$VENV_PYTHON -c "from playwright.sync_api import sync_playwright; print('✅ playwright installed')" 2>&1 || echo "❌ playwright not installed"
# Check for version drift against requirements.txt
$VENV_PYTHON -c "
import importlib.metadata, pathlib
reqs = pathlib.Path('${CLAUDE_PLUGIN_ROOT}/requirements.txt').read_text()
stale = []
for line in reqs.splitlines():
line = line.split('#')[0].strip()
if not line or '==' not in line:
continue
name, _, ver = line.partition('==')
name = name.split('[')[0].strip()
try:
installed = importlib.metadata.version(name)
if installed != ver:
stale.append(f' {name}: {installed} → {ver}')
except importlib.metadata.PackageNotFoundError:
stale.append(f' {name}: missing (needs {ver})')
if stale:
print('⚠️ Version drift detected:')
print('\n'.join(stale))
else:
print('✅ All package versions match requirements.txt')
" 2>&1
else
echo "❌ Venv not found at ~/.bitwize-music/venv"
echo " Run: python3 -m venv ~/.bitwize-music/venv # macOS/Linux/WSL"
echo " Or: py -3 -m venv ~/.bitwize-music/venv # Windows"
fi
All components are installed together in the venv via requirements.txt.
Step 3: Show Installation Commands
Always use the unified venv approach — it works on all platforms and is automatically detected by the plugin.
# Create unified venv (if it doesn't exist)
python3 -m venv ~/.bitwize-music/venv # macOS/Linux/WSL
py -3 -m venv ~/.bitwize-music/venv # Windows (native)
# Install ALL plugin dependencies
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/python.exe -m pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # Windows (native)
# Set up document hunter browser
~/.bitwize-music/venv/bin/playwright install chromium # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/playwright.exe install chromium # Windows (native)
That's it! The plugin automatically detects and uses the platform venv (~/.bitwize-music/venv on macOS/Linux/WSL, %USERPROFILE%\.bitwize-music\venv on native Windows). No configuration needed.
Works on:
- ✅ Linux (externally-managed Python)
- ✅ macOS
- ✅ Windows (native — Core tier, best-effort; audio tooling needs WSL2)
- ✅ Windows (WSL)
- ✅ All other systems
Step 3.5: Optional — Suno Server and Audio Player
Neither is needed for the plugin to work. Mention them once, after the required components are sorted.
Suno MCP server — lets /bitwize-music:generate, /bitwize-music:listen and /bitwize-music:import-audio --from-suno reach the user's Suno account. Check the suno section of the health_check result first: configured means it is already registered (say so, with its name and scope, and skip the command); missing means it is not:
claude mcp add --transport http suno https://api.suno.com/mcp
Then /mcp in a session to sign in. --scope user on the command makes it available in every project, not only this one. The plugin does not ship this server; without it those skills fall back to the clipboard flow, and session start shows these instructions until it is added (generation.suno_mcp_reminder: false in the config hides them).
Audio player — lets /bitwize-music:listen play audio in the terminal. Any one of mpv (recommended), ffplay (part of ffmpeg) or macOS's built-in afplay:
command -v mpv ffplay afplay # shows which are installed
brew install mpv # macOS
sudo apt install mpv # Debian/Ubuntu/WSL
winget install mpv # Windows
Step 4: Installation Guide
Present a clear, simple installation guide:
- Environment detected: [Python version, Platform]
- Missing components: [list what needs to be installed]
- Installation commands:
python3 -m venv ~/.bitwize-music/venv # macOS/Linux/WSL ~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # macOS/Linux/WSL ~/.bitwize-music/venv/bin/playwright install chromium # macOS/Linux/WSL py -3 -m venv ~/.bitwize-music/venv # Windows (native) ~/.bitwize-music/venv/Scripts/python.exe -m pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # Windows (native) ~/.bitwize-music/venv/Scripts/playwright.exe install chromium # Windows (native) - After installation:
- Restart Claude Code to reload the plugin
- MCP server should show as running in
/pluginstatus - Run
/bitwize-music:setupagain to verify
Step 5: Verify Installation (if requested)
After user reports they've installed, re-run the checks from Step 2 and confirm:
✅ MCP server: Ready ✅ Audio mastering: Ready ✅ Cloud uploads: Ready ✅ Document hunter: Ready
Next steps: Run /bitwize-music:configure to set up your workspace paths.
Output Format
Use clear sections with checkboxes for status:
## bitwize-music Setup
### Environment
- Python: 3.12.3
- System: Linux
### Component Status
- [❌] MCP server
- [❌] Audio mastering
- [❌] Cloud uploads
- [❌] Document hunter
### Installation
Run these commands to install all plugin dependencies (macOS/Linux/WSL shown; see Step 3 for the Windows native `py -3` / `Scripts\` equivalents):
```bash
# Create unified venv
python3 -m venv ~/.bitwize-music/venv
# Install ALL dependencies
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt
# Set up browser
~/.bitwize-music/venv/bin/playwright install chromium
After installation:
- Restart Claude Code
- All components will work automatically
- Run
/bitwize-music:setupto verify
The plugin automatically detects ~/.bitwize-music/venv — everything just works!
---
## Remember
- **Be specific** - show exact commands for their environment
- **Prioritize user install** for externally-managed Python
- **Explain what each component does** so they can decide what to install
- **Test commands work** before suggesting them
- **Clear next steps** after installation
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/bitwize-music-studio/claude-ai-music-skills/setup">View setup on skillZs</a>