Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bitwize-music-studio/claude-ai-music-skills --skill session-start -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/session-start/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/session-start/

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.

From the same set52

The whole set →
help help is a Claude Code skill that lists bitwize-music commands and workflows; call it to find a command or check what a tool does. CX Codex +1 253installs import-art import-art distributes album artwork into audio and content folders using standard naming conventions. Useful right after generating or downloading a cover. CX Codex +1 252installs new-album new-album generates directory trees and markdown templates for new music albums based on genre settings. CX Codex +1 252installs researchers-gov researchers-gov gathers official US government releases from the DOJ, FBI, and SEC for documentary music tracks. Pulls verifiable figures, timelines, and direct quotes. CX Codex +1 252installs explicit-checker explicit-checker scans song lyrics for profanity and verifies explicit flags before Suno generation or distributor release. CX Codex +1 251installs promo-reviewer promo-reviewer reviews album promo copy by platform and helps polish it before release. Use it to check populated promo/ files and revise posts interactively. CX Codex +1 250installs voice-checker The voice-checker skill scans song lyrics and prose for seven hallmarks of machine-generated text: stacked abstractions, over-explained metaphors, clichéd phrases, missing specifics, perfect grammar instead of natural speech. CX Codex +1 250installs import-track import-track moves track markdown files from Downloads or other locations into the correct album directory structure. Use it when track files are scattered and need to be organized by your project layout. CX Codex +1 250installs

Project sponsors

Companies that keep this analytics open