setup · bitwize-music-studio — Claude Code skill: what it does, how to install
Checks the Python environment and plugin dependencies, then gives setup commands. Use it during first-time setup or when the MCP server will not start.
CC0-1.0 255 installs ★ 686 updated 2026-10-22
npx skills add bitwize-music-studio/claude-ai-music-skills --skill setup -a claude-codeWhat setup does
The skill inspects the Python version, platform, pipx, and venv support. It then checks the dedicated environment at ~/.bitwize-music/venv, including mcp, matchering, boto3, playwright, and package versions from requirements.txt.
Installation uses one shared virtual environment. Dependencies come from requirements.txt, while document hunter also needs Chromium installed through playwright. Restart Claude Code after installation and run /bitwize-music:setup again to verify the result. On native Windows, audio tooling requires WSL2.
What it helps with
- check Python and
venvsupport - locate missing plugin dependencies
- compare installed packages with
requirements.txt - install Chromium for document hunter
- verify the MCP server setup
Example prompts for the agent
- Run
/bitwize-music:setupand check every component. - Run
/bitwize-music:setup mcpto check the MCP dependencies. - After installing the packages, run
/bitwize-music:setupagain to verify them.
How to install setup
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill setup -a claude-code2Manually: put the files in place
~/.claude/skills/setup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/setup/
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill setup -a codex2Manually: put the files in place
.agents/skills/setup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill setup -a cursor2Manually: put the files in place
.cursor/skills/setup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bitwize-music-studio/claude-ai-music-skills skills/setup2Manually: put the files in place
.github/skills/setup/SKILL.md1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill setup -a gemini-cli2Platform CLI
gemini skills install https://github.com/bitwize-music-studio/claude-ai-music-skills --path skills/setupManually: put the files in place
.devin/skills/setup/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill setup -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about setup
How do I install setup in Claude Code?
Run npx skills add bitwize-music-studio/claude-ai-music-skills --skill setup -a claude-code, then check ~/.claude/skills/setup/SKILL.md.
What does setup do?
It detects the Python environment, checks the plugin virtual environment, and looks for mcp, matchering, boto3, and playwright. It also shows commands for installing the dependencies.
What does setup need on Windows?
Native Windows uses py -3 and the ~/.bitwize-music/venv/Scripts/ path. Audio tooling requires WSL2.
Source text
SKILL.md · CC0-1.0
---
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 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
© bitwize-music-studio · CC0-1.0 · bitwize-music-studio/claude-ai-music-skills
Similar skills
SKILL.md skills catalog →setup by other authors comes first.