Any lyric writing request should read this skill first, then decide which other one to read.
The output of this libraryis not lyric text, but a LYR-SPEC(lyric draft specification sheet) — the lyrics are part of it, but the spec sheet also carries "why it was written this way" and "how to verify it".
★ The biggest difference in the lyric writing step
Lyric writing is the only step in making a song that produces pure text.
Two consequences:
- No need to go around the three steps of "compute first, then listen" — the AB method for text can be used as-is: the evaluation table is finalized before looking at the results, A/B labels are shuffled, pairwise comparison, judging the same pair two or three times to see if the conclusion is stable
- ★ Inverted characters and tonal harmony can be judged programmatically — Mandarin inverted characters (the tone direction is opposite to the melody direction → it is sung as a different character), Cantonese tonal harmony, neither requires ears. This gives Chinese lyrics an objective criterion for the first time, with a status equivalent to tempo in audio: one of the few quantities that can be directly measured accurately and used for comparison
0. Thirty-second positioning
| What you want to do now | Go to |
|---|---|
| Write a lyric from scratch | ★ First answer the fork in §1, then follow the corresponding stage table |
| Set lyrics to an existing melody | §2 Music first, lyrics after |
| Write lyrics first, then compose | §3 Lyrics first, music after |
| Don't know which skill a certain question belongs to | §4 Full library boundary table |
| lint fails | §5.2 |
| Need to hand off the lyrics (composition and arrangement, recording, scoring, drama) | §6 |
| Need to test: where the request belongs, whether the lyrics read like something a human wrote, inverted characters | §7 |
| Want to know how far this library can currently be used | ★ §8 |
1. ★ The first fork: which workflow
This is the only question in this library that must be answered first, because the stage tables of the two paths are completely different.
先曲后词：meta.upstream（段落表 ＋ 旋律） ──→ LYR-SPEC 的 prosody 约束
先词后曲：LYR-SPEC 的字数句式 ──→ 交出去约束小节数 form[].bars
★ In the two paths the direction of the data is opposite, and there is only one rule: whoever does it first defines it, and the party that does it later only reads（§6.1）。
| Ask | Answer |
|---|---|
| Is there already a melody/demo | Yes → Music first, lyrics after（§2） |
| Is it an assigned topic with a predetermined tune | Yes → Music first, lyrics after |
| Is the content of the lyrics more important than the music | Yes → considerLyrics first, music after（§3） |
| Is it Cantonese | ★ Cantonese is almost inevitably music first, lyrics after— tonal harmony makes the melody directly determine what characters can be used at each position (see lw-cantonese） |
2. Stage table: music first, lyrics after
| Stage | What to do | Output | Gate |
|---|---|---|---|
| S0 Concept | Turn the brief into "say only one thing" | intent five items |
★ All five items complete，plot_type Answer first and do not default to narrative type,anchor_object must beCan be photographed in kind |
| S1 Connect the spec | From meta.upstream read the paragraphs, bar counts, emotional arc, and melody; if there is no paragraph chart, segment and count bars yourself against the melody or demo, fill it into meta.upstream.form and note that it is self-devised |
prosody.sections the box of |
Paragraph ids and meta.upstream.form[].id one-to-one correspondence |
| S2 Measure lines | Count syllables/characters line by line, mark stress positions, markwhich character the highest note falls on | prosody fill in |
★ peak_syllable required—that character must hold up when sung |
| S3 Find objects and imagery | object writing, come up with a list of concrete nouns | imagery |
Clear the abstract-word blacklist to zero |
| S4 Write lyrics | Fill according to the prosody grid | Lyric draft | |
| S5 Language-layer check | Tone mismatch/assonance/rhyme category/stress | checks.computed |
★ For Mandarin, check the tone-mismatch rate; for Cantonese,assonance violations must be 0。★★ The manually judged results must be written into checks.computed(tone-mismatch rate, which positions were checked, which characters were mismatched, how they were handled); if you only read lw-tone-check and write no record, it counts as not checked, and lint item 7 directly fails |
| S6 Asymmetry | Deliberately break up uniformity | asymmetry three items |
Fill in at least two items |
| S7 Acceptance | LYR-LINT + AI-flavor checklist | All 10 pass |
3. Stage table: lyrics first, then music
| Stage | What to do | Difference from music first, then lyrics |
|---|---|---|
| S0 Concept | Same as above | Same |
| S1 Form-setting | Set paragraphs and sentence patterns first | ★ No external constraints, decide yourself—so it is easier to write uniformly and neatly,the asymmetry in §6 must be pushed harder |
| S2 Write lyrics | Write according to your own sentence patterns | |
| S3 Measure lines | ★ The reverse: count the number of characters in each line,determine by character-count sentence patterns form[].bars |
This package does it first; the six shared fields are defined by this package (§6.1) |
| S4 Language-layer check | ★ At this point there is no melody yet, so tone mismatch cannot be checked | ⚠ The tone-mismatch check must wait until the melody is out and be done then |
| S5 Handoff | Hand over the spec sheet: character-count sentence patterns, six shared fields, tone contour (§6) | |
| S6 Recheck | ★ After the melody comes back, the tone-mismatch/assonance check must be rerun | This step is most often missed |
★★ The biggest trap of lyrics first, then music：
The lyrics are finalized, and only when the melody is added do you discover tone mismatches. At that point, changing the lyrics is very costly.
Countermeasure: When writing lyrics in S2, mark the "tone contour" of each line and write it into prosody.sections[].melody_contour, hand it over as part of the melody constraints.
4. Full-library boundary table
4.1 Search by question
| Question | Owner |
|---|---|
| What does this song want to say | lw-song-intent |
| Paragraph function, where the hook and title go, whether the sentence pattern is stable | lw-structure |
| Imagery, concrete nouns, object writing | lw-imagery |
| Rhyme, rhyme scheme, when to deliberately not rhyme | lw-rhyme |
| Person, point of view, time anchor, leaving blanks | lw-narrative |
| Inverted tones, thirteen rhyme categories, level and oblique tones | lw-mandarin |
| Tone-melody matching(Cantonese) | ★ lw-cantonese（You are not allowed to substitute the Mandarin system for it） |
| Aligning English stress with the beat | lw-english |
| Writing Japanese lyrics by mora, fukuwari, jiamari | lw-japanese |
| Writing Korean lyrics by syllable, batchim (final consonant), liaison and sound changes | lw-korean |
| Chinese style | lw-chinese-style |
| Musical theater, character lyrics | lw-musical-theatre |
| Rhyme density and flow in rap | lw-rap |
| How to use the inverted-tone detector, how to read its results | lw-tone-check |
| Final AI-flavor check before submitting | lw-ai-tell-audit |
| Find a real example | lw-case-studies |
4.2 ★ Several groups of boundaries most easily confused
★ lw-japanese ⇄ lw-korean: Japanese counts by mora, with sokuon, hatsuon, and chōon each taking one beat; Korean counts by the number of Hangul syllable blocks, and batchim does not take an extra beat. If you use the Japanese system to count Korean, every closed syllable will be counted as one beat too many.
| A ⇄ B | Boundary line |
|---|---|
lw-rhyme ⇄ lw-mandarin |
rhyme handles the matter of rhyming itself (rhyme scheme, degree of surprise, deliberate non-rhyming); mandarin handles the Chinese rhyme tables (thirteen rhyme categories) and character tones |
lw-mandarin ⇄ lw-cantonese |
★ It is not "swapping in a different rhyme table". Cantonese tone-melody matching is ahard constraint and reverses the writing order—once the melody is fixed, only a few characters remain available for each position |
lw-imagery ⇄ lw-narrative |
imagery handles "what thing is used to say it"; narrative handles "who is speaking, when they speak, and what is not said" |
lw-structure ⇄ composition and arrangement |
★ The sectional function of lyrics belongs here; the number of measures in the musical form belongs to composition and arrangement. Section ids are shared by both sides (§6.1) |
| This library ⇄ vocal direction | ★ How characters are fitted onto notes (fukuwari) belongs to this library; how those characters should be sung (breathy voice/dynamics/pitch correction) belongs to vocal direction (voice) |
4.3 Always out of scope
| Content | Which function it belongs to |
|---|---|
| Melody, harmony, arrangement, number of measures in the musical form | Composition and arrangement |
| Vocal recording, pitch correction, vocal direction | Voice(recording and vocal direction) |
| Writing music for visuals | Scoring |
| Poetry not set to music | It is not lyrics and is not in this package |
| Opera and drama lyrics'qupai prosody, metrical patterns and line patterns | Dramatic writing(opera and drama libretto writing). This library only borrows rhyme and character tones: the thirteen rhyme categories are in lw-mandarin(for opera and drama reading, see its reference §1.5), the three merits of rhyme selection for lyrics are in lw-mandarin reference §7, and setting melody according to characters is in lw-tone-check §1 |
Out-of-scope items are handed off only through LYR-SPEC (§6).
5. LYR-SPEC
The complete specification is in this skill directory's LYR-SPEC.schema.md, the blank template is LYR-SPEC.template.yaml, and the filled examples are example-01-jacket.yaml(positive) and example-00-ai-default.yaml(negative).
★ Before writing the spec sheet, Read the template first and fill it in according to its field names. After writing prosody.syllables , go through the lyrics line by line and count the characters before submitting, as this item is the most consistently off-by-one-character place. If you do not look at the template, field names will grow on their own (in actual testing it has been written as said_to、moment, while the spec says to_whom、at_what_moment), then whoever reads this spec sheet can't follow it.
★ YAML self-check(the two most commonly broken spots):
- If a value uses quotes, the whole sentence stays inside the quotes,do not continue writing outside the quotes（
peak_syllable: "价"（第二杯半价）—— 去声otherwise the whole file won't parse) - List item
- {…}belowcannot have anothernote:key attached, for comments use a same-levelxxx_note:or#line comment
5.1 ★ Why these fields
Every field corresponds to one "why can you tell at a single listen that the words were written directly by AI":
| AI-flavor symptom | Counter field | Computable |
|---|---|---|
| All nouns are abstract | imagery.concrete_nouns required,forbidden blacklist |
✅ |
| Structure symmetrical to death | asymmetry three items required |
✅ |
| Everything is resolved, nothing left hanging | narrative.withholding required |
⚠ Semi-automatic |
| No perspective or time | narrative.pov ＋ tense_anchor |
⚠ Semi-automatic |
| Inverted tones ignored | prosody + inverted-tone detector |
✅ Fully computable |
| Rhyme categories only pick the smoothest | rhyme.che + rhyme-category distribution |
✅ |
| Rhyming always picks the first character that comes to mind | rhyme.surprise_notes |
✅ |
| Chorus repeats verbatim three times | asymmetry.chorus_variation |
✅ |
★ Seven of the nine are computable. Harder than the equivalent checks on audio,because text doesn't need detection。
5.1b ★ How to pass the ten: with your eyes, not with tools
This library does not require any tools on the user's machine—no scripts, no Python or Node assumed.
- All ten LYR-LINT itemsgo through manually one by one(every item in the table below can be judged with your eyes), write the results into
checks.self_audit - Inverted tones: use
lw-tone-checkthe five tone-pattern table in §2.2to judge by hand—only check these three types of positions: the highest note of each section, the first character of each line, and the landing point of large leaps (about 1/5 of all characters), no need to check everything; ★ after judging, write the results intochecks.computed(e.g.,倒字: {查了: 18 字, 倒: ["暖", "口"], 率: 0.11, 处理: "暖 改 温"}), missing this step is the most common point-losing mistake - ★ The ten are criteria, not iron laws: fix the items that don't pass, or write a sentence explaining why this lyric should be this way. A deviation with a written reason is a legitimate choice, not a "fail"
- Don't write scripts just to check
5.2 The ten LYR-LINT items
| # | Check | When it fails, look at |
|---|---|---|
| 1 | intent five items non-empty,plot_type is in the closed set,anchor_object is a photographable physical object |
lw-song-intent |
| 2 | Each section has at least N concrete nouns;forbidden zero occurrences of abstract words |
lw-imagery |
| 3 | Sections must not all have exactly the same character count | lw-structure |
| 4 | asymmetry at least two of the three items filled in |
lw-structure |
| 5 | narrative.withholding non-empty |
lw-narrative |
| 6 | pov ＋ tense_anchor non-empty |
lw-narrative |
| 7 | Inverted-tone rate ≤ threshold (Mandarin) / homophone violation = 0 (Cantonese) | lw-tone-check |
| 8 | Rhyme categories must not use only one or two broad rhyme categories for the whole song | lw-mandarin |
| 9 | Rhyme-word unexpectedness: must not be all the highest-frequency rhyme characters | lw-rhyme |
| 10 | Chorus text must not be exactly the same across repetitions | lw-structure |
⚠ Items 2, 7, 8, and 9 only report numbers, they don't judge pass/fail. ★ This meansArticles 7, 8, and 9 can only give values, not "pass/fail"。
6. External interface
This library interfaces externally only through LYR-SPEC: what is handed over, what is read, and how issues are communicated are all written in the spec sheet; it does not assume who the reader is or what tools they use. For how to understand each field, see LYR-SPEC.schema.md §3。
| Which function it is handed to | Handed over | If present, read (meta.upstream） |
|---|---|---|
| Composition and arrangement(melody, harmony, arrangement, number of bars in the form) | lyrics[]；prosody.sections[](character count per line, stress positions,which character the highest note falls on; when lyrics come before music, there is also the tonal contour); when lyrics come before music, the six shared fields defined by this library (§6.1);checks.computed tonal mismatch records of |
Section table form(section id, name, number of bars, emotion value), tempo, key, who is singing, melody source—when music comes before lyrics, this is the input to S1 |
| Voice(recording and vocal direction) | lyrics[](reference for recording and pitch correction);vocal.persona、narrative.pov; characters at high risk of tonal mismatch and characters that can only be saved by adding ornamentation (checks） |
— |
| Scoring(cues with lyrics) | intent、narrative、lyrics[] |
Where this song sits in the picture (scene: cue, duration, what happened before and after) |
| Dramaturgy(sung passages in the play) | intent、narrative、lyrics[] |
The source and turning point of this scene (scene） |
- If present, read it; if not, follow this library's own analysis: if there is no section table, segment the melody yourself; if there is no melody, follow §3 lyrics before music; for songs not in a play and not in a picture,
scenewritenone。 - Upstream fields read in are not rewritten by this library. When upstream and this library's judgments conflict, this library writes its own fields truthfully, then writes a message (§6.2).
6.1 ★ The six fields shared with the other side of the song
form[].id / form[].bars / form[].name / meta.tempo / meta.key / vocal.persona
- Whoever goes first decides; the side that goes later only reads: when music comes before lyrics, these six items are in
meta.upstream, and this library uses them as locked items; when lyrics come before music, this library decides them and hands them over—the character count and sentence pattern of the lyrics are the basis forform[].bars. - The side that goes later does not change these six items: if the lyrics cannot fit into these few bars, write a message to
music, stating clearly which item to change and why; after the other side accepts and changes it, this library reads it again. - When there is only the lyrics side, this library decides these six items itself. For the original rules and where each item is placed, see schema §3.3.
6.2 How to write messages
messages is the common area at the top level of the spec sheet; each {from, to, about, says, status, reply}, this library writes from: lyrics；to takes music(composition and arrangement, scoring),sound(voice),writing(dramaturgy),production(production).
- Example:
to: music，about: form[C2].bars，says: "C2's third line has eleven characters and cannot fit into 4 bars; please change C2 to 6 bars." - If no reply can be read, treat it as none;this library does not wait：
openmessages do not block any gate; finish writing the lyrics according to your own judgment, and hand them over as-is at delivery. - Messages written to this library (
to: lyrics) are read when S0 starts work and before each lyric revision.
7. Three inspections
7.1 The types of requests most easily mishandled
- "Write me a melody" → check out: composition and arrangement
- "The vocals in this mix are too muddy" → check out: sound (mixing)
- "What are the thirteen rhymes" → read-only
lw-mandarin，don't start the full workflow - "Write lyrics for this Cantonese song" → must read
lw-cantonese, don't just use the Mandarin set - "Turn these lyrics into rap" →
lw-rap, shouldn't disturb anything outside the language layer
7.2 ★ What a first-draft lyric is judged by
There is only one criterion: whether this draft can be told apart from a hand-written lyric.
- Taken as "human-written" → this draft holds up
- Still distinguishable from hand-written → the shortfall is exactly what still needs revising
The method is the text AB mentioned at the start: the rubric is finalized before looking at the results (using lw-ai-tell-audit §2's eight items), this draft and hand-written lyrics are shuffled under A/B labels, uninformed people are asked to compare them in pairs, and the same pair is judged two or three times to see whether the conclusion is stable. The shortfall is traced per lw-ai-tell-audit §5 to which skill should fix it.
7.3 Inverted-tone detection
The criterion, the five-tone constraint, the three boundaries (one character with multiple pronunciations, context disambiguation, risk ≠ error) and the five revision methods are in lw-tone-check §2~§6。
★ This is the only thing in this library that can be built without any textbook and immediately produces an objective criterion, so only the routing is given here, and the body text is not repeated.
8. ★ Scope of coverage of this package
| This package has | This package does not have | |
|---|---|---|
| Language layer | Mandarin (thirteen rhymes, level and oblique tones, inverted tones), Cantonese (tonal matching), English (stress and meter), Japanese (morae, character division), Korean (syllables and batchim, liaison, sound change) | None |
| Genre layer | Chinese style, musical theatre lyrics, rap | Folk narrative |
★ The five sets of language constraints cannot substitute for one another: Chinese relies on character tones, Cantonese on tonal matching, English on stress, Japanese on beat count, Korean on syllables and final consonants.
Using one set to check another gives confidently wrong answers. For comparison see lw-korean §7 and §4.2.
The genre layer lacks folk narrative; for such requests use the L1 general layer, and state that the genre conventions are not covered.
Each skill's "Appendix" lists the books it is based on.
9. Self-check before starting work
- Answered the fork in §1:music first then lyrics or lyrics first then music
-
intentFive itemsthought up, not filled in to pass lint -
prosody.syllablesArecounted line by line after the lyrics were written(counting only Chinese characters), not filled in first and then written to -
anchor_objectIsa physical object that can be photographed - Section ids align with
form[].id(when music comes first then lyrics, it ismeta.upstream.form[].id) - Read the message written to this library (
messagesthe entry forto: lyricsin - Language selected, and the corresponding L2 skill read (Cantonese may not be substituted with the Mandarin set）
- If lyrics come first then music,remember to rerun the inverted-tone check after the melody comes back(S6 of §3)
- After finishing, run LYR-LINT and
lw-ai-tell-audit
Appendix: Directory Map
本包的文件（全是文本）：
skills/<17 个 skill>/SKILL.md, reference.md
skills/lw-workflow/LYR-SPEC.schema.md ★ 规格单定义（v1.0）
skills/lw-workflow/LYR-SPEC.template.yaml 空模板
skills/lw-workflow/example-*.yaml 填好的示例（外套 / 反面样本）