lyrics

name	lyrics
type	capability
description	Lyrics and songwriting — original lyrics for pop, rock, hip-hop, R&B, folk, electronic, classical vocal, Chinese-style (中国风), and all musical genres. Handles verse-chorus structure, rhyme schemes, syllable fitting, hook writing, singability, and AI music platform integration.

Lyrics Writing

Orchestrator dispatches all creation and review work to subagents. Before creation, copy user-uploaded files to /mnt/agents/output/research/.

Sub-skill of general-writing. Inherits shared creative writing principles, anti-AI discipline, and quality gate framework.

CRITICAL — Review → Fix Brief → Dispatched Subagent: When a review finds issues, translate them into a detailed fix brief (file paths, quoted findings, expected outcome, scope boundary, self-check) and dispatch a fresh lyrics_writer subagent to apply the fix. Never use inline sed/edit_file fixes.

CRITICAL — Anti-Read-Loop Rule: The orchestrator must dispatch its first subagent (lyrics_writer) within 10 iterations. If the orchestrator has spent 10+ iterations only reading files without creating any subagent, it is in a read-loop. Stop reading, draft your structural plan from what you have, and dispatch the writer immediately.

CRITICAL — .docx / .txt Delivery: Every completed song must be converted to .docx using skills/docx/SKILL.md. For Suno/AI music platform targets, also produce a .txt file with meta-tags. Never end a session with only raw section files and no assembled deliverable.

File Paths

Output: /mnt/agents/output/
  {project_name}.{song_title}.md        # Song lyrics
  {project_name}.{song_title}.suno.txt  # Suno meta-tags (if requested)
  research/                              # User uploads (melody refs, mood boards)

Trigger Keywords

歌词, lyrics, 填词, songwriting, 作词, chorus, verse-chorus, hook, 说唱词, rap lyrics, 中国风歌词, Suno, AI music, 古风歌词

Workflow Decision Tree

User Query
  │
  ├─ Provides existing lyrics + asks for revision → Stage 3 → Assembly
  ├─ Provides melody/structure + asks for lyrics → Stage 2 → Stage 3 → Assembly
  └─ New request → Infer parameters (see below) → Stage 1 → Stage 2 → Stage 3 → Assembly

Infer genre, structure, emotional arc, melody reference, target platform, and language register from the user's request. The orchestrator analyzes and infers all parameters autonomously; for complex requests, deploy a subagent to analyze requirements in depth. Never prompt the user for clarification.

Stage 1: Conception

Orchestrator produces a structural plan:

1. Section order (from template, adjusted to song's needs). Common templates:
   • Pop: V1 → Pre-C → Chorus → V2 → Pre-C → Chorus → Bridge → Final Chorus
   • Ballad: V1 → V2 → Chorus → V3 → Chorus → Bridge → Final Chorus
   • Hip-hop: Intro → V1 (16 bars) → Hook → V2 (16 bars) → Hook → Bridge → Hook → Outro
   • 古风: 起 → 承 → [Interlude] → 转 → 合
2. Syllable targets per line (critical if melody exists)
3. Rhyme scheme per section (e.g., Verse: ABAB, Chorus: AABB)
4. Hook concept: the central lyrical idea in one sentence
5. Emotional trajectory mapped to structure (verse = setup, pre-chorus = tension, chorus = peak, bridge = shift)
6. If melody reference provided: extract syllable counts per phrase, stress patterns, breath points
7. If for AI music platform: draft style tags (genre, instrumentation, vocal style, mood, tempo — 300-500 chars)

Save to /mnt/agents/output/{filename}.agent.outline.md.

Stage 2: Creation

Read ../anti-ai.md — inline its content into writer system prompts.

Write chorus FIRST. The chorus is the song's center of gravity. Horse-race 2-3 chorus variants — dispatch parallel subagents with different approaches.

Strictly one section per task call (chorus, verse, bridge each dispatched separately).

create_subagent:

• name: "lyrics_writer"
• system_prompt: Compose from these elements: (1) Role: "You are a songwriter writing [genre] lyrics in [language]." (2) Song structure template: Inline the full section order, line counts, and emotional arc per section. (3) Singability rules: "Singability overrides literary merit. Every line must pass the read-aloud test. Rules: (a) stressed syllables land on downbeats; (b) breath points at natural grammatical breaks; (c) no consonant clusters (str-, spl-, nkths) on fast passages; (d) open vowels (ah, oh, oo, ee) on sustained/high notes; (e) closed vowels (uh, ih) never on held notes." (4) Genre conventions: Pop — conversational register, emotional directness, strong hook; Hip-hop — internal rhyme density, wordplay, flow, punch lines; 古风 — classical imagery (意象), 四字词, 典故, elegant register; Ballad — emotional vulnerability, simple language, quiet-to-intense build. (5) Anti-AI rules: Inline from ../anti-ai.md plus lyrics-specific: "No 'journey of self-discovery.' No 'stand tall in the face of adversity.' No 'wings to fly' / 'light in the darkness' without earned context. No perfectly grammatical singing — use contractions, fragments, repetition. No every-line-same-length." (6) Narrative-to-lyric rule: "When source material is a story, concept, or experience, convert to metaphor and sensory imagery. FORBIDDEN: naming literal specifics (place names, dates, technical terms) unless they serve as deliberate poetic anchors. Test: could a listener not in on the context still feel the emotion? If no, it's too literal."
• description: "Write song lyrics per structural plan"

Dispatch chorus horse-race — task (2-3 parallel):

• agent: "lyrics_writer"
• prompt: "Write [genre] chorus. Hook concept: [concept]. Variant [A/B/C] — explore [different hook phrasing / different imagery / different rhythmic pattern]. Rhyme scheme: [scheme]. Syllable targets: [targets]. This is the emotional peak of the song."
• Save each to /mnt/agents/output/{filename}_chorus_{A|B|C}.md

Present chorus variants to user. After selection:

Dispatch remaining sections — task (one section per call):

• agent: "lyrics_writer"
• prompt: "Write [section name] for [genre] song. Chorus (selected): [inline or path]. Emotional arc position: [setup/tension/shift/resolution]. Rhyme scheme: [scheme]. Syllable targets: [targets]. Tempo guidance: [BPM feel or qualitative]. The verse must build toward the chorus; the bridge must contrast it." Include structural plan, selected chorus, melody reference (if exists).
• Save to /mnt/agents/output/{filename}_sec{NN}.md

Word Count Verification

After each completed section, orchestrator runs:

python skills/general-writing/scripts/check_wordcount.py <file> --min {target} --lang auto

If FAIL, return to writer with expansion instructions.

Stage 3: Review

Read ../review.md first. Follow the shared pipeline, then add genre-specific editor.

Shared Pipeline (from review.md)

For lyrics (short form), continuity_editor is lightweight. style_editor checks AI-pattern absence and voice consistency across sections. structural_editor verifies emotional arc and section balance.

Genre-Specific Editor

singability_checker — The critical lyrics-specific reviewer.

create_subagent:

• name: "singability_checker"
• system_prompt: "You perform phonetic analysis of lyrics for singability. Check: (1) syllable stress alignment with intended downbeats; (2) breath point placement at natural phrase boundaries; (3) consonant clusters that would be unsingable at tempo; (4) vowel quality on sustained/high notes (open vowels required); (5) tongue-twister detection; (6) line length variation (monotone lengths = algorithmic). Output: PASS or FAIL with specific line numbers and fixes."
• description: "Phonetic singability analysis"

task:

• agent: "singability_checker"
• prompt: Include all section file paths, structural plan (syllable targets, tempo), melody reference if available.

Iterative loop: flag unsingable phrases → write a fix brief (specific lines, phonetic issues, suggested alternatives) and dispatch a fresh lyrics_writer subagent to apply the fix → re-check. Max 2 rounds. For multi-song projects: if a song fails review twice, mark remaining issues and move on.

Scoring Dimensions

Dimension	Weight	Check
Singability	30%	Natural mouth feel, stress alignment, breath points, vowel quality
Hook memorability	25%	Chorus sticks after one read; hook is catchy and resonant. Floor: 70
Rhyme craft	20%	Scheme consistency, no forced rhymes, internal rhyme in verses
Emotional arc	15%	Song progresses emotionally, not repeated sentiment
Syllable precision	10%	Line lengths match melodic rhythm (if melody provided)

Pass: >= 75 overall. Hook memorability must be >= 70.

Suno/AI Music Integration

When target platform is Suno, Udio, or similar:

1. Metatag format: Use standard section markers on their own lines:

   [Intro] [Verse 1] [Pre-Chorus] [Chorus] [Bridge] [Instrumental] [Outro]
   

2. Style tags: Include at top of final file. Format: genre + subgenre, instrumentation, vocal style, mood/dynamics, tempo (300-500 chars)
3. Lyrics-music alignment: sparse lyrics for slow songs, denser for uptempo; place strongest emotional words at melodic peaks; chorus lyrics must carry repetition; use [Instrumental] and [Break] for breathing room

Translation / Adaptation Mode

When user provides lyrics in one language and requests adaptation to another:

• Match syllable count per line (+-2 syllables acceptable)
• Preserve stressed syllables on downbeats across languages
• Reimagine culturally untranslatable expressions (don't literal-translate idioms)
• Apply singability_checker to BOTH source and target versions
• Prioritize how the line sounds sung over literal accuracy

Assembly

1. Concatenate all sections in structural order with section labels: [Verse 1], [Pre-Chorus], [Chorus], [Bridge], [Outro], etc.
2. If Suno/AI platform: prepend style tags at top of file
3. Save to /mnt/agents/output/{filename}.agent.final.md
4. Convert to .docx using the md2docx pipeline (see skills/docx/SKILL.md → references/md2docx-reference.md). Output: /mnt/agents/output/{filename}.agent.final.docx. For Suno/AI platform targets, the .suno.txt file is also a primary deliverable.

Delivery is mandatory. Raw section files without an assembled deliverable (.docx or .txt) is not an acceptable end state.

Reference Files

File	Purpose	When to Read	Who Runs
../anti-ai.md	AI patterns to avoid — inline into system prompts	Before creating any writer subagent	Orchestrator inlines into subagent
../review.md	Shared review pipeline, editor definitions, quality gates	Before Stage 3	Orchestrator follows
Structural plan (agent.outline.md)	Section order, syllable targets, rhyme schemes, hook concept	Generated in Stage 1	Orchestrator creates, subagents consume
../scripts/check_wordcount.py	Word count verification	After each section completes	Orchestrator runs directly