bitwize-music-studio/claude-ai-music-skills / skills/setup
setup
VerifiedDetects your Python environment and guides you through installing plugin dependencies. Use on first-time setup or when MCP server fails to start.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
SKILL.md
View on GitHub---
name: setup
description: Detects your Python environment and guides you through installing plugin dependencies. Use on first-time setup or when MCP server fails to start.
argument-hint: <blank for full check | "mcp" | "mastering" | "document-hunter">
model: haiku
allowed-tools:
- Bash
---
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:**
```bash
# 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!
```bash
# 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.
```bash
# 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:
```bash
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`:
```bash
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:
1. **Environment detected**: [Python version, Platform]
2. **Missing components**: [list what needs to be installed]
3. **Installation commands**:
```bash
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)
```
4. **After installation**:
- Restart Claude Code to reload the plugin
- MCP server should show as running in `/plugin` status
- Run `/bitwize-music:setup` again 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:
```markdown
## 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:**
1. Restart Claude Code
2. All components will work automatically
3. Run `/bitwize-music:setup` to 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |