AMCS Lyrics Generator
Produces complete song lyrics that satisfy structural, stylistic, and policy constraints while maintaining full source provenance through hash-pinned retrieval.
When to Use
Invoke this skill after PLAN and STYLE generation to create lyrics. Runs in parallel with PRODUCER node and feeds into COMPOSE.
Input Contract
inputs:
- name: sds_lyrics
type: amcs://schemas/lyrics-1.0.json
required: true
description: Lyrics entity from SDS with constraints and preferences
- name: plan
type: amcs://schemas/plan-1.0.json
required: true
description: Section order and target word counts
- name: style
type: amcs://schemas/style-1.0.json
required: true
description: Musical style for thematic alignment
- name: sources
type: array[amcs://schemas/source-1.0.json]
required: false
description: External knowledge sources for retrieval
- name: blueprint
type: amcs://schemas/blueprint-1.0.json
required: true
description: Genre-specific lyrical patterns and lexicon
- name: seed
type: integer
required: true
description: Determinism seed (use seed+2 for this node)
Output Contract
outputs:
- name: lyrics
type: string
description: Complete lyrics text with section markers
- name: citations
type: array[citation]
description: |
Source chunks used with provenance:
- chunk_hash: SHA-256 of source text
- source_id: UUID of source
- text: Actual source snippet
- weight: Influence weight (0-1)
- name: metrics
type: object
description: |
Quality metrics:
- rhyme_tightness: 0-1 score
- singability: 0-1 score (syllable consistency)
- hook_density: count per section
Determinism Requirements
- Seed:
run_seed + 2 for LLM generation and retrieval tie-breaking
- Temperature: 0.3 for lyrics generation
- Top-p: 0.85
- Retrieval: Deterministic source chunk selection:
- Fixed top-k (k=5 per source)
- Sort by chunk_hash lexicographically for tie-breaking
- Store all chunk hashes in citations
- Hashing: Hash every source chunk (SHA-256) for pinned retrieval
Constraints & Policies
- Section order MUST match
plan.section_order
- Total lines MUST NOT exceed
sds_lyrics.constraints.max_lines
- Each section MUST satisfy
section_requirements (min/max lines, must_end_with_hook)
- Rhyme scheme MUST match
sds_lyrics.rhyme_scheme (e.g., AABB, ABAB)
- Syllable count per line MUST be within ±2 of
sds_lyrics.syllables_per_line
- Profanity filter MUST enforce
sds_lyrics.constraints.explicit:
- If false, replace profanity with [[REDACTED]] or safe alternatives
- If true, allow explicit content but score it in metrics
- Hook strategy MUST align with
sds_lyrics.hook_strategy:
- "chant": Repeat hook phrase ≥3 times in chorus
- "lyrical": Strong memorable phrase, ≥2 occurrences
- "melodic": Focus on singable phonetics
- "call-response": Alternating lines
- Source citations MUST include ALL retrieved chunks with hashes
Implementation Guidance
Step 1: Prepare Source Retrieval (if sources provided)
- For each source in
sources:
- Construct deterministic query from
style.mood + plan.section_order[0]
- Retrieve top-k=5 chunks from MCP source
- Sort chunks by SHA-256 hash lexicographically (tie-breaking)
- Store each chunk:
{chunk_hash, source_id, text}
- Apply source weights from
sds_lyrics.source_citations
- Store all chunks in citations array
Step 2: Generate Section-by-Section
For each section in plan.section_order:
Retrieve Section Constraints:
- Get
section_requirements[section] for min/max lines
- Get
target_word_counts[section] from plan
Build Context:
- Include style mood, energy, themes
- Include relevant source chunks (prioritize by weight)
- Include rhyme scheme and meter
Generate Lyrics:
- Use LLM with seed
run_seed + 2 + section_index
- Temperature: 0.3
- Enforce syllable target:
sds_lyrics.syllables_per_line ± 2
- Enforce rhyme scheme
- If section is "Chorus" and
must_end_with_hook, ensure last line is hook
Apply Profanity Filter:
- If
explicit = false, scan for profanity
- Replace with [[REDACTED]] or safe synonym
- Log replacements
Store Section:
- Prepend section marker:
[Verse 1], [Chorus], etc.
- Append to complete lyrics text
Step 3: Enforce Hook Strategy
If hook_strategy = "chant":
- Identify hook phrase (usually chorus last line)
- Count occurrences across all chorus sections
- Ensure ≥3 occurrences
If hook_strategy = "lyrical":
- Ensure at least 2 chorus sections contain identical hook line
If hook_strategy = "call-response":
- Alternate line structure in chorus sections
Step 4: Calculate Metrics
Rhyme Tightness:
- For each section, check line-end rhyme against scheme
- Score: (matching_rhymes / expected_rhymes)
Singability:
- For each line, count syllables
- Score: 1 - (avg_deviation_from_target / target)
Hook Density:
- Count hook occurrences per section
- Store as
metrics.hook_density
Step 5: Validate and Return
- Check total lines ≤
max_lines
- Validate all section requirements met
- Compute hash of complete lyrics text
- Return
{lyrics, citations, metrics, _hash}
Examples
Example 1: Christmas Pop with Family Source
Input:
{
"sds_lyrics": {
"language": "en",
"pov": "1st",
"tense": "present",
"rhyme_scheme": "AABB",
"syllables_per_line": 8,
"hook_strategy": "chant",
"section_order": ["Intro", "Verse", "Chorus", "Verse", "Chorus"],
"constraints": {
"explicit": false,
"max_lines": 40,
"section_requirements": {
"Chorus": {"min_lines": 6, "must_end_with_hook": true}
}
},
"source_citations": [{"source_id": "family-doc-uuid", "weight": 0.8}]
},
"sources": [
{
"source_id": "family-doc-uuid",
"chunks": [
{"hash": "abc123", "text": "Our family gathers every Christmas Eve..."},
{"hash": "abc456", "text": "The kids love decorating the tree together..."}
]
}
],
"seed": 44
}
Output:
{
"lyrics": "[Intro]\nSnowflakes falling, lights aglow\n\n[Verse]\nGathering 'round on Christmas Eve (8 syllables)\nThe kids decorate, we all believe (8 syllables)\n\n[Chorus]\nFamily time is what we need (8 syllables)\nLove and joy in every deed (8 syllables)\nSinging carols, feeling free (8 syllables)\nChristmas magic, you and me (8 syllables)\nFamily time is what we need (8 syllables - HOOK)\nLove and joy in every deed (8 syllables)\n\n[Verse]\n...\n\n[Chorus]\n...",
"citations": [
{
"chunk_hash": "abc123",
"source_id": "family-doc-uuid",
"text": "Our family gathers every Christmas Eve...",
"weight": 0.8
},
{
"chunk_hash": "abc456",
"source_id": "family-doc-uuid",
"text": "The kids love decorating the tree together...",
"weight": 0.8
}
],
"metrics": {
"rhyme_tightness": 0.95,
"singability": 0.88,
"hook_density": 3
},
"_hash": "ghi789..."
}
Common Pitfalls
- Missing Citations: Not recording source chunk hashes breaks determinism
- Syllable Variance: Exceeding ±2 syllable tolerance reduces singability
- Hook Absence: Missing hooks in "chant" strategy fails validation
- Profanity Leak: Not filtering when
explicit=false violates policy
- Section Overflow: Exceeding
max_lines per section truncates lyrics
- Rhyme Scheme Break: Not enforcing scheme reduces rhyme_tightness score
- Non-Deterministic Retrieval: Not sorting chunks by hash causes variation across runs
1---
2name: amcs-lyrics-generator
3description: Generate song lyrics with citations from pinned sources. Enforces rhyme scheme, meter, syllable counts, hook strategy, and profanity filter while retrieving from MCP sources with deterministic hash-based pinning. Use when creating lyrics with structural constraints, source attribution, and policy compliance.
4metadata:
5 source: https://skillmd.com/skills/majiayu000/amcs-lyrics-generator
6---
7
8# AMCS Lyrics Generator
9
10Produces complete song lyrics that satisfy structural, stylistic, and policy constraints while maintaining full source provenance through hash-pinned retrieval.
11
12## When to Use
13
14Invoke this skill after PLAN and STYLE generation to create lyrics. Runs in parallel with PRODUCER node and feeds into COMPOSE.
15
16## Input Contract
17
18```yaml
19inputs:
20 - name: sds_lyrics
21 type: amcs://schemas/lyrics-1.0.json
22 required: true
23 description: Lyrics entity from SDS with constraints and preferences
24 - name: plan
25 type: amcs://schemas/plan-1.0.json
26 required: true
27 description: Section order and target word counts
28 - name: style
29 type: amcs://schemas/style-1.0.json
30 required: true
31 description: Musical style for thematic alignment
32 - name: sources
33 type: array[amcs://schemas/source-1.0.json]
34 required: false
35 description: External knowledge sources for retrieval
36 - name: blueprint
37 type: amcs://schemas/blueprint-1.0.json
38 required: true
39 description: Genre-specific lyrical patterns and lexicon
40 - name: seed
41 type: integer
42 required: true
43 description: Determinism seed (use seed+2 for this node)
44```
45
46## Output Contract
47
48```yaml
49outputs:
50 - name: lyrics
51 type: string
52 description: Complete lyrics text with section markers
53 - name: citations
54 type: array[citation]
55 description: |
56 Source chunks used with provenance:
57 - chunk_hash: SHA-256 of source text
58 - source_id: UUID of source
59 - text: Actual source snippet
60 - weight: Influence weight (0-1)
61 - name: metrics
62 type: object
63 description: |
64 Quality metrics:
65 - rhyme_tightness: 0-1 score
66 - singability: 0-1 score (syllable consistency)
67 - hook_density: count per section
68```
69
70## Determinism Requirements
71
72- **Seed**: `run_seed + 2` for LLM generation and retrieval tie-breaking
73- **Temperature**: 0.3 for lyrics generation
74- **Top-p**: 0.85
75- **Retrieval**: Deterministic source chunk selection:
76 - Fixed top-k (k=5 per source)
77 - Sort by chunk_hash lexicographically for tie-breaking
78 - Store all chunk hashes in citations
79- **Hashing**: Hash every source chunk (SHA-256) for pinned retrieval
80
81## Constraints & Policies
82
83- Section order MUST match `plan.section_order`
84- Total lines MUST NOT exceed `sds_lyrics.constraints.max_lines`
85- Each section MUST satisfy `section_requirements` (min/max lines, must_end_with_hook)
86- Rhyme scheme MUST match `sds_lyrics.rhyme_scheme` (e.g., AABB, ABAB)
87- Syllable count per line MUST be within ±2 of `sds_lyrics.syllables_per_line`
88- Profanity filter MUST enforce `sds_lyrics.constraints.explicit`:
89 - If false, replace profanity with [[REDACTED]] or safe alternatives
90 - If true, allow explicit content but score it in metrics
91- Hook strategy MUST align with `sds_lyrics.hook_strategy`:
92 - "chant": Repeat hook phrase ≥3 times in chorus
93 - "lyrical": Strong memorable phrase, ≥2 occurrences
94 - "melodic": Focus on singable phonetics
95 - "call-response": Alternating lines
96- Source citations MUST include ALL retrieved chunks with hashes
97
98## Implementation Guidance
99
100### Step 1: Prepare Source Retrieval (if sources provided)
101
1021. For each source in `sources`:
103 - Construct deterministic query from `style.mood + plan.section_order[0]`
104 - Retrieve top-k=5 chunks from MCP source
105 - Sort chunks by SHA-256 hash lexicographically (tie-breaking)
106 - Store each chunk: `{chunk_hash, source_id, text}`
1072. Apply source weights from `sds_lyrics.source_citations`
1083. Store all chunks in citations array
109
110### Step 2: Generate Section-by-Section
111
112For each section in `plan.section_order`:
113
1141. **Retrieve Section Constraints**:
115 - Get `section_requirements[section]` for min/max lines
116 - Get `target_word_counts[section]` from plan
117
1182. **Build Context**:
119 - Include style mood, energy, themes
120 - Include relevant source chunks (prioritize by weight)
121 - Include rhyme scheme and meter
122
1233. **Generate Lyrics**:
124 - Use LLM with seed `run_seed + 2 + section_index`
125 - Temperature: 0.3
126 - Enforce syllable target: `sds_lyrics.syllables_per_line` ± 2
127 - Enforce rhyme scheme
128 - If section is "Chorus" and `must_end_with_hook`, ensure last line is hook
129
1304. **Apply Profanity Filter**:
131 - If `explicit = false`, scan for profanity
132 - Replace with [[REDACTED]] or safe synonym
133 - Log replacements
134
1355. **Store Section**:
136 - Prepend section marker: `[Verse 1]`, `[Chorus]`, etc.
137 - Append to complete lyrics text
138
139### Step 3: Enforce Hook Strategy
140
1411. If `hook_strategy = "chant"`:
142 - Identify hook phrase (usually chorus last line)
143 - Count occurrences across all chorus sections
144 - Ensure ≥3 occurrences
145
1462. If `hook_strategy = "lyrical"`:
147 - Ensure at least 2 chorus sections contain identical hook line
148
1493. If `hook_strategy = "call-response"`:
150 - Alternate line structure in chorus sections
151
152### Step 4: Calculate Metrics
153
1541. **Rhyme Tightness**:
155 - For each section, check line-end rhyme against scheme
156 - Score: (matching_rhymes / expected_rhymes)
157
1582. **Singability**:
159 - For each line, count syllables
160 - Score: 1 - (avg_deviation_from_target / target)
161
1623. **Hook Density**:
163 - Count hook occurrences per section
164 - Store as `metrics.hook_density`
165
166### Step 5: Validate and Return
167
1681. Check total lines ≤ `max_lines`
1692. Validate all section requirements met
1703. Compute hash of complete lyrics text
1714. Return `{lyrics, citations, metrics, _hash}`
172
173## Examples
174
175### Example 1: Christmas Pop with Family Source
176
177**Input**:
178```json
179{
180 "sds_lyrics": {
181 "language": "en",
182 "pov": "1st",
183 "tense": "present",
184 "rhyme_scheme": "AABB",
185 "syllables_per_line": 8,
186 "hook_strategy": "chant",
187 "section_order": ["Intro", "Verse", "Chorus", "Verse", "Chorus"],
188 "constraints": {
189 "explicit": false,
190 "max_lines": 40,
191 "section_requirements": {
192 "Chorus": {"min_lines": 6, "must_end_with_hook": true}
193 }
194 },
195 "source_citations": [{"source_id": "family-doc-uuid", "weight": 0.8}]
196 },
197 "sources": [
198 {
199 "source_id": "family-doc-uuid",
200 "chunks": [
201 {"hash": "abc123", "text": "Our family gathers every Christmas Eve..."},
202 {"hash": "abc456", "text": "The kids love decorating the tree together..."}
203 ]
204 }
205 ],
206 "seed": 44
207}
208```
209
210**Output**:
211```json
212{
213 "lyrics": "[Intro]\nSnowflakes falling, lights aglow\n\n[Verse]\nGathering 'round on Christmas Eve (8 syllables)\nThe kids decorate, we all believe (8 syllables)\n\n[Chorus]\nFamily time is what we need (8 syllables)\nLove and joy in every deed (8 syllables)\nSinging carols, feeling free (8 syllables)\nChristmas magic, you and me (8 syllables)\nFamily time is what we need (8 syllables - HOOK)\nLove and joy in every deed (8 syllables)\n\n[Verse]\n...\n\n[Chorus]\n...",
214 "citations": [
215 {
216 "chunk_hash": "abc123",
217 "source_id": "family-doc-uuid",
218 "text": "Our family gathers every Christmas Eve...",
219 "weight": 0.8
220 },
221 {
222 "chunk_hash": "abc456",
223 "source_id": "family-doc-uuid",
224 "text": "The kids love decorating the tree together...",
225 "weight": 0.8
226 }
227 ],
228 "metrics": {
229 "rhyme_tightness": 0.95,
230 "singability": 0.88,
231 "hook_density": 3
232 },
233 "_hash": "ghi789..."
234}
235```
236
237## Common Pitfalls
238
2391. **Missing Citations**: Not recording source chunk hashes breaks determinism
2402. **Syllable Variance**: Exceeding ±2 syllable tolerance reduces singability
2413. **Hook Absence**: Missing hooks in "chant" strategy fails validation
2424. **Profanity Leak**: Not filtering when `explicit=false` violates policy
2435. **Section Overflow**: Exceeding `max_lines` per section truncates lyrics
2446. **Rhyme Scheme Break**: Not enforcing scheme reduces rhyme_tightness score
2457. **Non-Deterministic Retrieval**: Not sorting chunks by hash causes variation across runs