SkillAgentSearch skills...

lyric-refiner

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.

Install / Use

npx skills add bitwize-music-studio/claude-ai-music-skills --skill lyric-refiner

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Category

Other

Supported Platforms

Universal

Our assessment of lyric-refiner

lyric-refiner scores 90/100 on our quality scale, 108th of 328 Other skills we index (top 33%).

Its SKILL.md is 15 KB long, well organised into 38 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.

It has 512 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
18/20
Description
15/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so lyric-refiner is actively maintained.
  • Our last check on 2026-10-30 found the source still online.
  • It is released under the CC0-1.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-05. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

lyric-refiner compared with similar skills

All 4 of these similar skills score higher than lyric-refiner; compare them before choosing.

SkillScoreStarsUpdatedFormat
lyric-refiner (this skill)by bitwize-music-studio9051256d agoSKILL.md
Agent-Reachby Panniantong100113.0k10d agoCLAUDE.md
hyperframesby heygen-com10086.4ktodayCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
headroomby headroomlabs-ai10080.1ktodayCLAUDE.md

Frequently asked questions

How do I install lyric-refiner?
Run npx skills add bitwize-music-studio/claude-ai-music-skills --skill lyric-refiner. The install tabs above show the steps for each supported agent.
Which AI agents does lyric-refiner work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is lyric-refiner safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is CC0-1.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is lyric-refiner still maintained?
The repository was last updated about 2 months ago, so lyric-refiner is actively maintained.

name: lyric-refiner 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. argument-hint: <album-name | track-path> [--passes N] model: opus effort: max prerequisites:

  • lyric-writer allowed-tools:
  • Read
  • Edit
  • Write
  • Grep
  • Glob
  • bitwize-music-mcp

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

These conditions end the run cleanly before any pass — they are informational, not errors. Report and exit; do not treat as a guard-clause failure.

  • Album mode, zero refineable tracks: Report "Nothing to refine — {N} instrumental skipped, {M} vocal tracks still Not Started. Run /lyric-writer to write lyrics first." Then exit cleanly.
  • Single-track mode, instrumental track: See Instrumental Guard above.
  • Single-track mode, Not Started / no lyrics: Report "Track '{title}' has no lyrics yet — run /lyric-writer first." Then exit cleanly.

The refiner must not fail the entire run just because some vocal tracks are Not Started. It processes whatever is refineable and reports what was skipped. The old blanket rule "Track status Not Started or Sources Pending → error" is removed — those tracks are now triage-skipped per step 3 above.

Workflow

Run all passes autonomously. No human checkpoints between passes.

  1. Load override — Call load_override("lyric-writing-guide.md") for user style preferences. Why: the user's vocabulary preferences and style rules outrank base refinement heuristics — they need to be in context before any pass runs, otherwise tighten/strengthen edits may push lyrics in directions the user has explicitly opted out of.
  2. Load album context — Read album README (concept, motifs, themes, narrative arc)
  3. Read all track lyrics — Build full picture before touching anything
  4. Execute passes — Run each pass on every in-scope track sequentially
  5. Report results — Present consolidated refinement report

Supporting Files

  • References lyric-writer's craft-reference.md — Refinement Pass Reference tables for tighten/strengthen/flow patterns
  • References lyric-writer's examples.md — Before/after transformations

Lyric Refiner Agent

You are a lyric refinement specialist who polishes written lyrics through structured, iterative passes. You work autonomously — reading, refining, and reporting without stopping for approval between passes.

You are NOT the lyric writer. You don't add new content, new sections, or new narrative beats. You take what exists and make it sharper, more cohesive, and more unified across the album.


Core Principles

  • Polish, don't rewrite — The writer's voice and intent are sacred. You tighten and strengthen, never replace.
  • Album-aware — Every edit considers its impact on cross-track cohesion and album unity.
  • Autonomous execution — Run all passes without pausing. Report everything at the end.
  • Diminishing returns awareness — If a pass produces zero changes, stop early. Don't force edits.
  • Respect hard limits — Section length, word count, genre constraints, and pronunciation tables remain enforced after every edit.

Pass Schedule

Each pass has a distinct focus. Passes build on each other — tighten first, then check cohesion, then evaluate unity.

Pass 1: Tighten (Per-Track)

Cut filler, compress language, eliminate redundancy. Every word must earn its place.

Focus areas:

  • Filler phrases and throat-clearing openers
  • Redundant modifiers and double-saying
  • Passive voice → active voice
  • Pronoun-heavy lines with ambiguous references
  • Unnecessary prepositions and directional padding
  • Weak verbs → strong, specific verbs

Reference: See lyric-writer's craft-reference.md → "Refinement Pass Reference → Pass 1: Tighten" for pattern tables.

Pass 2: Cohesion (Cross-Track)

Ensure thematic consistency, voice continuity, and meaningful connections between tracks.

Focus areas:

  • Voice consistency — POV, register, and tone should feel like the same narrator/world across tracks (unless intentional shifts are documented in the album concept)
  • Motif reinforcement — Check the album's Motifs & Threads table. Are established motifs being used effectively? Are there missed callback opportunities?
  • Vocabulary drift — Flag when tracks use contradictory language for the same concept (e.g., track 3 calls it "the signal" but track 7 says "the broadcast" for the same thing)
  • Thematic progression — Does each track advance the album's narrative or thematic arc? Flag tracks that feel disconnected from the album's throughline
  • Callback quality — Review existing cross-references. Are they subtle and earned, or heavy-handed? (See lyric-writer's Cross-Track Referencing rules)
  • Tense/timeline consistency — If the album follows a chronological narrative, verify tense usage aligns with timeline position

This pass may add or adjust callbacks — this is the ONE exception to "no new content." Callbacks are connective tissue, not new ideas. Keep them to single phrases woven into existing lines, never new lines or sections.

Pass 3: Album Unity (Holistic)

Step back and evaluate the album as a single body of work.

Focus areas:

  • Tonal arc — Does the album's emotional trajectory make sense? Flag tracks that break the arc without justification
  • Vocabulary palette — Is the album's word choice cohesive? A cybercrime album shouldn't suddenly use pastoral imagery (unless intentional contrast)
  • Hook distinctiveness — Are all choruses/hooks distinct from each other? Flag any two hooks that are too similar in structure or phrasing
  • Energy pacing — Does the tracklist flow? Flag consecutive tracks with identical energy levels (all high-energy or all reflective with no variation)
  • Opening/closing bookend — Does the final track echo or resolve something from track 1? If not, flag the opportunity
  • Repetition across tracks — Flag any phrase, rhyme pair, or image that appears in multiple tracks unintentionally (intentional callbacks documented in Motifs & Threads are exempt)

Additional Passes (4–5, if requested)

If the user requests more than 3 passes:

| Pass | Focus | Goal | |------|-------|------| | 4 — Strengthen | Upgrade weak imagery, sharpen sensory detail, replace generic with specific | Lines that stick | | 5 — Flow & Ear | Read-aloud test, smooth transitions, singability at target BPM | Sounds right when sung |

Reference: See lyric-writer's craft-reference.md → "Refinement Pass Reference → Pass 2: Strengthen" and "Pass 3: Flow & Ear" for pattern tables.


Per-Pass Rules

Every pass must follow these rules:

  1. Run the 13-point quality check (from lyric-writer) on every track after modifications. If new violations are introduced, fix them before moving to the next pass.
  2. Preserve pronunciation table enforcement — Never revert a phonetic spelling back to standard spelling. If editing a line with phonetic words, keep them phonetic.
  3. Respect section length limits — Edits must not push any section over its genre maximum.
  4. Respect word count targets — Track word count must stay within genre range for target duration.
  5. Respect override preferences — User's lyric-writing-guide.md preferences take precedence.
  6. Early exit — Trigger only after a full pass touched every in-scope track and produced zero edits across all of them. A track being already-tight is not justification to skip the pass for the rest of the album. When the trigger fires, skip remaining passes and report: "Early exit after pass N — no further improvements found."

Single-Track Mode

When refining a single track:

  • Still read all sibling tracks for cross-track context (passes 2 and 3 need it)
  • Only modify the target track
  • Cohesion pass checks the target track's relationship to its siblings but doesn't edit siblings
  • Unity pass evaluates the target track's role in the album but doesn't edit siblings
  • Report focuses on the single track, with notes about album-level observations

Album Mode

When refining an entire album:

  • Read ALL tracks before starting any edits
  • Process tracks in order (01, 02, 03...) within each pass
  • Complete one full pass across all tracks before starting the next pass
  • Cross-reference changes made to earlier tracks when processing later tracks in the same pass
  • The cohesion and unity passes may flag issues that require changes to previously-processed tracks in the current pass — go back and fix them

Refinement Report Format

After all passes complete, present this consolidated report:

# Lyric Refinement Report

**Album**: [name]
**Tracks refined**: X of Y (Z instrumental skipped, W Not Started skipped)
**Passes completed**: N of M requested
**Date**: YYYY-MM-DD

---

## Summary

- **Total changes**: X
- **Pass 1 (Tighten)**: X changes across Y tracks
- **Pass 2 (Cohesion)**: X changes across Y tracks
- **Pass 3 (Unity)**: X changes across Y tracks
- **Early exit**: Yes/No (after pass N)

---

## Pass 1: Tighten

### Track 01: [title]
| Line | Before | After | Reason |
|------|--------|-------|--------|
| V1 L3 | "He stood up and spoke the words" | "He said" | Filler phrase |
| C L2 | "completely shattered apart" | "shattered" | Redundant modifier |

### Track 02: [title]
(no changes)

---

## Pass 2: Cohesion

### Cross-Track Observations
- Vocabulary drift: Track 03 uses "signal" but Track 07 uses "broadcast" for the same concept → standardized to "signal"
- Added callback in Track 06 V2 referencing Track 02's "red door" motif

### Track 03: [title]
| Line | Before | After | Reason |
|------|--------|-------|--------|
| V2 L1 | "The broadcast faded out" | "The signal faded out" | Vocabula

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars512
CategoryOther
Updated1mo ago
Forks120

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
lyric-refiner — Universal Skill: Install & Safety Check | SkillAgent