# Lyric Refiner

Autonomous multi-pass lyric refinement for tightening, cohesion, and album unity.

- Repository: https://github.com/bitwize-music-studio/claude-ai-music-skills (615 stars)
- Category: Engineering
- License: CC0-1.0
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bitwize-music-studio/claude-ai-music-skills --skill lyric-refiner -g -a claude-code -y`
Codex: `npx skills add bitwize-music-studio/claude-ai-music-skills --skill lyric-refiner -g -a codex -y`
Cursor: `npx skills add bitwize-music-studio/claude-ai-music-skills --skill lyric-refiner -g -a cursor -y`
Gemini CLI: `npx skills add bitwize-music-studio/claude-ai-music-skills --skill lyric-refiner -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add bitwize-music-studio/claude-ai-music-skills`

## Description

Autonomous multi-pass lyric refinement for tightening, cohesion, and album unity. Use after lyrics are written to polish a track or entire album through iterative passes.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## Your Task

**Input**: $ARGUMENTS

### Parse Arguments

1. **Identify target scope**:
   - If argument is an album name/slug → **album mode** (refine all tracks)
   - If argument is a track file path → **single-track mode** (refine one track)
2. **Parse pass count**: Look for `--passes N` (default: 3, minimum: 1, maximum: 5)
   - If `--passes` > 5, warn: "Diminishing returns beyond 5 passes, capping at 5."

### Instrumental Guard

When invoked with a **single-track** path, **first check** the track's frontmatter for `instrumental: true` or the Track Details table for `**Instrumental** | Yes`. If the track is instrumental:

- **STOP** and report: "This is an instrumental track, no lyrics to refine. Use `/bitwize-music:suno-engineer` for Style Box work."
- Do NOT attempt to refine instrumental tracks.

In **album mode**, instrumental tracks are **silently skipped with a one-line note** (not blocking), see the triage in "Resolve Album & Tracks" below. A mix of instrumental and vocal tracks on the same album is the normal case, not an error.

### Resolve Album & Tracks

1. Use `find_album(name)` MCP tool to locate the album
2. Use `list_tracks(album_slug)` to get all tracks
3. **Triage every track** into one of three buckets, the refiner only operates on the third:
   - **Instrumental**, frontmatter `instrumental: true` or Track Details `**Instrumental** | Yes` → **skip**, emit `Skipping {track}, instrumental`
   - **Not ready**, status `Not Started` / `Sources Pending`, OR no Lyrics Box content → **skip**, emit `Skipping {track}, no lyrics yet ({status})`
   - **Refineable**, vocal track with lyrics written → include in the refinement pass set
4. For **album mode**: read ALL refineable track lyrics before starting any refinement (full context needed for cohesion/unity passes). Instrumental and not-ready tracks do not need to be read.
5. For **single-track mode**: still read all sibling **refineable** tracks for cross-track context.

### Pre-flight Exits

The rest: https://github.com/bitwize-music-studio/claude-ai-music-skills/blob/HEAD/skills/lyric-refiner/SKILL.md