session-start · bitwize-music-studio — Claude Code skill: what it does, how to install
session-start starts a fresh coding session by checking the setup, loading project state, and showing the work context. It helps restore where the project left off.
CC0-1.0 251 installs ★ 686 updated 2026-10-22
npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -a claude-codeWhat session-start does
This skill runs the startup flow for a new session. It checks the MCP environment, calls the health check, reads ~/.bitwize-music/config.yaml, and loads optional override files. It can rebuild the cached state when the cache is missing or invalid, then checks whether plugin migrations need attention.
The final report is based on state.json: ideas, albums in progress, tracks with pending source checks, and the previous session context. Migration actions are handled according to their type, with acknowledgements recorded afterward. The startup stops when the MCP setup is unusable or the virtual environment is missing, so ~/.bitwize-music/venv must be ready first.
What it helps with
- verify the MCP environment
- load project configuration and overrides
- rebuild missing project state
- process pending plugin migrations
- show unfinished albums and source checks
Example prompts for the agent
- Start a fresh session, check the setup, and report the current project status.
- Load the project state and tell me which albums need attention.
- Check pending plugin migrations and handle each action in order.
How to install session-start
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -a claude-code2Manually: put the files in place
~/.claude/skills/session-start/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/session-start/
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -a codex2Manually: put the files in place
.agents/skills/session-start/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -a cursor2Manually: put the files in place
.cursor/skills/session-start/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bitwize-music-studio/claude-ai-music-skills skills/session-start2Manually: put the files in place
.github/skills/session-start/SKILL.md1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -a gemini-cli2Platform CLI
gemini skills install https://github.com/bitwize-music-studio/claude-ai-music-skills --path skills/session-startManually: put the files in place
.devin/skills/session-start/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -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 session-start
How do I install session-start in Claude Code?
Run npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -a claude-code, then check ~/.claude/skills/session-start/SKILL.md.
What does session-start do?
It checks the MCP setup, loads configuration and cached state, handles plugin migrations, and reports the project context at session start.
What does session-start require?
The skill expects a working virtual environment at ~/.bitwize-music/venv, an available MCP SDK, and ~/.bitwize-music/config.yaml. It stops when the MCP setup cannot be used.
Source text
SKILL.md · CC0-1.0
---
name: session-start
description: Runs the session startup procedure - verifies setup, loads config and state, checks skill models, and reports project status. Use at the beginning of a fresh session.
model: sonnet
effort: low
allowed-tools:
- Read
- Bash
- Glob
- Grep
- WebSearch
- WebFetch
- bitwize-music-mcp
---
## Your Task
Run the full session start procedure and report project status to the user.
---
# Session Start Skill
You perform the 8-step session startup procedure that initializes a working session.
---
## Step 1: Verify Setup
Quick dependency check:
```bash
~/.bitwize-music/venv/bin/python3 -c "import mcp.server.mcpserver" 2>/dev/null || ~/.bitwize-music/venv/bin/python3 -c "import mcp.server.fastmcp" 2>/dev/null && echo "MCP ready" || echo "MCP unusable" # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/python.exe -c "import mcp.server.mcpserver" 2>/dev/null || ~/.bitwize-music/venv/Scripts/python.exe -c "import mcp.server.fastmcp" 2>/dev/null && echo "MCP ready" || echo "MCP unusable" # Windows (Git Bash; cmd/PowerShell: %USERPROFILE%\.bitwize-music\venv\Scripts\python.exe)
```
- If MCP unusable: **Stop immediately** and suggest: `/bitwize-music:setup mcp` (the SDK is missing or predates 1.28.1). Probe both server modules, never bare `import mcp`: 2.x serves `MCPServer` from `mcp.server.mcpserver` and 1.x serves `FastMCP` from `mcp.server.fastmcp`, and the server accepts either — but a bare `import mcp` succeeds even when neither module is present, reporting healthy on an install the server cannot boot on
- If config missing (`~/.bitwize-music/config.yaml` doesn't exist): suggest `/bitwize-music:configure`
- Don't proceed until setup is complete
## Step 1.5: Health Check
Use the `health_check` MCP tool (checks venv packages + skill registration + album slug collisions in one call):
**Venv results** (from `result.venv`):
- `status: "ok"` → continue silently
- `status: "stale"` → warn with mismatches and fix command, continue session
- `status: "no_venv"` → **stop** and suggest `/bitwize-music:setup`
- `status: "error"` → warn and continue
**Skill registration results** (from `result.skills`):
- `status: "ok"` → continue silently
- `status: "stale"` → warn: list missing and ghost skill names, show fix message
- `status: "no_cache"` → warn that plugin cache not found, continue
**Album slug collision results** (from `result.collisions`):
- `status: "ok"` → continue silently
- `status: "collision"` → warn: list each slug with its kept and shadowed genres, show the fix (rename one album with `/bitwize-music:rename` or move its directory, then run `rebuild_state`), continue session
## Step 2: Load Config
Read `~/.bitwize-music/config.yaml`.
If missing, tell user to run `/bitwize-music:configure`.
## Step 3: Load Overrides
Read `paths.overrides` from config (default: `{content_root}/overrides`):
- Check for `{overrides}/CLAUDE.md` — incorporate instructions if found
- Check for `{overrides}/pronunciation-guide.md` — note if found
- Skip silently if missing (overrides are optional)
## Step 4: Load State Cache
Read `~/.bitwize-music/cache/state.json`:
- If missing, corrupted, schema mismatch, or config changed: rebuild via MCP
```
rebuild_state()
```
## Step 4.5: Check for Plugin Upgrades
Call the `get_pending_migrations` MCP tool. It compares the installed plugin
version against `last_migrated_version` in state (the last version whose
migrations were processed — distinct from `plugin_version`, which only records
the installed version for display) and returns the pending notes already
parsed and sorted.
1. **If `pending` is empty** (`reason: "current"`, or `reason: "unknown"` when the
installed version can't be read from plugin.json): No action needed.
2. **If `pending` is non-empty** (`reason: "upgrade"` or `"untracked"`): For each
migration, process its `actions` in order:
- `auto`: Execute silently (run `check` first — skip if it returns 0)
- `action`: Show description, ask the user to confirm before executing
- `info`: Display to the user
- `manual`: Show the instruction to the user
3. **After processing all notes**, call `acknowledge_migrations` (no argument
acknowledges everything up to the installed version) so the same notes do
not surface again next session.
4. Report: "Upgraded to Y" with a summary of the actions taken.
> `reason: "untracked"` means the state predates migration tracking; the full
> backlog up to the installed version is surfaced once, then cleared by
> `acknowledge_migrations`. Do NOT just rebuild state to clear migrations —
> a rebuild preserves the pending status; only `acknowledge_migrations` records
> that you processed them.
## Step 5: (Removed)
Skill model checking is no longer part of session start. Skills use tier aliases (`opus`/`sonnet`/`haiku`) that auto-track the frontier model, and the test suite (`/bitwize-music:test`) enforces model/effort hygiene — so no manual model checking is needed when new Claude models are released.
## Step 6: Report From State Cache
Using data from `state.json`, report:
### Album Ideas
From `state.ideas.counts` — show count by status (Pending, In Progress, etc.)
### In-Progress Albums
Filter `state.albums` for status: "In Progress", "Research Complete", "Complete"
For each, show:
- Album name, genre, status
- Track progress (completed/total)
### Pending Source Verifications
From `state.albums` — find tracks where `sources_verified` is "Pending"
If any found, warn: "These tracks have unverified sources — generation is blocked until verified."
### Last Session Context
From `state.session`:
- Last album worked on
- Last phase
- Pending actions
## Step 7: Show Contextual Tips
Based on state, show ONE relevant tip:
| Condition | Tip |
|-----------|-----|
| No albums exist | "Try `/bitwize-music:tutorial` to create your first album" |
| Ideas exist but no albums | "You have album ideas! Use `/bitwize-music:album-ideas list` to review them" |
| In-progress albums exist | "Resume where you left off: `/bitwize-music:resume <album-name>`" |
| Overrides loaded | "Custom overrides loaded from {overrides}/" |
| Overrides missing | "Customize your workflow with override files — see `/reference/overrides/`" |
| Pending verifications | "Source verification needed before generation can proceed" |
Also show one random general tip (rotate through these):
- "Ask 'what should I do next?' for workflow guidance"
- "Use `/bitwize-music:resume` to quickly jump back into an album"
- "The researcher skill coordinates 10 specialized sub-skills for deep research"
- "Check pronunciation before generating — Suno can't infer from context"
- "Use `/bitwize-music:clipboard` to copy lyrics/prompts for Suno"
- "Master your audio with `/bitwize-music:mastering-engineer` for professional results"
## Step 8: Ask
End with: "What would you like to work on?"
---
## Report Format
```
SESSION START
=============
Setup: MCP ready, config loaded
Health: [venv ok, skills ok, no collisions | warnings listed]
Overrides: [loaded from {path} | not found (optional)]
State: [loaded | rebuilt | error]
ALBUM IDEAS
Pending: X | In Progress: Y
IN-PROGRESS ALBUMS
[album-name] (genre) - Status [X/Y tracks]
[album-name] (genre) - Status [X/Y tracks]
PENDING VERIFICATIONS
[album-name]: track-01, track-05
LAST SESSION
Album: [name] | Phase: [phase]
Pending: [actions]
TIP: [contextual tip]
What would you like to work on?
```
---
## Remember
1. **Don't skip steps** — Each step matters for session integrity
2. **Rebuild state if needed** — Stale state leads to wrong recommendations
3. **Be concise** — This is a status report, not a conversation
4. **Warn about verifications** — Unverified sources block generation
5. **One tip, not five** — Pick the most relevant tip for the current state
© bitwize-music-studio · CC0-1.0 · bitwize-music-studio/claude-ai-music-skills
Similar skills
SKILL.md skills catalog →session-start by other authors comes first.