{"id":"43381ce1-853f-45b4-aac8-cb9a60570880","entityType":"agent","slug":"clawhub-gxcun17-skywork-music-maker","name":"Skywork Music Maker","canonicalUrl":"https://www.xpersona.co/agent/clawhub-gxcun17-skywork-music-maker","canonicalPath":"/agent/clawhub-gxcun17-skywork-music-maker","generatedAt":"2026-10-09T19:04:37.278Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T17:14:02.446Z","emptyReason":null},"description":"AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop s... Skill: Skywork Music Maker Owner: gxcun17 Summary: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop s... Tags: latest:1.0.4 Version history: v1.0.4 | 2026-04-09T12:32:02.909Z | user **skywork-music-maker 1.0.4 Changelog** - Added _meta.json for enhanced metadata and compatibility. - Expanded SKILL.md intro and d","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s174hwb34r6ncgdm62n09a9tbd83hn5x:skywork-music-maker","sourceUrl":"https://clawhub.ai/gxcun17/skywork-music-maker","homepage":"https://clawhub.ai/gxcun17/skills/skywork-music-maker","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/gxcun17/skywork-music-maker","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/gxcun17/skills/skywork-music-maker","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":59,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop s..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:14:02.446Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:14:02.446Z","emptyReason":null},"stars":null,"forks":null,"downloads":2234,"packageName":null,"latestVersion":"1.0.4","tractionLabel":"2.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:14:02.445Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T17:14:02.446Z","lastCrawledAt":"2026-10-09T17:14:02.445Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T17:14:02.445Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.4","createdAt":"2026-04-09T12:32:02.909Z","changelog":"**skywork-music-maker 1.0.4 Changelog** - Added `_meta.json` for enhanced metadata and compatibility. - Expanded SKILL.md intro and documentation, now including concise multilingual overviews (Chinese, Japanese, Korean, Spanish). - Improved privacy, data usage, and first-time setup documentation. - Updated and clarified Smart Prompt Conversion workflow, with more international examples and genre coverage. - No core logic changes; full production workflow and validation remain as before.","fileCount":6,"zipByteSize":21192},{"version":"1.0.3","createdAt":"2026-04-09T12:08:49.775Z","changelog":"- Documentation streamlined for clarity: removed multilingual overviews and privacy sections. - No code changes—update is documentation-only. - Instructions for smart prompt conversion, parameter extraction, quality validation, and workflow remain, but are reorganized and simplified. - Adds explicit, concise CLI usage examples and clarifies user/assistant workflow steps. - Summary: The skill’s doc is now easier to read and focused directly on practical usage for everyone.","fileCount":5,"zipByteSize":17492},{"version":"1.0.2","createdAt":"2026-03-18T10:32:55.087Z","changelog":"- Added Openclaw metadata section for improved compatibility and discoverability. - Specified required environment variables and binary dependencies. - Included package installation instructions using `uv` (for `requests`). - Provided official skill homepage link in metadata. - No functional changes to song generation or user workflow.","fileCount":5,"zipByteSize":19831},{"version":"1.0.1","createdAt":"2026-03-18T10:11:25.667Z","changelog":"Skywork Music Maker v1.0.1 - Added multilingual overview sections for Chinese, Japanese, Korean, and Spanish, with key features and usage notes. - Expanded and clarified genre, mood, and instrument parameter examples in the Smart Prompt Conversion workflow to support more languages and musical cultures. - Updated SKILL.md metadata: added multilingual tags, enhanced description for clarity, and included the API key environment variable requirements. - Improved privacy and data usage documentation, explicitly detailing information flows and user consent for uploads. - No code or workflow changes; all updates are in documentation and metadata for broader language support and user clarity.","fileCount":5,"zipByteSize":19894},{"version":"1.0.0","createdAt":"2026-03-16T11:24:42.129Z","changelog":"Skywork Music Maker 1.0.0 – Initial Release - Enables music creation from natural language prompts using the Mureka AI API. - Supports the full workflow: lyric writing, instrumental/song generation, vocal cloning, and reference track uploads. - Smart prompt extraction: automatically converts user descriptions (in any language) into structured music prompts. - Built-in quality checks to ensure prompts include genre, mood, tempo, instrument details, and lyric structure before generating. - CLI-based interface for generating songs, instrumentals, lyrics, and uploading references. - Guides users through API key setup and confirmation workflows to prevent errors.","fileCount":5,"zipByteSize":17487}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s174hwb34r6ncgdm62n09a9tbd83hn5x:skywork-music-maker","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T19:04:37.274Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gxcun17-skywork-music-maker/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T17:14:02.446Z","emptyReason":null},"readme":"Skill: Skywork Music Maker\n\nOwner: gxcun17\n\nSummary: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop s...\n\nTags: latest:1.0.4\n\nVersion history:\n\nv1.0.4 | 2026-04-09T12:32:02.909Z | user\n\n**skywork-music-maker 1.0.4 Changelog**\n\n- Added `_meta.json` for enhanced metadata and compatibility.\n- Expanded SKILL.md intro and documentation, now including concise multilingual overviews (Chinese, Japanese, Korean, Spanish).\n- Improved privacy, data usage, and first-time setup documentation.\n- Updated and clarified Smart Prompt Conversion workflow, with more international examples and genre coverage.\n- No core logic changes; full production workflow and validation remain as before.\n\nv1.0.3 | 2026-04-09T12:08:49.775Z | user\n\n- Documentation streamlined for clarity: removed multilingual overviews and privacy sections.\n- No code changes—update is documentation-only.\n- Instructions for smart prompt conversion, parameter extraction, quality validation, and workflow remain, but are reorganized and simplified.\n- Adds explicit, concise CLI usage examples and clarifies user/assistant workflow steps.\n- Summary: The skill’s doc is now easier to read and focused directly on practical usage for everyone.\n\nv1.0.2 | 2026-03-18T10:32:55.087Z | user\n\n- Added Openclaw metadata section for improved compatibility and discoverability.\n- Specified required environment variables and binary dependencies.\n- Included package installation instructions using `uv` (for `requests`).\n- Provided official skill homepage link in metadata.\n- No functional changes to song generation or user workflow.\n\nv1.0.1 | 2026-03-18T10:11:25.667Z | user\n\nSkywork Music Maker v1.0.1\n\n- Added multilingual overview sections for Chinese, Japanese, Korean, and Spanish, with key features and usage notes.\n- Expanded and clarified genre, mood, and instrument parameter examples in the Smart Prompt Conversion workflow to support more languages and musical cultures.\n- Updated SKILL.md metadata: added multilingual tags, enhanced description for clarity, and included the API key environment variable requirements.\n- Improved privacy and data usage documentation, explicitly detailing information flows and user consent for uploads.\n- No code or workflow changes; all updates are in documentation and metadata for broader language support and user clarity.\n\nv1.0.0 | 2026-03-16T11:24:42.129Z | user\n\nSkywork Music Maker 1.0.0 – Initial Release\n\n- Enables music creation from natural language prompts using the Mureka AI API.\n- Supports the full workflow: lyric writing, instrumental/song generation, vocal cloning, and reference track uploads.\n- Smart prompt extraction: automatically converts user descriptions (in any language) into structured music prompts.\n- Built-in quality checks to ensure prompts include genre, mood, tempo, instrument details, and lyric structure before generating.\n- CLI-based interface for generating songs, instrumentals, lyrics, and uploading references.\n- Guides users through API key setup and confirmation workflows to prevent errors.\n\nArchive index:\n\nArchive v1.0.4: 6 files, 21192 bytes\n\nFiles: _meta.json (138b), README.md (9245b), references/prompt_guide.md (10296b), scripts/mureka.py (10880b), skill-card.md (2660b), SKILL.md (16190b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: skywork-music-maker\ndescription: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop songs, orchestral scores, K-POP, reggaetón, guofeng, and more. Supports vocal cloning, reference track style transfer, lyric writing, and full music production workflows. Just say \"make me a chill lo-fi beat\" or describe any musical idea and this skill handles the rest.\nmetadata:\n  openclaw:\n    requires:\n      env:\n        - MUREKA_API_KEY\n      bins:\n        - python3\n    install:\n      - kind: uv\n        package: requests\n    primaryEnv: MUREKA_API_KEY\n    homepage: https://clawhub.ai/gxcun17/skywork-music-maker\n---\n\n# Skywork Music Maker (Mureka API)\n\nGenerate professional-quality music using the Mureka API at https://api.mureka.ai. This skill covers the complete music production workflow: lyrics writing → song/instrumental generation.\n\n## 多语言简介 | Multilingual Overview\n\n### 中文简介\nSkywork Music Maker 是基于 Mureka AI API 的专业音乐创作工具。支持从自然语言描述生成歌曲、纯音乐和歌词，覆盖完整的音乐制作流程。支持中文输入，可根据中文描述自动生成英文提示词。适用于流行音乐、国风音乐、电子音乐等多种风格。主要功能包括：AI 作词、歌曲生成（含人声）、纯音乐生成、人声克隆、参考音频风格迁移。\n\n### 日本語の概要\nSkywork Music Maker は Mureka AI API を使用したプロフェッショナルな音楽制作ツールです。自然言語の説明から楽曲・インストゥルメンタル・歌詞を生成でき、完全な音楽制作ワークフローをカバーします。日本語入力に対応し、日本語の説明から自動的に英語プロンプトを生成します。ポップス、ロック、J-POP、アニソン風、エレクトロニカなど、多様なジャンルに対応。主な機能：AI 作詞、ボーカル付き楽曲生成、インストゥルメンタル生成、ボーカルクローン、リファレンストラックによるスタイル転写。\n\n### 한국어 개요\nSkywork Music Maker는 Mureka AI API를 기반으로 한 전문 음악 제작 도구입니다. 자연어 설명으로 노래, 인스트루멘탈, 가사를 생성하며 완전한 음악 제작 워크플로우를 지원합니다. 한국어 입력을 지원하며, 한국어 설명에서 자동으로 영어 프롬프트를 생성합니다. K-POP, 발라드, 힙합, 인디, 트로트 등 다양한 장르에 대응합니다. 주요 기능: AI 작사, 보컬 포함 곡 생성, 인스트루멘탈 생성, 보컬 클론, 레퍼런스 트랙 기반 스타일 전사.\n\n### Descripción en español\nSkywork Music Maker es una herramienta profesional de creación musical basada en la API de Mureka AI. Permite generar canciones, instrumentales y letras a partir de descripciones en lenguaje natural, cubriendo el flujo completo de producción musical. Compatible con entrada en español: describe tu idea musical en español y el sistema generará automáticamente prompts optimizados en inglés. Soporta una amplia variedad de géneros: reggaetón, salsa, bachata, cumbia, pop latino, flamenco, bossa nova, rock en español y más. Funciones principales: composición de letras con IA, generación de canciones con vocales, producción de instrumentales, clonación de voz y transferencia de estilo mediante pistas de referencia.\n\n---\n\n## Privacy & Data Usage\n\n- **API endpoint**: All API calls are made exclusively to `https://api.mureka.ai` (official Mureka endpoint by Skywork AI)\n- **Data transmitted**: Lyrics text, music prompts, and uploaded audio files (reference tracks, vocal samples, melodies) are sent to Mureka servers for music generation\n- **No third-party sharing**: No data is sent to any service beyond the official Mureka API\n- **Local output**: Generated audio files and lyrics are saved locally to the user-specified output directory\n- **No local caching of credentials**: The API key is read from the `MUREKA_API_KEY` environment variable at runtime; this skill does not store or cache credentials\n- **User-managed billing**: Users must register their own Mureka account at https://platform.mureka.ai; all usage billing is handled directly by Mureka\n- **Upload consent**: File uploads (reference audio, vocal samples, melodies) are initiated only when the user explicitly requests reference-based or vocal-cloning generation\n\n---\n\n## First-Time Setup\n\nBefore running any API command, check if `MUREKA_API_KEY` is set. If not, guide the user to get an API key at https://platform.mureka.ai/ (register → API Keys → generate key → `export MUREKA_API_KEY=\"...\"`), then **STOP** — do not attempt any API calls until the key is configured.\n\n## Smart Prompt Conversion (CRITICAL WORKFLOW)\n\n**Default behavior**: When the user doesn't specify song type, always generate a song with lyrics (use `mureka.py song`). Only use `mureka.py instrumental` when the user explicitly asks for instrumental, BGM, background music, or \"no vocals\".\n\n**Output defaults**: Use mp3 format unless the user requests otherwise. The `--output` flag specifies a directory — the script creates it and saves all results inside (audio files + lyrics.txt for songs). If the user doesn't specify a location, choose a user-friendly path with a descriptive folder name based on the song theme (e.g., `summer_pop_song/`).\n\nWhen users provide music descriptions in natural language (in any language), you **MUST** convert them to structured Mureka API prompts using this workflow:\n\n### Conversion Process\n\n**User Input Examples:**\n- \"upbeat pop song, female vocals, guitar, perfect for summer\"\n- \"sad piano ballad about lost love\"\n- \"epic orchestral music for a fantasy game\"\n- \"traditional Chinese music with bamboo flute and zither, misty atmosphere\"\n- \"明るいJ-POP風の夏の曲を作って\" (Japanese: bright J-POP style summer song)\n- \"슬픈 발라드 만들어줘, 피아노 위주로\" (Korean: make a sad ballad, piano-focused)\n- \"做一首国风古典音乐，要有二胡和古筝\" (Chinese: make a guofeng classical piece with erhu and guzheng)\n- \"Hazme una canción de reggaetón romántico con guitarra acústica\" (Spanish: make a romantic reggaeton song with acoustic guitar)\n\n**Your Task:**\n1. Extract structured parameters using the extraction rules below\n2. Validate the prompt meets quality standards (see Quality Checklist)\n3. Present to user for confirmation before generating\n4. Run the generation command with the structured prompt\n\n### Parameter Extraction Rules\n\nWhen users provide natural language music descriptions, directly extract and structure the following parameters:\n\n**Required Parameters:**\n- **genres**: music genres including fusion styles (e.g., Pop, Rock, Jazz, Pop Rap Fusion, Alternative Rock, Guofeng, J-POP, K-POP, Trot, Reggaetón, Salsa, Bachata, Cumbia, Flamenco, Bossa Nova)\n- **moods**: emotional tones (e.g., Happy, Melancholic, Energetic, Nostalgic, Bright)\n- **instruments**: specific instruments (e.g., Piano, Guitar, Drums, Erhu, Guzheng, Synth Pads, Dizi, Shamisen, Gayageum, Cajón, Congas, Bongos, Tres, Charango)\n- **rhythms**: rhythm characteristics (e.g., 4/4, Slow, Syncopated, Driving, Flowing)\n- **vocals**: vocal attributes (e.g., Female, Husky, Whispered, Male, Soft, Clear) or \"instrumental only\"\n- **key**: musical key if specified (e.g., C Major, A Minor, C# Major)\n- **bpm**: beats per minute (e.g., 120) or tempo descriptor (e.g., \"slow groove\", \"uptempo\")\n- **description**: concise summary (under 50 words) capturing mood progression, melody, harmony, timbre, texture, dynamics\n\n**Extraction Instructions:**\n- **Translate non-English terms**: Convert ALL non-English musical terms to English while preserving cultural and musical meaning\n- **Preserve specificity**: Keep detailed information including specific styles, subgenres, and cultural context (e.g., \"Chinese traditional guofeng\" not just \"Chinese music\")\n- **Design dynamic arc**: Include mood progression where appropriate (e.g., \"sparse opening → building tension → cathartic chorus\")\n- **Infer intelligently**: Make reasonable assumptions based on genre conventions when parameters are not explicitly stated\n- **English output**: Final prompt string MUST be entirely in English\n\n**Generate Structured Prompt:** Combine all extracted parameters into a comprehensive, natural-flowing description that captures the essence of the user's vision.\n\n### Quality Checklist (Validate BEFORE Generation)\n\nBefore running the generation command, verify the prompt meets these criteria:\n\n**MUST HAVE:**\n- ☑ Specific genre (NOT \"pop song\" but \"synth-pop, 2020s\")\n- ☑ BPM or tempo descriptor (e.g., \"120 BPM\" or \"slow groove\")\n- ☑ 3-5 instruments explicitly named\n- ☑ Mood/emotion descriptors (2-3 words)\n- ☑ Vocal style (or \"instrumental only\")\n- ☑ Structure tags in lyrics: [Verse], [Chorus], [Bridge], [Outro]\n\n**WATCH OUT FOR:**\n- Vague terms: \"nice\", \"good\", \"beautiful\" → replace with specific descriptors\n- Contradictions: \"slow\" + \"energetic\", \"sad\" + \"uplifting\" → pick one direction\n- Too short: <50 chars → add more detail\n- Long lyric lines: >10 words per line → split into shorter lines\n- No dynamic arc: add mood progression (e.g., \"sparse → building → full\")\n\n**AVOID:**\n- Command verbs: \"create a song\" → use descriptions \"upbeat pop song\"\n- Famous artist names: \"sounds like Taylor Swift\" → describe qualities instead\n- Unrealistic combos: melody_id cannot combine with other control options\n\nAfter validation, present the generated prompt to the user for confirmation before proceeding.\n\n---\n\n## Core Workflow: Production Pipeline\n\n1. **Conceptualize** → User describes in natural language → YOU convert to structured prompt\n2. **Validate** → Check prompt quality against Quality Checklist (see above)\n3. **Write Lyrics** → Use lyrics/generate or write manually\n4. **Upload References** → Optional: reference track, vocal sample, melody\n5. **Generate** → Submit song/instrumental task (async) with validated prompt\n6. **Evaluate** → Listen to all N choices, pick best\n7. **Iterate** → Refine prompt based on what you heard\n\n**Critical Steps:**\n- Step 1 is mandatory when user provides natural language input (especially non-English)\n- Step 2 validation prevents 80% of common generation failures\n- Step 3: Read `references/prompt_guide.md` for prompt crafting examples, lyrics structure rules (line length, syllable count, rhyme patterns, hook writing), and iteration best practices\n- Do NOT skip conceptualization — jumping straight to generation without a clear concept is the #1 reason for generic results\n\n**Your Role as AI Assistant:**\n1. Convert user's natural language → structured Mureka prompt (using Smart Prompt Conversion)\n2. Validate prompt quality → flag issues → suggest fixes\n3. Write or generate lyrics with proper structure\n4. Present prompt to user for confirmation\n5. Execute generation command with validated prompt\n6. Help iterate and refine based on generation results\n\n---\n\n## CLI Tool\n\nAll operations go through a single script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\nRun `python scripts/mureka.py --help` for full usage. Note: use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n## Common Scenarios\n\n### \"I just want background music for my video\"\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion, background music for tech product video\" \\\n  --output ./bg_music\n```\n\n### \"I want a song but don't have lyrics\"\n```bash\n# Step 1: Generate lyrics with proper structure\npython scripts/mureka.py lyrics generate \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Copy/refine the output, then generate the song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste lyrics here)\\n[Chorus]\\n(paste chorus here)\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, soft drums, male vocal\" \\\n  --output ./summer_song\n```\n\n---\n\n## Advanced Features\n\n### Reference-Based Generation\nUpload a reference track (must be exactly 30s, mp3/m4a) to guide the style:\n```bash\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# → File ID: 542321\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --reference-id 542321 --output ./song\n```\n\n### Vocal Cloning\nUpload a vocal sample (15-30s, mp3/m4a) to use a specific voice:\n```bash\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# → File ID: 789012\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --vocal-id 789012 --prompt \"R&B, smooth, 90 BPM\" --output ./song\n```\n\n---\n\n## Control Options & Rules\n\n### Song Generation Control Combos\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- `melody_id` does NOT support any combination — use it alone\n- `prompt` and `reference_id` are mutually exclusive — use one or the other\n\n### Instrumental Generation Rules\nFor instrumentals, `prompt` and `instrumental_id` are mutually exclusive — use one or the other.\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| reference | mp3/m4a | exactly 30s | Excess trimmed |\n| vocal | mp3/m4a | 15-30s | Excess trimmed |\n| melody | mp3/m4a/mid | 5-60s | MIDI recommended |\n| instrumental | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\nAlways use `mureka-8` — it is the latest and highest quality model.\n\n---\n\n## Error Handling\n\nScripts raise `RuntimeError` or `requests.HTTPError` on failure. Handle common errors:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| 401 Unauthorized | Invalid or expired API key | Ask user to verify `MUREKA_API_KEY` |\n| 429 Too Many Requests | Rate limit exceeded | Wait 30-60 seconds, then retry |\n| 402 / Insufficient balance | Account balance depleted | Direct user to https://platform.mureka.ai to top up |\n| Task ended with status: failed | Generation failed (bad prompt, server error) | Check prompt against Quality Checklist, retry |\n| Task ended with status: timeouted | Generation took too long | Retry; if persistent, simplify the prompt or try a different model |\n| ConnectionError / Timeout | Network issue | Retry after a few seconds |\n\n**General strategy:** Read the error message carefully. If it's a client error (4xx), fix the input. If it's a server error (5xx) or timeout, retry once before escalating to the user.\n\n## Troubleshooting Common Issues\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | Check prompt meets quality checklist; verify lyrics have structure tags; retry the generation |\n| Vocals sound rushed | Shorten lyric lines (≤10 words); reduce syllables per line |\n| Listed instruments not audible | Verify each instrument named explicitly in prompt; add more specific descriptors |\n| Prompt doesn't match output | Increase specificity (exact genre, BPM, instruments); add mood progression; generate n=3 choices |\n| melody_id error | melody_id MUST be used alone — remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | File IDs only valid for account that uploaded — re-upload file if from another session |\n\nFor parameter help:\n```bash\npython scripts/mureka.py --help\npython scripts/mureka.py song --help\n```\n\n---\n\n## Environment\n\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **Base URL**: https://api.mureka.ai\n- **Dependencies**: Python 3, `requests` library\n- **Billing**: Check balance with `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\nFile v1.0.4:README.md\n\n# Skywork Music Maker 1.0.0\n\nAI-powered music generation skill for Claude Code and other AI agent frameworks. Create professional songs, instrumentals, and lyrics using Mureka AI API with natural language descriptions in any language.\n\n## Quick Links\n\n- **[SKILL.md](SKILL.md)** - Complete agent guide (start here)\n- **[references/prompt_guide.md](references/prompt_guide.md)** - Music craftsmanship guide (MANDATORY reading for lyrics tasks)\n- **[scripts/mureka.py](scripts/mureka.py)** - Unified CLI tool for all operations\n\n## Installation\n\n### For Claude Code / Codex\n```bash\n# Option 1: Use directly from this repo\n# Reference as: @skywork-music-maker-1.0.0\n\n# Option 2: Install to ~/.claude/skills\ncp -r skywork-music-maker-1.0.0 ~/.claude/skills/\n```\n\n### For Gemini CLI\n```bash\n# Install to skills directory (check your platform's docs)\ncp -r skywork-music-maker-1.0.0 /path/to/gemini/skills/\n```\n\n### For Other AI Frameworks\nCopy the directory to your framework's skills location. The skill follows standard conventions and should work with any framework supporting tool-based agents.\n\n## Key Features\n\n✅ **Natural language to music** - Describe in any language, get structured prompts\n✅ **Smart validation** - Quality checks before generation\n✅ **Complete workflow** - Lyrics → Song/Instrumental → Analysis → Extension\n✅ **Unified CLI** - Single `mureka.py` script for all operations\n✅ **Agent-optimized** - Self-documenting code, clear documentation structure\n✅ **Production-ready** - Best practices from real music production practitioners\n\n## Quick Start\n\n### 1. Set up API key\n\n```bash\n# Get your API key from https://platform.mureka.ai\nexport MUREKA_API_KEY=\"your_api_key\"\n```\n\n### 2. Generate music with natural language\n\n```bash\n# The AI agent will convert your description to a structured prompt\nUser: \"create an upbeat summer pop song with female vocals\"\nAI: [Converts to structured prompt, validates, generates]\n\n# Or use the CLI directly\ncd scripts/\npython mureka.py song \\\n  --lyrics \"[Verse]\\nWalking down the beach...\" \\\n  --prompt \"indie pop, 110 BPM, acoustic guitar, female vocal, warm and nostalgic\" \\\n  --output ./my_song\n```\n\n### 3. Check the results\n\n```bash\n# Generated files will be in the output directory:\nls ./my_song/\n# output_0.mp3  output_1.mp3  lyrics.txt\n```\n\n## CLI Tool\n\nAll operations use a single unified script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics using AI\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\n**Usage:**\n```bash\npython scripts/mureka.py --help              # Show all commands\npython scripts/mureka.py song --help         # Song-specific options\npython scripts/mureka.py instrumental --help # Instrumental options\npython scripts/mureka.py lyrics --help       # Lyrics generation options\npython scripts/mureka.py upload --help       # Upload options\n```\n\n**Important:** Use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n## Common Scenarios\n\n### Background music for videos\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion\" \\\n  --output ./bg_music\n```\n\n### Song without lyrics yet\n```bash\n# Step 1: Generate lyrics\npython scripts/mureka.py lyrics generate \\\n  \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Use the generated lyrics for your song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste generated lyrics here)\\n[Chorus]\\n...\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, male vocal\" \\\n  --output ./summer_song\n```\n\n### With reference track (style transfer)\n```bash\n# Upload 30-second reference track\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# Returns: File ID: 542321\n\n# Generate song using that style\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --reference-id 542321 \\\n  --output ./song_with_style\n```\n\n### Vocal cloning\n```bash\n# Upload 15-30 second vocal sample\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# Returns: File ID: 789012\n\n# Generate song with cloned voice\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --vocal-id 789012 \\\n  --prompt \"R&B, smooth, 90 BPM, emotional\" \\\n  --output ./cloned_voice_song\n```\n\n## File Structure\n\n```\nskywork-music-maker-1.0.0/\n├── SKILL.md                    # Complete agent guide\n├── README.md                   # This file\n├── references/\n│   └── prompt_guide.md        # Music craftsmanship guide (MANDATORY for lyrics)\n└── scripts/\n    └── mureka.py              # Unified CLI tool (use --help for docs)\n```\n\n## Smart Prompt Conversion\n\nWhen you describe music in natural language (in any language), the AI agent automatically:\n\n1. **Extracts structured parameters** - Genres, moods, instruments, BPM, vocals, key\n2. **Validates quality** - Checks against quality checklist to prevent generation failures\n3. **Presents for confirmation** - Shows you the structured prompt before generation\n4. **Executes generation** - Runs the API call with the validated prompt\n\nThis prevents 80% of common generation failures and ensures high-quality results.\n\n## Control Options & Requirements\n\n### Song Generation Combinations\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- `melody_id` does NOT support any combination — use it alone\n- `prompt` and `reference_id` are mutually exclusive\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| `reference` | mp3/m4a | exactly 30s | Excess trimmed |\n| `vocal` | mp3/m4a | 15-30s | Excess trimmed |\n| `melody` | mp3/m4a/mid | 5-60s | MIDI recommended |\n| `instrumental` | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\n\nAlways use `mureka-8` — it is the latest and highest quality model (default in scripts).\n\n## Error Handling\n\nCommon errors and solutions:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `401 Unauthorized` | Invalid/expired API key | Verify `MUREKA_API_KEY` |\n| `429 Too Many Requests` | Rate limit exceeded | Wait 30-60 seconds, retry |\n| `402 / Insufficient balance` | Account depleted | Top up at https://platform.mureka.ai |\n| `Task failed` | Bad prompt/server error | Check Quality Checklist, retry |\n| `Task timeouted` | Generation took too long | Simplify prompt, retry |\n| `ConnectionError` | Network issue | Retry after a few seconds |\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | • Check prompt meets quality checklist<br>• Verify lyrics have structure tags<br>• Retry |\n| Vocals sound rushed | • Shorten lyric lines (≤10 words)<br>• Reduce syllables per line |\n| Instruments not audible | • Name each instrument explicitly<br>• Add specific descriptors (e.g., \"acoustic guitar strumming\") |\n| Output doesn't match prompt | • Increase specificity (exact genre, BPM)<br>• Add mood progression (\"sparse → full\")<br>• Generate n=3 choices |\n| melody_id error | • melody_id MUST be used alone<br>• Remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | • File IDs only valid for uploading account<br>• Re-upload if from another session |\n\n## Environment Requirements\n\n- **Python**: 3.7+\n- **Dependencies**: `requests` library (`pip install requests`)\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **API Base URL**: `https://api.mureka.ai`\n\n## Support & Resources\n\n- **Issues & Feedback**: [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)\n- **Mureka API Docs**: [platform.mureka.ai](https://platform.mureka.ai)\n- **Get API Key**: [platform.mureka.ai](https://platform.mureka.ai) → Register → API Keys → Generate\n- **Check Balance**: `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\n## Examples\n\n### Traditional Chinese Music\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n春风拂面...\" \\\n  --prompt \"Chinese traditional guofeng, 90 BPM, bamboo flute (dizi), guzheng, erhu, misty atmosphere, ancient poetry aesthetic\" \\\n  --output ./chinese_style\n```\n\n### Electronic Dance Music\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"progressive house, 128 BPM, synth leads, deep bass, atmospheric pads, building energy\" \\\n  -n 3 \\\n  --output ./edm_track\n```\n\n### Jazz Ballad\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\nUnder the midnight sky...\" \\\n  --prompt \"jazz ballad, slow groove, piano, upright bass, soft brushed drums, female husky vocal, intimate\" \\\n  --output ./jazz_ballad\n```\n\n## License\n\nSame as parent repository.\n\n---\n\n**For detailed music production guidance, prompt crafting examples, and lyric writing best practices, see [references/prompt_guide.md](references/prompt_guide.md).**\n\nFile v1.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn70ct0m3p4538a9t49cjcwern82ky02\",\n  \"slug\": \"skywork-music-maker\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1775737922909\n}\n\nFile v1.0.4:references/prompt_guide.md\n\n# Music Prompt Crafting Guide\n\nComprehensive guide to writing effective music prompts for Mureka AI.\n\n## The Golden Rule: DESCRIBE, Don't Command\n\n```\n❌ \"Create an energetic pop song with drums\"\n✅ \"energetic pop, driving four-on-the-floor drums, bright synth hooks, 128 BPM, female vocal, festival anthem vibe\"\n```\n\nThe AI responds to descriptions of the music, not instructions to \"make\" or \"create\" it.\n\n---\n\n## Design a Dynamic Arc, Not a Static Description\n\nThe most common reason AI-generated songs sound flat is that the prompt describes one mood level throughout. Great songs are tension/release journeys — design yours explicitly.\n\nExpress the arc as a **mood progression string** in your prompt:\n```\n✅ \"sparse and intimate opening → rising tension → full cathartic chorus → stripped-back bridge → bigger final chorus\"\n✅ \"melancholic and sparse → building urgency → explosive release → quiet resolution\"\n```\n\nThe AI interprets this as an emotional journey across the song. Without it, every section gets the same energy and density.\n\n---\n\n## Effective Prompt Structure\n\n### Minimum Viable Prompt (always include these)\n```\n[genre + sub-genre], [mood/emotion], [tempo/BPM], [key instruments], [vocal style]\n```\n\n### Standard Prompt (recommended for good results)\n```\nGenre: [specific genre + era, e.g., \"90s trip-hop\"]\nMood: [2-3 descriptors, e.g., \"melancholic, introspective, nocturnal\"]\nTempo: [BPM or description, e.g., \"85 BPM, slow groove\"]\nInstruments: [3-5 key instruments, e.g., \"turntable scratches, Rhodes piano, upright bass\"]\nVocals: [style, e.g., \"breathy female vocals, intimate delivery\"]\nScene: [usage context, e.g., \"late-night city driving\"]\n```\n\n### Production Brief (for maximum control)\n```\nGenre: trip-hop | Era: mid-90s Bristol\nBPM: 85 | Key: D minor\nMood: melancholic → building tension → cathartic release\nLead: Rhodes piano, tremolo\nRhythm: breakbeat, vinyl crackle texture\nBass: deep sub-bass, Moog-style\nTexture: tape saturation, lo-fi warmth\nVocals: breathy female, close-mic intimacy\nStructure: Intro(8bars) / Verse / Chorus / Verse / Bridge / Chorus / Outro\nAvoid: auto-tune, bright synths, four-on-the-floor kick\nReference: Portishead \"Roads\" (breakbeat texture, Rhodes tone)\n```\n\n**Note on references**: Only use specific songs as sonic benchmarks when all other parameters are already specified. Different from \"sound like [artist]\" — use for named production qualities (e.g., \"Roads-style breakbeat texture\").\n\n---\n\n## What Makes Prompts FAIL (Top 7 Mistakes)\n\n| # | Mistake | Why It Fails | Fix |\n|---|---------|-------------|-----|\n| 1 | **Vague prompts** (\"nice pop song\") | AI defaults to the statistical average — generic, forgettable | Be ruthlessly specific: sub-genre + era + mood + instruments + BPM |\n| 2 | **Contradictions** (\"slow and relaxing, high energy, 160 BPM\") | Conflicting signals make the AI unpredictable | Check every descriptor agrees with the mood. Pick one direction |\n| 3 | **\"Sound like [famous artist]\"** | Copyright risk + AI interprets literally, often misses the point | Describe the *qualities* you like: \"warm analog synths, driving bass, 80s production style\" |\n| 4 | **Too many words per lyric line** | AI rushes through words → slurred, unnatural vocals | Keep lines ≤10 words. Short lines = better vocal delivery |\n| 5 | **No structure tags in lyrics** | Song has no shape — verse/chorus blur together | Always use [Verse], [Chorus], [Bridge], [Outro] tags |\n| 6 | **Rewriting entire prompt between iterations** | Can never isolate what improved (or worsened) the output | Change ONE element at a time. A/B test systematically |\n| 7 | **Ignoring negative prompts** | Unwanted elements creep in (auto-tune, trap hi-hats, reverb) | Explicitly state what to avoid: \"no auto-tune, avoid heavy reverb\" |\n\n---\n\n## Effective vs Ineffective — Side-by-Side Examples\n\n### Example 1: Pop Song\n```\n❌ \"A pop song about love that sounds good\"\n✅ \"bright synth-pop, uplifting, 120 BPM, arpeggiated synths, punchy electronic drums, female vocal with light reverb, 2020s clean production, summer anthem feel\"\n```\n\n### Example 2: Lo-Fi Background\n```\n❌ \"lofi music for studying\"\n✅ \"lo-fi hip-hop, warm and mellow, 75 BPM, dusty vinyl crackle, jazzy Rhodes chords, muted boom-bap drums, no vocals, late-night study session atmosphere\"\n```\n\n### Example 3: Cinematic\n```\n❌ \"epic movie music\"\n✅ \"cinematic orchestral, tension building to triumphant climax, 95 BPM, strings staccato → legato swell, French horns, timpani rolls, choir in final section, Hans Zimmer-style layered percussion\"\n```\n\n### Example 4: Rock Song\n```\n❌ \"energetic rock song, male vocals, guitar solo\"\n✅ \"alternative rock, energetic and raw, 140 BPM, distorted electric guitar riffs, driving bass line, punchy drums, raspy male vocals, anthemic chorus, guitar solo section, garage rock aesthetic, festival anthem energy\"\n```\n\n### Example 5: Traditional Chinese\n```\n❌ \"Chinese music, sad\"\n✅ \"Chinese traditional guofeng, melancholic and nostalgic, 60 BPM, dizi bamboo flute lead melody, guzheng plucked strings, subtle erhu, misty atmosphere, Jiangnan water town imagery, rain and mist soundscape, instrumental only\"\n```\n\n---\n\n## Lyrics Writing: What Separates Good from Bad\n\n### Structure Tags (always use these)\n\n```\n[Intro]\n[Verse]\n[Pre-Chorus]\n[Chorus]\n[Bridge]\n[Break]\n[Outro]\n```\n\n**Standard structure order**: Verse → Chorus → Verse → Chorus → Bridge → Final Chorus → Outro. The Bridge always appears after the second chorus — never before the first.\n\nIf your generated bridge sounds like a second verse, regenerate it with:\n```bash\npython generate_lyrics.py extend \"<existing lyrics>\" \"write a contrasting bridge that shifts perspective, strips back to a single instrument, and sets up the final chorus\"\n```\n\n### Golden Rules for Lyrics That Sing Well\n\n1. **Keep lines short** — 6-10 words per line. Long lines get rushed.\n   ```\n   ❌ \"I've been walking through the streets of this old town thinking about everything we used to do together\"\n   ✅ \"Walking through the old town streets\\n   Thinking of what we used to be\"\n   ```\n\n2. **Match syllable count across verse lines** — Creates natural rhythm.\n   ```\n   ✅ \"Shadows fall on empty streets\"    (7 syllables)\n      \"Whispers lost in evening heat\"    (7 syllables)\n      \"Dancing lights through window panes\" (7 syllables)\n   ```\n\n3. **Use rhyme patterns intentionally** — ABAB or AABB, not random.\n   ```\n   ✅ [Verse]\n      The city sleeps beneath the stars (A)\n      While dreamers chase the fading light (B)\n      We trace our names on passing cars (A)\n      And disappear into the night (B)\n   ```\n\n4. **Chorus should be simpler and more repetitive than verses** — Fewer words, not more. Whitespace and repetition create impact; repetition IS the melody.\n\n5. **Don't over-explain in lyrics** — Imagery > exposition.\n\n---\n\n## Writing a Memorable Hook\n\nThe hook is the most important line in your song. Get it right:\n\n### 1. Length and singability\n4-8 words, singable on first listen, usually contains the song's title.\n\n```\n✅ \"I will always love you\" — simple, universal, title, singable\n✅ \"Rolling in the deep\" — 4 words, vivid, singable\n❌ \"I feel the way I feel when I think about our story\" — too long, too vague\n```\n\n### 2. End chorus lines on open vowels\nAI vocals hold the last syllable of each line. Open vowels (oh, ah, ay, ee) sustain beautifully. Closed consonants (mm, th, ff, ss) sound awkward when held.\n\n```\n✅ \"Let me go\" → ends on \"oh\" — sustains well\n❌ \"Let me breathe\" → ends on closed \"th\" sound — awkward to hold\n```\n\n### 3. Chorus density\nA chorus should have FEWER words than a verse, not more. The space around the hook gives it impact.\n\n```\n❌ \"I feel sad because you left me and now I'm alone\"\n✅ \"Empty chair across the table\\n   Coffee cold, the morning grey\"\n```\n\n---\n\n## Auto-Generate Lyrics First, Then Refine\n\n```bash\n# Generate lyrics from a concept\npython generate_lyrics.py generate \"a bittersweet farewell song, two old friends parting ways after summer\"\n\n# Extend if you need more sections\npython generate_lyrics.py extend \"[Verse]\\nThe last light paints the pier in gold...\"\n```\n\n---\n\n## Iteration Strategy (How Pros Refine)\n\n1. **First generation**: Use your best-guess prompt + n=3\n2. **Listen to all choices**: Note what's good and what's off\n3. **Adjust ONE element**: If rhythm is wrong → change BPM/drums description. If mood is off → change mood descriptors\n4. **Re-generate**: Same lyrics, tweaked prompt\n5. **Compare**: Does the change improve or worsen?\n6. **Repeat** until satisfied\n\n### What to Listen For\n\n**For vocal songs:**\n| Symptom | Fix |\n|---------|-----|\n| Vocals feel rushed / words swallowed | Shorten lyric lines, reduce syllables per line |\n| No energy build between verse and chorus | Add mood progression arc to prompt (e.g., \"sparse → full cathartic release\") |\n| Hook doesn't stick | Simplify chorus to 4-8 words, repeat title phrase, check lines end on open vowels |\n| Tempo feels wrong | Adjust BPM ±10 and regenerate |\n| Listed instruments not audible | Verify each instrument is named explicitly in the prompt |\n\n**For instrumentals / ambient:**\n| Symptom | Fix |\n|---------|-----|\n| Tempo feels wrong | Adjust BPM ±10 |\n| Mood doesn't match intent | Audit all mood descriptors for internal consistency |\n| Instruments missing | Verify each is named explicitly in the prompt |\n\n**Never rewrite the entire prompt at once.** You'll lose track of what works.\n\n---\n\n## Production Checklist (Before You Generate)\n\nBefore hitting generate, verify:\n\n- [ ] **Genre is specific**: Not just \"pop\" but \"synth-pop, 2020s, clean production\"\n- [ ] **Mood is consistent**: No contradictions (slow + energetic = confused AI)\n- [ ] **BPM is set**: Even approximate (\"~90 BPM, slow groove\") helps\n- [ ] **3-5 instruments listed**: Gives the AI sonic anchors\n- [ ] **Vocal style specified**: Or \"no vocals\" / \"instrumental only\"\n- [ ] **Lyrics have structure tags**: [Verse], [Chorus], [Bridge], [Outro]\n- [ ] **Lines are short**: ≤10 words per line\n- [ ] **Avoid list included**: What you DON'T want (auto-tune, trap hi-hats, etc.)\n- [ ] **N > 1**: Generate 2-3 choices and pick the best. Never rely on a single generation\n\nFile v1.0.4:skill-card.md\n\n## Description:\n\nSkywork Music Maker helps agents turn multilingual music descriptions into structured Mureka API prompts and generate songs, instrumentals, lyrics, and uploaded-reference music workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[gxcun17](https://clawhub.ai/user/gxcun17)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to guide agents through music prompt shaping, lyrics creation, Mureka API calls, reference uploads, vocal cloning workflows, and local audio-file output.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Vocal cloning and reference-track workflows can upload voice samples or copyrighted audio without clear consent safeguards.\n\nMitigation: Use only voice samples and reference audio that the user owns or has documented permission to use, and review vocal-cloning requests before running upload commands.\n\nRisk: Prompts, lyrics, and uploaded audio are transmitted to the Mureka API for generation.\n\nMitigation: Tell users what data will be sent before generation or upload, and avoid sending confidential or sensitive content.\n\nRisk: The documented billing curl pattern can expose MUREKA_API_KEY locally on shared or monitored machines.\n\nMitigation: Prefer commands or clients that read MUREKA_API_KEY from the process environment without placing the token directly in shell history or process listings.\n\nRisk: Unpinned dependency installation can reduce reproducibility.\n\nMitigation: Pin the requests dependency in controlled deployments.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/gxcun17/skills/skywork-music-maker)\n- [OpenClaw Homepage](https://clawhub.ai/gxcun17/skywork-music-maker)\n- [Music Prompt Crafting Guide](references/prompt_guide.md)\n- [Mureka API Endpoint](https://api.mureka.ai)\n- [Mureka Platform](https://platform.mureka.ai)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, files]\n\n**Output Format:** [Markdown guidance with inline shell commands and local audio or lyrics files produced by the CLI]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires MUREKA_API_KEY and sends prompts, lyrics, and uploaded audio to the Mureka API when generation or upload commands are run.]\n\n## Skill Version(s):\n\n1.0.4 (source: release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.3: 5 files, 17492 bytes\n\nFiles: README.md (9245b), references/prompt_guide.md (10296b), scripts/mureka.py (10880b), SKILL.md (12005b), _meta.json (138b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: skywork-music-maker\ndescription: Skywork Music Maker (skywork) - Create professional music with the Mureka AI API: songs, instrumentals, and lyrics from natural language descriptions in any language. Use when users want to generate a song, create a beat or instrumental, write lyrics, clone vocals, upload reference tracks, or do anything related to AI music creation, even casual requests like \"make me a chill lo-fi beat\".\n---\n\n# Skywork Music Maker (Mureka API)\n\nGenerate professional-quality music using the Mureka API at `https://api.mureka.ai`. This skill covers the **complete music production workflow**: lyrics writing → song/instrumental generation.\n\n## First-Time Setup\n\nBefore running any API command, check if `MUREKA_API_KEY` is set. If not, guide the user to get an API key at https://platform.mureka.ai/ (register → API Keys → generate key → `export MUREKA_API_KEY=\"...\"`), then STOP — do not attempt any API calls until the key is configured.\n\n---\n\n## Smart Prompt Conversion (CRITICAL WORKFLOW)\n\n**Default behavior**: When the user doesn't specify song type, always generate a **song with lyrics** (use `mureka.py song`). Only use `mureka.py instrumental` when the user explicitly asks for instrumental, BGM, background music, or \"no vocals\".\n\n**Output defaults**: Use mp3 format unless the user requests otherwise. The `--output` flag specifies a directory — the script creates it and saves all results inside (audio files + `lyrics.txt` for songs). If the user doesn't specify a location, choose a user-friendly path with a descriptive folder name based on the song theme (e.g., `summer_pop_song/`).\n\nWhen users provide music descriptions in **natural language** (in any language), you MUST convert them to structured Mureka API prompts using this workflow:\n\n### Conversion Process\n\n**User Input Examples:**\n- \"upbeat pop song, female vocals, guitar, perfect for summer\"\n- \"sad piano ballad about lost love\"\n- \"epic orchestral music for a fantasy game\"\n- \"traditional Chinese music with bamboo flute and zither, misty atmosphere\"\n\n**Your Task:**\n1. **Extract structured parameters** using the extraction rules below\n2. **Validate** the prompt meets quality standards (see Quality Checklist)\n3. **Present to user** for confirmation before generating\n4. **Run the generation** command with the structured prompt\n\n### Parameter Extraction Rules\n\nWhen users provide natural language music descriptions, directly extract and structure the following parameters:\n\n**Required Parameters:**\n- **genres**: music genres including fusion styles (e.g., Pop, Rock, Jazz, Pop Rap Fusion, Alternative Rock, Guofeng)\n- **moods**: emotional tones (e.g., Happy, Melancholic, Energetic, Nostalgic, Bright)\n- **instruments**: specific instruments (e.g., Piano, Guitar, Drums, Erhu, Guzheng, Synth Pads, Dizi)\n- **rhythms**: rhythm characteristics (e.g., 4/4, Slow, Syncopated, Driving, Flowing)\n- **vocals**: vocal attributes (e.g., Female, Husky, Whispered, Male, Soft, Clear) or \"instrumental only\"\n- **key**: musical key if specified (e.g., C Major, A Minor, C# Major)\n- **bpm**: beats per minute (e.g., 120) or tempo descriptor (e.g., \"slow groove\", \"uptempo\")\n- **description**: concise summary (under 50 words) capturing mood progression, melody, harmony, timbre, texture, dynamics\n\n**Extraction Instructions:**\n1. **Translate non-English terms**: Convert ALL non-English musical terms to English while preserving cultural and musical meaning\n2. **Preserve specificity**: Keep detailed information including specific styles, subgenres, and cultural context (e.g., \"Chinese traditional guofeng\" not just \"Chinese music\")\n3. **Design dynamic arc**: Include mood progression where appropriate (e.g., \"sparse opening → building tension → cathartic chorus\")\n4. **Infer intelligently**: Make reasonable assumptions based on genre conventions when parameters are not explicitly stated\n5. **English output**: Final prompt string MUST be entirely in English\n\n**Generate Structured Prompt:**\nCombine all extracted parameters into a comprehensive, natural-flowing description that captures the essence of the user's vision.\n\n### Quality Checklist (Validate BEFORE Generation)\n\nBefore running the generation command, verify the prompt meets these criteria:\n\n**MUST HAVE:**\n- [ ] Specific genre (NOT \"pop song\" but \"synth-pop, 2020s\")\n- [ ] BPM or tempo descriptor (e.g., \"120 BPM\" or \"slow groove\")\n- [ ] 3-5 instruments explicitly named\n- [ ] Mood/emotion descriptors (2-3 words)\n- [ ] Vocal style (or \"instrumental only\")\n- [ ] Structure tags in lyrics: [Verse], [Chorus], [Bridge], [Outro]\n\n**WATCH OUT FOR:**\n- Vague terms: \"nice\", \"good\", \"beautiful\" → replace with specific descriptors\n- Contradictions: \"slow\" + \"energetic\", \"sad\" + \"uplifting\" → pick one direction\n- Too short: <50 chars → add more detail\n- Long lyric lines: >10 words per line → split into shorter lines\n- No dynamic arc: add mood progression (e.g., \"sparse → building → full\")\n\n**AVOID:**\n- Command verbs: \"create a song\" → use descriptions \"upbeat pop song\"\n- Famous artist names: \"sounds like Taylor Swift\" → describe qualities instead\n- Unrealistic combos: melody_id cannot combine with other control options\n\nAfter validation, present the generated prompt to the user for confirmation before proceeding.\n\n---\n\n## Core Workflow: Production Pipeline\n\n```\n1. Conceptualize → User describes in natural language → YOU convert to structured prompt\n2. Validate → Check prompt quality against Quality Checklist (see above)\n3. Write Lyrics → Use lyrics/generate or write manually\n4. Upload References → Optional: reference track, vocal sample, melody\n5. Generate → Submit song/instrumental task (async) with validated prompt\n6. Evaluate → Listen to all N choices, pick best\n7. Iterate → Refine prompt based on what you heard\n```\n\n**Critical Steps:**\n- **Step 1 is mandatory** when user provides natural language input (especially non-English)\n- **Step 2 validation** prevents 80% of common generation failures\n- **Step 3**: Read `references/prompt_guide.md` for prompt crafting examples, lyrics structure rules (line length, syllable count, rhyme patterns, hook writing), and iteration best practices\n- **Do NOT skip conceptualization** — jumping straight to generation without a clear concept is the #1 reason for generic results\n\n**Your Role as AI Assistant:**\n1. Convert user's natural language → structured Mureka prompt (using Smart Prompt Conversion)\n2. Validate prompt quality → flag issues → suggest fixes\n3. Write or generate lyrics with proper structure\n4. Present prompt to user for confirmation\n5. Execute generation command with validated prompt\n6. Help iterate and refine based on generation results\n\n---\n\n## CLI Tool\n\nAll operations go through a single script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\nRun `python scripts/mureka.py --help` for full usage. Note: use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n---\n\n## Common Scenarios\n\n### \"I just want background music for my video\"\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion, background music for tech product video\" \\\n  --output ./bg_music\n```\n\n### \"I want a song but don't have lyrics\"\n```bash\n# Step 1: Generate lyrics with proper structure\npython scripts/mureka.py lyrics generate \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Copy/refine the output, then generate the song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste lyrics here)\\n[Chorus]\\n(paste chorus here)\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, soft drums, male vocal\" \\\n  --output ./summer_song\n```\n\n---\n\n## Advanced Features\n\n### Reference-Based Generation\nUpload a reference track (must be exactly 30s, mp3/m4a) to guide the style:\n```bash\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# → File ID: 542321\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --reference-id 542321 --output ./song\n```\n\n### Vocal Cloning\nUpload a vocal sample (15-30s, mp3/m4a) to use a specific voice:\n```bash\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# → File ID: 789012\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --vocal-id 789012 --prompt \"R&B, smooth, 90 BPM\" --output ./song\n```\n\n---\n\n## Control Options & Rules\n\n### Song Generation Control Combos\n\nWhen generating songs, these control options work together:\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- **melody_id does NOT support any combination** — use it alone\n- **prompt and reference_id are mutually exclusive** — use one or the other\n\n### Instrumental Generation Rules\n\nFor instrumentals, `prompt` and `instrumental_id` are mutually exclusive — use one or the other.\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| `reference` | mp3/m4a | exactly 30s | Excess trimmed |\n| `vocal` | mp3/m4a | 15-30s | Excess trimmed |\n| `melody` | mp3/m4a/mid | 5-60s | MIDI recommended |\n| `instrumental` | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\n\nAlways use `mureka-8` — it is the latest and highest quality model.\n\n---\n\n## Error Handling\n\nScripts raise `RuntimeError` or `requests.HTTPError` on failure. Handle common errors:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `401 Unauthorized` | Invalid or expired API key | Ask user to verify `MUREKA_API_KEY` |\n| `429 Too Many Requests` | Rate limit exceeded | Wait 30-60 seconds, then retry |\n| `402 / Insufficient balance` | Account balance depleted | Direct user to https://platform.mureka.ai to top up |\n| `Task ended with status: failed` | Generation failed (bad prompt, server error) | Check prompt against Quality Checklist, retry |\n| `Task ended with status: timeouted` | Generation took too long | Retry; if persistent, simplify the prompt or try a different model |\n| `ConnectionError` / `Timeout` | Network issue | Retry after a few seconds |\n\n**General strategy**: Read the error message carefully. If it's a client error (4xx), fix the input. If it's a server error (5xx) or timeout, retry once before escalating to the user.\n\n---\n\n## Troubleshooting Common Issues\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | • Check prompt meets quality checklist<br>• Verify lyrics have structure tags<br>• Retry the generation |\n| Vocals sound rushed | • Shorten lyric lines (≤10 words)<br>• Reduce syllables per line |\n| Listed instruments not audible | • Verify each instrument named explicitly in prompt<br>• Add more specific descriptors (e.g., \"acoustic guitar strumming\") |\n| Prompt doesn't match output | • Increase specificity (exact genre, BPM, instruments)<br>• Add mood progression (\"sparse → full\")<br>• Generate n=3 choices |\n| melody_id error | • melody_id MUST be used alone<br>• Remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | • File IDs only valid for account that uploaded<br>• Re-upload file if from another session |\n\n**For parameter help:**\n```bash\npython scripts/mureka.py --help\npython scripts/mureka.py song --help\n```\n\n---\n\n## Environment\n\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **Base URL**: `https://api.mureka.ai`\n- **Dependencies**: Python 3, `requests` library\n- **Billing**: Check balance with `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\nFile v1.0.3:README.md\n\n# Skywork Music Maker 1.0.0\n\nAI-powered music generation skill for Claude Code and other AI agent frameworks. Create professional songs, instrumentals, and lyrics using Mureka AI API with natural language descriptions in any language.\n\n## Quick Links\n\n- **[SKILL.md](SKILL.md)** - Complete agent guide (start here)\n- **[references/prompt_guide.md](references/prompt_guide.md)** - Music craftsmanship guide (MANDATORY reading for lyrics tasks)\n- **[scripts/mureka.py](scripts/mureka.py)** - Unified CLI tool for all operations\n\n## Installation\n\n### For Claude Code / Codex\n```bash\n# Option 1: Use directly from this repo\n# Reference as: @skywork-music-maker-1.0.0\n\n# Option 2: Install to ~/.claude/skills\ncp -r skywork-music-maker-1.0.0 ~/.claude/skills/\n```\n\n### For Gemini CLI\n```bash\n# Install to skills directory (check your platform's docs)\ncp -r skywork-music-maker-1.0.0 /path/to/gemini/skills/\n```\n\n### For Other AI Frameworks\nCopy the directory to your framework's skills location. The skill follows standard conventions and should work with any framework supporting tool-based agents.\n\n## Key Features\n\n✅ **Natural language to music** - Describe in any language, get structured prompts\n✅ **Smart validation** - Quality checks before generation\n✅ **Complete workflow** - Lyrics → Song/Instrumental → Analysis → Extension\n✅ **Unified CLI** - Single `mureka.py` script for all operations\n✅ **Agent-optimized** - Self-documenting code, clear documentation structure\n✅ **Production-ready** - Best practices from real music production practitioners\n\n## Quick Start\n\n### 1. Set up API key\n\n```bash\n# Get your API key from https://platform.mureka.ai\nexport MUREKA_API_KEY=\"your_api_key\"\n```\n\n### 2. Generate music with natural language\n\n```bash\n# The AI agent will convert your description to a structured prompt\nUser: \"create an upbeat summer pop song with female vocals\"\nAI: [Converts to structured prompt, validates, generates]\n\n# Or use the CLI directly\ncd scripts/\npython mureka.py song \\\n  --lyrics \"[Verse]\\nWalking down the beach...\" \\\n  --prompt \"indie pop, 110 BPM, acoustic guitar, female vocal, warm and nostalgic\" \\\n  --output ./my_song\n```\n\n### 3. Check the results\n\n```bash\n# Generated files will be in the output directory:\nls ./my_song/\n# output_0.mp3  output_1.mp3  lyrics.txt\n```\n\n## CLI Tool\n\nAll operations use a single unified script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics using AI\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\n**Usage:**\n```bash\npython scripts/mureka.py --help              # Show all commands\npython scripts/mureka.py song --help         # Song-specific options\npython scripts/mureka.py instrumental --help # Instrumental options\npython scripts/mureka.py lyrics --help       # Lyrics generation options\npython scripts/mureka.py upload --help       # Upload options\n```\n\n**Important:** Use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n## Common Scenarios\n\n### Background music for videos\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion\" \\\n  --output ./bg_music\n```\n\n### Song without lyrics yet\n```bash\n# Step 1: Generate lyrics\npython scripts/mureka.py lyrics generate \\\n  \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Use the generated lyrics for your song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste generated lyrics here)\\n[Chorus]\\n...\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, male vocal\" \\\n  --output ./summer_song\n```\n\n### With reference track (style transfer)\n```bash\n# Upload 30-second reference track\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# Returns: File ID: 542321\n\n# Generate song using that style\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --reference-id 542321 \\\n  --output ./song_with_style\n```\n\n### Vocal cloning\n```bash\n# Upload 15-30 second vocal sample\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# Returns: File ID: 789012\n\n# Generate song with cloned voice\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --vocal-id 789012 \\\n  --prompt \"R&B, smooth, 90 BPM, emotional\" \\\n  --output ./cloned_voice_song\n```\n\n## File Structure\n\n```\nskywork-music-maker-1.0.0/\n├── SKILL.md                    # Complete agent guide\n├── README.md                   # This file\n├── references/\n│   └── prompt_guide.md        # Music craftsmanship guide (MANDATORY for lyrics)\n└── scripts/\n    └── mureka.py              # Unified CLI tool (use --help for docs)\n```\n\n## Smart Prompt Conversion\n\nWhen you describe music in natural language (in any language), the AI agent automatically:\n\n1. **Extracts structured parameters** - Genres, moods, instruments, BPM, vocals, key\n2. **Validates quality** - Checks against quality checklist to prevent generation failures\n3. **Presents for confirmation** - Shows you the structured prompt before generation\n4. **Executes generation** - Runs the API call with the validated prompt\n\nThis prevents 80% of common generation failures and ensures high-quality results.\n\n## Control Options & Requirements\n\n### Song Generation Combinations\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- `melody_id` does NOT support any combination — use it alone\n- `prompt` and `reference_id` are mutually exclusive\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| `reference` | mp3/m4a | exactly 30s | Excess trimmed |\n| `vocal` | mp3/m4a | 15-30s | Excess trimmed |\n| `melody` | mp3/m4a/mid | 5-60s | MIDI recommended |\n| `instrumental` | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\n\nAlways use `mureka-8` — it is the latest and highest quality model (default in scripts).\n\n## Error Handling\n\nCommon errors and solutions:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `401 Unauthorized` | Invalid/expired API key | Verify `MUREKA_API_KEY` |\n| `429 Too Many Requests` | Rate limit exceeded | Wait 30-60 seconds, retry |\n| `402 / Insufficient balance` | Account depleted | Top up at https://platform.mureka.ai |\n| `Task failed` | Bad prompt/server error | Check Quality Checklist, retry |\n| `Task timeouted` | Generation took too long | Simplify prompt, retry |\n| `ConnectionError` | Network issue | Retry after a few seconds |\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | • Check prompt meets quality checklist<br>• Verify lyrics have structure tags<br>• Retry |\n| Vocals sound rushed | • Shorten lyric lines (≤10 words)<br>• Reduce syllables per line |\n| Instruments not audible | • Name each instrument explicitly<br>• Add specific descriptors (e.g., \"acoustic guitar strumming\") |\n| Output doesn't match prompt | • Increase specificity (exact genre, BPM)<br>• Add mood progression (\"sparse → full\")<br>• Generate n=3 choices |\n| melody_id error | • melody_id MUST be used alone<br>• Remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | • File IDs only valid for uploading account<br>• Re-upload if from another session |\n\n## Environment Requirements\n\n- **Python**: 3.7+\n- **Dependencies**: `requests` library (`pip install requests`)\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **API Base URL**: `https://api.mureka.ai`\n\n## Support & Resources\n\n- **Issues & Feedback**: [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)\n- **Mureka API Docs**: [platform.mureka.ai](https://platform.mureka.ai)\n- **Get API Key**: [platform.mureka.ai](https://platform.mureka.ai) → Register → API Keys → Generate\n- **Check Balance**: `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\n## Examples\n\n### Traditional Chinese Music\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n春风拂面...\" \\\n  --prompt \"Chinese traditional guofeng, 90 BPM, bamboo flute (dizi), guzheng, erhu, misty atmosphere, ancient poetry aesthetic\" \\\n  --output ./chinese_style\n```\n\n### Electronic Dance Music\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"progressive house, 128 BPM, synth leads, deep bass, atmospheric pads, building energy\" \\\n  -n 3 \\\n  --output ./edm_track\n```\n\n### Jazz Ballad\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\nUnder the midnight sky...\" \\\n  --prompt \"jazz ballad, slow groove, piano, upright bass, soft brushed drums, female husky vocal, intimate\" \\\n  --output ./jazz_ballad\n```\n\n## License\n\nSame as parent repository.\n\n---\n\n**For detailed music production guidance, prompt crafting examples, and lyric writing best practices, see [references/prompt_guide.md](references/prompt_guide.md).**\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn70ct0m3p4538a9t49cjcwern82ky02\",\n  \"slug\": \"skywork-music-maker\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1775736529775\n}\n\nFile v1.0.3:references/prompt_guide.md\n\n# Music Prompt Crafting Guide\n\nComprehensive guide to writing effective music prompts for Mureka AI.\n\n## The Golden Rule: DESCRIBE, Don't Command\n\n```\n❌ \"Create an energetic pop song with drums\"\n✅ \"energetic pop, driving four-on-the-floor drums, bright synth hooks, 128 BPM, female vocal, festival anthem vibe\"\n```\n\nThe AI responds to descriptions of the music, not instructions to \"make\" or \"create\" it.\n\n---\n\n## Design a Dynamic Arc, Not a Static Description\n\nThe most common reason AI-generated songs sound flat is that the prompt describes one mood level throughout. Great songs are tension/release journeys — design yours explicitly.\n\nExpress the arc as a **mood progression string** in your prompt:\n```\n✅ \"sparse and intimate opening → rising tension → full cathartic chorus → stripped-back bridge → bigger final chorus\"\n✅ \"melancholic and sparse → building urgency → explosive release → quiet resolution\"\n```\n\nThe AI interprets this as an emotional journey across the song. Without it, every section gets the same energy and density.\n\n---\n\n## Effective Prompt Structure\n\n### Minimum Viable Prompt (always include these)\n```\n[genre + sub-genre], [mood/emotion], [tempo/BPM], [key instruments], [vocal style]\n```\n\n### Standard Prompt (recommended for good results)\n```\nGenre: [specific genre + era, e.g., \"90s trip-hop\"]\nMood: [2-3 descriptors, e.g., \"melancholic, introspective, nocturnal\"]\nTempo: [BPM or description, e.g., \"85 BPM, slow groove\"]\nInstruments: [3-5 key instruments, e.g., \"turntable scratches, Rhodes piano, upright bass\"]\nVocals: [style, e.g., \"breathy female vocals, intimate delivery\"]\nScene: [usage context, e.g., \"late-night city driving\"]\n```\n\n### Production Brief (for maximum control)\n```\nGenre: trip-hop | Era: mid-90s Bristol\nBPM: 85 | Key: D minor\nMood: melancholic → building tension → cathartic release\nLead: Rhodes piano, tremolo\nRhythm: breakbeat, vinyl crackle texture\nBass: deep sub-bass, Moog-style\nTexture: tape saturation, lo-fi warmth\nVocals: breathy female, close-mic intimacy\nStructure: Intro(8bars) / Verse / Chorus / Verse / Bridge / Chorus / Outro\nAvoid: auto-tune, bright synths, four-on-the-floor kick\nReference: Portishead \"Roads\" (breakbeat texture, Rhodes tone)\n```\n\n**Note on references**: Only use specific songs as sonic benchmarks when all other parameters are already specified. Different from \"sound like [artist]\" — use for named production qualities (e.g., \"Roads-style breakbeat texture\").\n\n---\n\n## What Makes Prompts FAIL (Top 7 Mistakes)\n\n| # | Mistake | Why It Fails | Fix |\n|---|---------|-------------|-----|\n| 1 | **Vague prompts** (\"nice pop song\") | AI defaults to the statistical average — generic, forgettable | Be ruthlessly specific: sub-genre + era + mood + instruments + BPM |\n| 2 | **Contradictions** (\"slow and relaxing, high energy, 160 BPM\") | Conflicting signals make the AI unpredictable | Check every descriptor agrees with the mood. Pick one direction |\n| 3 | **\"Sound like [famous artist]\"** | Copyright risk + AI interprets literally, often misses the point | Describe the *qualities* you like: \"warm analog synths, driving bass, 80s production style\" |\n| 4 | **Too many words per lyric line** | AI rushes through words → slurred, unnatural vocals | Keep lines ≤10 words. Short lines = better vocal delivery |\n| 5 | **No structure tags in lyrics** | Song has no shape — verse/chorus blur together | Always use [Verse], [Chorus], [Bridge], [Outro] tags |\n| 6 | **Rewriting entire prompt between iterations** | Can never isolate what improved (or worsened) the output | Change ONE element at a time. A/B test systematically |\n| 7 | **Ignoring negative prompts** | Unwanted elements creep in (auto-tune, trap hi-hats, reverb) | Explicitly state what to avoid: \"no auto-tune, avoid heavy reverb\" |\n\n---\n\n## Effective vs Ineffective — Side-by-Side Examples\n\n### Example 1: Pop Song\n```\n❌ \"A pop song about love that sounds good\"\n✅ \"bright synth-pop, uplifting, 120 BPM, arpeggiated synths, punchy electronic drums, female vocal with light reverb, 2020s clean production, summer anthem feel\"\n```\n\n### Example 2: Lo-Fi Background\n```\n❌ \"lofi music for studying\"\n✅ \"lo-fi hip-hop, warm and mellow, 75 BPM, dusty vinyl crackle, jazzy Rhodes chords, muted boom-bap drums, no vocals, late-night study session atmosphere\"\n```\n\n### Example 3: Cinematic\n```\n❌ \"epic movie music\"\n✅ \"cinematic orchestral, tension building to triumphant climax, 95 BPM, strings staccato → legato swell, French horns, timpani rolls, choir in final section, Hans Zimmer-style layered percussion\"\n```\n\n### Example 4: Rock Song\n```\n❌ \"energetic rock song, male vocals, guitar solo\"\n✅ \"alternative rock, energetic and raw, 140 BPM, distorted electric guitar riffs, driving bass line, punchy drums, raspy male vocals, anthemic chorus, guitar solo section, garage rock aesthetic, festival anthem energy\"\n```\n\n### Example 5: Traditional Chinese\n```\n❌ \"Chinese music, sad\"\n✅ \"Chinese traditional guofeng, melancholic and nostalgic, 60 BPM, dizi bamboo flute lead melody, guzheng plucked strings, subtle erhu, misty atmosphere, Jiangnan water town imagery, rain and mist soundscape, instrumental only\"\n```\n\n---\n\n## Lyrics Writing: What Separates Good from Bad\n\n### Structure Tags (always use these)\n\n```\n[Intro]\n[Verse]\n[Pre-Chorus]\n[Chorus]\n[Bridge]\n[Break]\n[Outro]\n```\n\n**Standard structure order**: Verse → Chorus → Verse → Chorus → Bridge → Final Chorus → Outro. The Bridge always appears after the second chorus — never before the first.\n\nIf your generated bridge sounds like a second verse, regenerate it with:\n```bash\npython generate_lyrics.py extend \"<existing lyrics>\" \"write a contrasting bridge that shifts perspective, strips back to a single instrument, and sets up the final chorus\"\n```\n\n### Golden Rules for Lyrics That Sing Well\n\n1. **Keep lines short** — 6-10 words per line. Long lines get rushed.\n   ```\n   ❌ \"I've been walking through the streets of this old town thinking about everything we used to do together\"\n   ✅ \"Walking through the old town streets\\n   Thinking of what we used to be\"\n   ```\n\n2. **Match syllable count across verse lines** — Creates natural rhythm.\n   ```\n   ✅ \"Shadows fall on empty streets\"    (7 syllables)\n      \"Whispers lost in evening heat\"    (7 syllables)\n      \"Dancing lights through window panes\" (7 syllables)\n   ```\n\n3. **Use rhyme patterns intentionally** — ABAB or AABB, not random.\n   ```\n   ✅ [Verse]\n      The city sleeps beneath the stars (A)\n      While dreamers chase the fading light (B)\n      We trace our names on passing cars (A)\n      And disappear into the night (B)\n   ```\n\n4. **Chorus should be simpler and more repetitive than verses** — Fewer words, not more. Whitespace and repetition create impact; repetition IS the melody.\n\n5. **Don't over-explain in lyrics** — Imagery > exposition.\n\n---\n\n## Writing a Memorable Hook\n\nThe hook is the most important line in your song. Get it right:\n\n### 1. Length and singability\n4-8 words, singable on first listen, usually contains the song's title.\n\n```\n✅ \"I will always love you\" — simple, universal, title, singable\n✅ \"Rolling in the deep\" — 4 words, vivid, singable\n❌ \"I feel the way I feel when I think about our story\" — too long, too vague\n```\n\n### 2. End chorus lines on open vowels\nAI vocals hold the last syllable of each line. Open vowels (oh, ah, ay, ee) sustain beautifully. Closed consonants (mm, th, ff, ss) sound awkward when held.\n\n```\n✅ \"Let me go\" → ends on \"oh\" — sustains well\n❌ \"Let me breathe\" → ends on closed \"th\" sound — awkward to hold\n```\n\n### 3. Chorus density\nA chorus should have FEWER words than a verse, not more. The space around the hook gives it impact.\n\n```\n❌ \"I feel sad because you left me and now I'm alone\"\n✅ \"Empty chair across the table\\n   Coffee cold, the morning grey\"\n```\n\n---\n\n## Auto-Generate Lyrics First, Then Refine\n\n```bash\n# Generate lyrics from a concept\npython generate_lyrics.py generate \"a bittersweet farewell song, two old friends parting ways after summer\"\n\n# Extend if you need more sections\npython generate_lyrics.py extend \"[Verse]\\nThe last light paints the pier in gold...\"\n```\n\n---\n\n## Iteration Strategy (How Pros Refine)\n\n1. **First generation**: Use your best-guess prompt + n=3\n2. **Listen to all choices**: Note what's good and what's off\n3. **Adjust ONE element**: If rhythm is wrong → change BPM/drums description. If mood is off → change mood descriptors\n4. **Re-generate**: Same lyrics, tweaked prompt\n5. **Compare**: Does the change improve or worsen?\n6. **Repeat** until satisfied\n\n### What to Listen For\n\n**For vocal songs:**\n| Symptom | Fix |\n|---------|-----|\n| Vocals feel rushed / words swallowed | Shorten lyric lines, reduce syllables per line |\n| No energy build between verse and chorus | Add mood progression arc to prompt (e.g., \"sparse → full cathartic release\") |\n| Hook doesn't stick | Simplify chorus to 4-8 words, repeat title phrase, check lines end on open vowels |\n| Tempo feels wrong | Adjust BPM ±10 and regenerate |\n| Listed instruments not audible | Verify each instrument is named explicitly in the prompt |\n\n**For instrumentals / ambient:**\n| Symptom | Fix |\n|---------|-----|\n| Tempo feels wrong | Adjust BPM ±10 |\n| Mood doesn't match intent | Audit all mood descriptors for internal consistency |\n| Instruments missing | Verify each is named explicitly in the prompt |\n\n**Never rewrite the entire prompt at once.** You'll lose track of what works.\n\n---\n\n## Production Checklist (Before You Generate)\n\nBefore hitting generate, verify:\n\n- [ ] **Genre is specific**: Not just \"pop\" but \"synth-pop, 2020s, clean production\"\n- [ ] **Mood is consistent**: No contradictions (slow + energetic = confused AI)\n- [ ] **BPM is set**: Even approximate (\"~90 BPM, slow groove\") helps\n- [ ] **3-5 instruments listed**: Gives the AI sonic anchors\n- [ ] **Vocal style specified**: Or \"no vocals\" / \"instrumental only\"\n- [ ] **Lyrics have structure tags**: [Verse], [Chorus], [Bridge], [Outro]\n- [ ] **Lines are short**: ≤10 words per line\n- [ ] **Avoid list included**: What you DON'T want (auto-tune, trap hi-hats, etc.)\n- [ ] **N > 1**: Generate 2-3 choices and pick the best. Never rely on a single generation\n\nArchive v1.0.2: 5 files, 19831 bytes\n\nFiles: README.md (9245b), references/prompt_guide.md (10296b), scripts/mureka.py (10880b), SKILL.md (16190b), _meta.json (138b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: skywork-music-maker\ndescription: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop songs, orchestral scores, K-POP, reggaetón, guofeng, and more. Supports vocal cloning, reference track style transfer, lyric writing, and full music production workflows. Just say \"make me a chill lo-fi beat\" or describe any musical idea and this skill handles the rest.\nmetadata:\n  openclaw:\n    requires:\n      env:\n        - MUREKA_API_KEY\n      bins:\n        - python3\n    install:\n      - kind: uv\n        package: requests\n    primaryEnv: MUREKA_API_KEY\n    homepage: https://clawhub.ai/gxcun17/skywork-music-maker\n---\n\n# Skywork Music Maker (Mureka API)\n\nGenerate professional-quality music using the Mureka API at https://api.mureka.ai. This skill covers the complete music production workflow: lyrics writing → song/instrumental generation.\n\n## 多语言简介 | Multilingual Overview\n\n### 中文简介\nSkywork Music Maker 是基于 Mureka AI API 的专业音乐创作工具。支持从自然语言描述生成歌曲、纯音乐和歌词，覆盖完整的音乐制作流程。支持中文输入，可根据中文描述自动生成英文提示词。适用于流行音乐、国风音乐、电子音乐等多种风格。主要功能包括：AI 作词、歌曲生成（含人声）、纯音乐生成、人声克隆、参考音频风格迁移。\n\n### 日本語の概要\nSkywork Music Maker は Mureka AI API を使用したプロフェッショナルな音楽制作ツールです。自然言語の説明から楽曲・インストゥルメンタル・歌詞を生成でき、完全な音楽制作ワークフローをカバーします。日本語入力に対応し、日本語の説明から自動的に英語プロンプトを生成します。ポップス、ロック、J-POP、アニソン風、エレクトロニカなど、多様なジャンルに対応。主な機能：AI 作詞、ボーカル付き楽曲生成、インストゥルメンタル生成、ボーカルクローン、リファレンストラックによるスタイル転写。\n\n### 한국어 개요\nSkywork Music Maker는 Mureka AI API를 기반으로 한 전문 음악 제작 도구입니다. 자연어 설명으로 노래, 인스트루멘탈, 가사를 생성하며 완전한 음악 제작 워크플로우를 지원합니다. 한국어 입력을 지원하며, 한국어 설명에서 자동으로 영어 프롬프트를 생성합니다. K-POP, 발라드, 힙합, 인디, 트로트 등 다양한 장르에 대응합니다. 주요 기능: AI 작사, 보컬 포함 곡 생성, 인스트루멘탈 생성, 보컬 클론, 레퍼런스 트랙 기반 스타일 전사.\n\n### Descripción en español\nSkywork Music Maker es una herramienta profesional de creación musical basada en la API de Mureka AI. Permite generar canciones, instrumentales y letras a partir de descripciones en lenguaje natural, cubriendo el flujo completo de producción musical. Compatible con entrada en español: describe tu idea musical en español y el sistema generará automáticamente prompts optimizados en inglés. Soporta una amplia variedad de géneros: reggaetón, salsa, bachata, cumbia, pop latino, flamenco, bossa nova, rock en español y más. Funciones principales: composición de letras con IA, generación de canciones con vocales, producción de instrumentales, clonación de voz y transferencia de estilo mediante pistas de referencia.\n\n---\n\n## Privacy & Data Usage\n\n- **API endpoint**: All API calls are made exclusively to `https://api.mureka.ai` (official Mureka endpoint by Skywork AI)\n- **Data transmitted**: Lyrics text, music prompts, and uploaded audio files (reference tracks, vocal samples, melodies) are sent to Mureka servers for music generation\n- **No third-party sharing**: No data is sent to any service beyond the official Mureka API\n- **Local output**: Generated audio files and lyrics are saved locally to the user-specified output directory\n- **No local caching of credentials**: The API key is read from the `MUREKA_API_KEY` environment variable at runtime; this skill does not store or cache credentials\n- **User-managed billing**: Users must register their own Mureka account at https://platform.mureka.ai; all usage billing is handled directly by Mureka\n- **Upload consent**: File uploads (reference audio, vocal samples, melodies) are initiated only when the user explicitly requests reference-based or vocal-cloning generation\n\n---\n\n## First-Time Setup\n\nBefore running any API command, check if `MUREKA_API_KEY` is set. If not, guide the user to get an API key at https://platform.mureka.ai/ (register → API Keys → generate key → `export MUREKA_API_KEY=\"...\"`), then **STOP** — do not attempt any API calls until the key is configured.\n\n## Smart Prompt Conversion (CRITICAL WORKFLOW)\n\n**Default behavior**: When the user doesn't specify song type, always generate a song with lyrics (use `mureka.py song`). Only use `mureka.py instrumental` when the user explicitly asks for instrumental, BGM, background music, or \"no vocals\".\n\n**Output defaults**: Use mp3 format unless the user requests otherwise. The `--output` flag specifies a directory — the script creates it and saves all results inside (audio files + lyrics.txt for songs). If the user doesn't specify a location, choose a user-friendly path with a descriptive folder name based on the song theme (e.g., `summer_pop_song/`).\n\nWhen users provide music descriptions in natural language (in any language), you **MUST** convert them to structured Mureka API prompts using this workflow:\n\n### Conversion Process\n\n**User Input Examples:**\n- \"upbeat pop song, female vocals, guitar, perfect for summer\"\n- \"sad piano ballad about lost love\"\n- \"epic orchestral music for a fantasy game\"\n- \"traditional Chinese music with bamboo flute and zither, misty atmosphere\"\n- \"明るいJ-POP風の夏の曲を作って\" (Japanese: bright J-POP style summer song)\n- \"슬픈 발라드 만들어줘, 피아노 위주로\" (Korean: make a sad ballad, piano-focused)\n- \"做一首国风古典音乐，要有二胡和古筝\" (Chinese: make a guofeng classical piece with erhu and guzheng)\n- \"Hazme una canción de reggaetón romántico con guitarra acústica\" (Spanish: make a romantic reggaeton song with acoustic guitar)\n\n**Your Task:**\n1. Extract structured parameters using the extraction rules below\n2. Validate the prompt meets quality standards (see Quality Checklist)\n3. Present to user for confirmation before generating\n4. Run the generation command with the structured prompt\n\n### Parameter Extraction Rules\n\nWhen users provide natural language music descriptions, directly extract and structure the following parameters:\n\n**Required Parameters:**\n- **genres**: music genres including fusion styles (e.g., Pop, Rock, Jazz, Pop Rap Fusion, Alternative Rock, Guofeng, J-POP, K-POP, Trot, Reggaetón, Salsa, Bachata, Cumbia, Flamenco, Bossa Nova)\n- **moods**: emotional tones (e.g., Happy, Melancholic, Energetic, Nostalgic, Bright)\n- **instruments**: specific instruments (e.g., Piano, Guitar, Drums, Erhu, Guzheng, Synth Pads, Dizi, Shamisen, Gayageum, Cajón, Congas, Bongos, Tres, Charango)\n- **rhythms**: rhythm characteristics (e.g., 4/4, Slow, Syncopated, Driving, Flowing)\n- **vocals**: vocal attributes (e.g., Female, Husky, Whispered, Male, Soft, Clear) or \"instrumental only\"\n- **key**: musical key if specified (e.g., C Major, A Minor, C# Major)\n- **bpm**: beats per minute (e.g., 120) or tempo descriptor (e.g., \"slow groove\", \"uptempo\")\n- **description**: concise summary (under 50 words) capturing mood progression, melody, harmony, timbre, texture, dynamics\n\n**Extraction Instructions:**\n- **Translate non-English terms**: Convert ALL non-English musical terms to English while preserving cultural and musical meaning\n- **Preserve specificity**: Keep detailed information including specific styles, subgenres, and cultural context (e.g., \"Chinese traditional guofeng\" not just \"Chinese music\")\n- **Design dynamic arc**: Include mood progression where appropriate (e.g., \"sparse opening → building tension → cathartic chorus\")\n- **Infer intelligently**: Make reasonable assumptions based on genre conventions when parameters are not explicitly stated\n- **English output**: Final prompt string MUST be entirely in English\n\n**Generate Structured Prompt:** Combine all extracted parameters into a comprehensive, natural-flowing description that captures the essence of the user's vision.\n\n### Quality Checklist (Validate BEFORE Generation)\n\nBefore running the generation command, verify the prompt meets these criteria:\n\n**MUST HAVE:**\n- ☑ Specific genre (NOT \"pop song\" but \"synth-pop, 2020s\")\n- ☑ BPM or tempo descriptor (e.g., \"120 BPM\" or \"slow groove\")\n- ☑ 3-5 instruments explicitly named\n- ☑ Mood/emotion descriptors (2-3 words)\n- ☑ Vocal style (or \"instrumental only\")\n- ☑ Structure tags in lyrics: [Verse], [Chorus], [Bridge], [Outro]\n\n**WATCH OUT FOR:**\n- Vague terms: \"nice\", \"good\", \"beautiful\" → replace with specific descriptors\n- Contradictions: \"slow\" + \"energetic\", \"sad\" + \"uplifting\" → pick one direction\n- Too short: <50 chars → add more detail\n- Long lyric lines: >10 words per line → split into shorter lines\n- No dynamic arc: add mood progression (e.g., \"sparse → building → full\")\n\n**AVOID:**\n- Command verbs: \"create a song\" → use descriptions \"upbeat pop song\"\n- Famous artist names: \"sounds like Taylor Swift\" → describe qualities instead\n- Unrealistic combos: melody_id cannot combine with other control options\n\nAfter validation, present the generated prompt to the user for confirmation before proceeding.\n\n---\n\n## Core Workflow: Production Pipeline\n\n1. **Conceptualize** → User describes in natural language → YOU convert to structured prompt\n2. **Validate** → Check prompt quality against Quality Checklist (see above)\n3. **Write Lyrics** → Use lyrics/generate or write manually\n4. **Upload References** → Optional: reference track, vocal sample, melody\n5. **Generate** → Submit song/instrumental task (async) with validated prompt\n6. **Evaluate** → Listen to all N choices, pick best\n7. **Iterate** → Refine prompt based on what you heard\n\n**Critical Steps:**\n- Step 1 is mandatory when user provides natural language input (especially non-English)\n- Step 2 validation prevents 80% of common generation failures\n- Step 3: Read `references/prompt_guide.md` for prompt crafting examples, lyrics structure rules (line length, syllable count, rhyme patterns, hook writing), and iteration best practices\n- Do NOT skip conceptualization — jumping straight to generation without a clear concept is the #1 reason for generic results\n\n**Your Role as AI Assistant:**\n1. Convert user's natural language → structured Mureka prompt (using Smart Prompt Conversion)\n2. Validate prompt quality → flag issues → suggest fixes\n3. Write or generate lyrics with proper structure\n4. Present prompt to user for confirmation\n5. Execute generation command with validated prompt\n6. Help iterate and refine based on generation results\n\n---\n\n## CLI Tool\n\nAll operations go through a single script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\nRun `python scripts/mureka.py --help` for full usage. Note: use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n## Common Scenarios\n\n### \"I just want background music for my video\"\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion, background music for tech product video\" \\\n  --output ./bg_music\n```\n\n### \"I want a song but don't have lyrics\"\n```bash\n# Step 1: Generate lyrics with proper structure\npython scripts/mureka.py lyrics generate \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Copy/refine the output, then generate the song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste lyrics here)\\n[Chorus]\\n(paste chorus here)\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, soft drums, male vocal\" \\\n  --output ./summer_song\n```\n\n---\n\n## Advanced Features\n\n### Reference-Based Generation\nUpload a reference track (must be exactly 30s, mp3/m4a) to guide the style:\n```bash\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# → File ID: 542321\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --reference-id 542321 --output ./song\n```\n\n### Vocal Cloning\nUpload a vocal sample (15-30s, mp3/m4a) to use a specific voice:\n```bash\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# → File ID: 789012\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --vocal-id 789012 --prompt \"R&B, smooth, 90 BPM\" --output ./song\n```\n\n---\n\n## Control Options & Rules\n\n### Song Generation Control Combos\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- `melody_id` does NOT support any combination — use it alone\n- `prompt` and `reference_id` are mutually exclusive — use one or the other\n\n### Instrumental Generation Rules\nFor instrumentals, `prompt` and `instrumental_id` are mutually exclusive — use one or the other.\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| reference | mp3/m4a | exactly 30s | Excess trimmed |\n| vocal | mp3/m4a | 15-30s | Excess trimmed |\n| melody | mp3/m4a/mid | 5-60s | MIDI recommended |\n| instrumental | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\nAlways use `mureka-8` — it is the latest and highest quality model.\n\n---\n\n## Error Handling\n\nScripts raise `RuntimeError` or `requests.HTTPError` on failure. Handle common errors:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| 401 Unauthorized | Invalid or expired API key | Ask user to verify `MUREKA_API_KEY` |\n| 429 Too Many Requests | Rate limit exceeded | Wait 30-60 seconds, then retry |\n| 402 / Insufficient balance | Account balance depleted | Direct user to https://platform.mureka.ai to top up |\n| Task ended with status: failed | Generation failed (bad prompt, server error) | Check prompt against Quality Checklist, retry |\n| Task ended with status: timeouted | Generation took too long | Retry; if persistent, simplify the prompt or try a different model |\n| ConnectionError / Timeout | Network issue | Retry after a few seconds |\n\n**General strategy:** Read the error message carefully. If it's a client error (4xx), fix the input. If it's a server error (5xx) or timeout, retry once before escalating to the user.\n\n## Troubleshooting Common Issues\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | Check prompt meets quality checklist; verify lyrics have structure tags; retry the generation |\n| Vocals sound rushed | Shorten lyric lines (≤10 words); reduce syllables per line |\n| Listed instruments not audible | Verify each instrument named explicitly in prompt; add more specific descriptors |\n| Prompt doesn't match output | Increase specificity (exact genre, BPM, instruments); add mood progression; generate n=3 choices |\n| melody_id error | melody_id MUST be used alone — remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | File IDs only valid for account that uploaded — re-upload file if from another session |\n\nFor parameter help:\n```bash\npython scripts/mureka.py --help\npython scripts/mureka.py song --help\n```\n\n---\n\n## Environment\n\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **Base URL**: https://api.mureka.ai\n- **Dependencies**: Python 3, `requests` library\n- **Billing**: Check balance with `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\nFile v1.0.2:README.md\n\n# Skywork Music Maker 1.0.0\n\nAI-powered music generation skill for Claude Code and other AI agent frameworks. Create professional songs, instrumentals, and lyrics using Mureka AI API with natural language descriptions in any language.\n\n## Quick Links\n\n- **[SKILL.md](SKILL.md)** - Complete agent guide (start here)\n- **[references/prompt_guide.md](references/prompt_guide.md)** - Music craftsmanship guide (MANDATORY reading for lyrics tasks)\n- **[scripts/mureka.py](scripts/mureka.py)** - Unified CLI tool for all operations\n\n## Installation\n\n### For Claude Code / Codex\n```bash\n# Option 1: Use directly from this repo\n# Reference as: @skywork-music-maker-1.0.0\n\n# Option 2: Install to ~/.claude/skills\ncp -r skywork-music-maker-1.0.0 ~/.claude/skills/\n```\n\n### For Gemini CLI\n```bash\n# Install to skills directory (check your platform's docs)\ncp -r skywork-music-maker-1.0.0 /path/to/gemini/skills/\n```\n\n### For Other AI Frameworks\nCopy the directory to your framework's skills location. The skill follows standard conventions and should work with any framework supporting tool-based agents.\n\n## Key Features\n\n✅ **Natural language to music** - Describe in any language, get structured prompts\n✅ **Smart validation** - Quality checks before generation\n✅ **Complete workflow** - Lyrics → Song/Instrumental → Analysis → Extension\n✅ **Unified CLI** - Single `mureka.py` script for all operations\n✅ **Agent-optimized** - Self-documenting code, clear documentation structure\n✅ **Production-ready** - Best practices from real music production practitioners\n\n## Quick Start\n\n### 1. Set up API key\n\n```bash\n# Get your API key from https://platform.mureka.ai\nexport MUREKA_API_KEY=\"your_api_key\"\n```\n\n### 2. Generate music with natural language\n\n```bash\n# The AI agent will convert your description to a structured prompt\nUser: \"create an upbeat summer pop song with female vocals\"\nAI: [Converts to structured prompt, validates, generates]\n\n# Or use the CLI directly\ncd scripts/\npython mureka.py song \\\n  --lyrics \"[Verse]\\nWalking down the beach...\" \\\n  --prompt \"indie pop, 110 BPM, acoustic guitar, female vocal, warm and nostalgic\" \\\n  --output ./my_song\n```\n\n### 3. Check the results\n\n```bash\n# Generated files will be in the output directory:\nls ./my_song/\n# output_0.mp3  output_1.mp3  lyrics.txt\n```\n\n## CLI Tool\n\nAll operations use a single unified script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics using AI\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\n**Usage:**\n```bash\npython scripts/mureka.py --help              # Show all commands\npython scripts/mureka.py song --help         # Song-specific options\npython scripts/mureka.py instrumental --help # Instrumental options\npython scripts/mureka.py lyrics --help       # Lyrics generation options\npython scripts/mureka.py upload --help       # Upload options\n```\n\n**Important:** Use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n## Common Scenarios\n\n### Background music for videos\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion\" \\\n  --output ./bg_music\n```\n\n### Song without lyrics yet\n```bash\n# Step 1: Generate lyrics\npython scripts/mureka.py lyrics generate \\\n  \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Use the generated lyrics for your song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste generated lyrics here)\\n[Chorus]\\n...\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, male vocal\" \\\n  --output ./summer_song\n```\n\n### With reference track (style transfer)\n```bash\n# Upload 30-second reference track\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# Returns: File ID: 542321\n\n# Generate song using that style\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --reference-id 542321 \\\n  --output ./song_with_style\n```\n\n### Vocal cloning\n```bash\n# Upload 15-30 second vocal sample\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# Returns: File ID: 789012\n\n# Generate song with cloned voice\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --vocal-id 789012 \\\n  --prompt \"R&B, smooth, 90 BPM, emotional\" \\\n  --output ./cloned_voice_song\n```\n\n## File Structure\n\n```\nskywork-music-maker-1.0.0/\n├── SKILL.md                    # Complete agent guide\n├── README.md                   # This file\n├── references/\n│   └── prompt_guide.md        # Music craftsmanship guide (MANDATORY for lyrics)\n└── scripts/\n    └── mureka.py              # Unified CLI tool (use --help for docs)\n```\n\n## Smart Prompt Conversion\n\nWhen you describe music in natural language (in any language), the AI agent automatically:\n\n1. **Extracts structured parameters** - Genres, moods, instruments, BPM, vocals, key\n2. **Validates quality** - Checks against quality checklist to prevent generation failures\n3. **Presents for confirmation** - Shows you the structured prompt before generation\n4. **Executes generation** - Runs the API call with the validated prompt\n\nThis prevents 80% of common generation failures and ensures high-quality results.\n\n## Control Options & Requirements\n\n### Song Generation Combinations\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- `melody_id` does NOT support any combination — use it alone\n- `prompt` and `reference_id` are mutually exclusive\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| `reference` | mp3/m4a | exactly 30s | Excess trimmed |\n| `vocal` | mp3/m4a | 15-30s | Excess trimmed |\n| `melody` | mp3/m4a/mid | 5-60s | MIDI recommended |\n| `instrumental` | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\n\nAlways use `mureka-8` — it is the latest and highest quality model (default in scripts).\n\n## Error Handling\n\nCommon errors and solutions:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `401 Unauthorized` | Invalid/expired API key | Verify `MUREKA_API_KEY` |\n| `429 Too Many Requests` | Rate limit exceeded | Wait 30-60 seconds, retry |\n| `402 / Insufficient balance` | Account depleted | Top up at https://platform.mureka.ai |\n| `Task failed` | Bad prompt/server error | Check Quality Checklist, retry |\n| `Task timeouted` | Generation took too long | Simplify prompt, retry |\n| `ConnectionError` | Network issue | Retry after a few seconds |\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | • Check prompt meets quality checklist<br>• Verify lyrics have structure tags<br>• Retry |\n| Vocals sound rushed | • Shorten lyric lines (≤10 words)<br>• Reduce syllables per line |\n| Instruments not audible | • Name each instrument explicitly<br>• Add specific descriptors (e.g., \"acoustic guitar strumming\") |\n| Output doesn't match prompt | • Increase specificity (exact genre, BPM)<br>• Add mood progression (\"sparse → full\")<br>• Generate n=3 choices |\n| melody_id error | • melody_id MUST be used alone<br>• Remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | • File IDs only valid for uploading account<br>• Re-upload if from another session |\n\n## Environment Requirements\n\n- **Python**: 3.7+\n- **Dependencies**: `requests` library (`pip install requests`)\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **API Base URL**: `https://api.mureka.ai`\n\n## Support & Resources\n\n- **Issues & Feedback**: [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)\n- **Mureka API Docs**: [platform.mureka.ai](https://platform.mureka.ai)\n- **Get API Key**: [platform.mureka.ai](https://platform.mureka.ai) → Register → API Keys → Generate\n- **Check Balance**: `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\n## Examples\n\n### Traditional Chinese Music\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n春风拂面...\" \\\n  --prompt \"Chinese traditional guofeng, 90 BPM, bamboo flute (dizi), guzheng, erhu, misty atmosphere, ancient poetry aesthetic\" \\\n  --output ./chinese_style\n```\n\n### Electronic Dance Music\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"progressive house, 128 BPM, synth leads, deep bass, atmospheric pads, building energy\" \\\n  -n 3 \\\n  --output ./edm_track\n```\n\n### Jazz Ballad\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\nUnder the midnight sky...\" \\\n  --prompt \"jazz ballad, slow groove, piano, upright bass, soft brushed drums, female husky vocal, intimate\" \\\n  --output ./jazz_ballad\n```\n\n## License\n\nSame as parent repository.\n\n---\n\n**For detailed music production guidance, prompt crafting examples, and lyric writing best practices, see [references/prompt_guide.md](references/prompt_guide.md).**\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn70ct0m3p4538a9t49cjcwern82ky02\",\n  \"slug\": \"skywork-music-maker\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1773829975087\n}\n\nFile v1.0.2:references/prompt_guide.md\n\n# Music Prompt Crafting Guide\n\nComprehensive guide to writing effective music prompts for Mureka AI.\n\n## The Golden Rule: DESCRIBE, Don't Command\n\n```\n❌ \"Create an energetic pop song with drums\"\n✅ \"energetic pop, driving four-on-the-floor drums, bright synth hooks, 128 BPM, female vocal, festival anthem vibe\"\n```\n\nThe AI responds to descriptions of the music, not instructions to \"make\" or \"create\" it.\n\n---\n\n## Design a Dynamic Arc, Not a Static Description\n\nThe most common reason AI-generated songs sound flat is that the prompt describes one mood level throughout. Great songs are tension/release journeys — design yours explicitly.\n\nExpress the arc as a **mood progression string** in your prompt:\n```\n✅ \"sparse and intimate opening → rising tension → full cathartic chorus → stripped-back bridge → bigger final chorus\"\n✅ \"melancholic and sparse → building urgency → explosive release → quiet resolution\"\n```\n\nThe AI interprets this as an emotional journey across the song. Without it, every section gets the same energy and density.\n\n---\n\n## Effective Prompt Structure\n\n### Minimum Viable Prompt (always include these)\n```\n[genre + sub-genre], [mood/emotion], [tempo/BPM], [key instruments], [vocal style]\n```\n\n### Standard Prompt (recommended for good results)\n```\nGenre: [specific genre + era, e.g., \"90s trip-hop\"]\nMood: [2-3 descriptors, e.g., \"melancholic, introspective, nocturnal\"]\nTempo: [BPM or description, e.g., \"85 BPM, slow groove\"]\nInstruments: [3-5 key instruments, e.g., \"turntable scratches, Rhodes piano, upright bass\"]\nVocals: [style, e.g., \"breathy female vocals, intimate delivery\"]\nScene: [usage context, e.g., \"late-night city driving\"]\n```\n\n### Production Brief (for maximum control)\n```\nGenre: trip-hop | Era: mid-90s Bristol\nBPM: 85 | Key: D minor\nMood: melancholic → building tension → cathartic release\nLead: Rhodes piano, tremolo\nRhythm: breakbeat, vinyl crackle texture\nBass: deep sub-bass, Moog-style\nTexture: tape saturation, lo-fi warmth\nVocals: breathy female, close-mic intimacy\nStructure: Intro(8bars) / Verse / Chorus / Verse / Bridge / Chorus / Outro\nAvoid: auto-tune, bright synths, four-on-the-floor kick\nReference: Portishead \"Roads\" (breakbeat texture, Rhodes tone)\n```\n\n**Note on references**: Only use specific songs as sonic benchmarks when all other parameters are already specified. Different from \"sound like [artist]\" — use for named production qualities (e.g., \"Roads-style breakbeat texture\").\n\n---\n\n## What Makes Prompts FAIL (Top 7 Mistakes)\n\n| # | Mistake | Why It Fails | Fix |\n|---|---------|-------------|-----|\n| 1 | **Vague prompts** (\"nice pop song\") | AI defaults to the statistical average — generic, forgettable | Be ruthlessly specific: sub-genre + era + mood + instruments + BPM |\n| 2 | **Contradictions** (\"slow and relaxing, high energy, 160 BPM\") | Conflicting signals make the AI unpredictable | Check every descriptor agrees with the mood. Pick one direction |\n| 3 | **\"Sound like [famous artist]\"** | Copyright risk + AI interprets literally, often misses the point | Describe the *qualities* you like: \"warm analog synths, driving bass, 80s production style\" |\n| 4 | **Too many words per lyric line** | AI rushes through words → slurred, unnatural vocals | Keep lines ≤10 words. Short lines = better vocal delivery |\n| 5 | **No structure tags in lyrics** | Song has no shape — verse/chorus blur together | Always use [Verse], [Chorus], [Bridge], [Outro] tags |\n| 6 | **Rewriting entire prompt between iterations** | Can never isolate what improved (or worsened) the output | Change ONE element at a time. A/B test systematically |\n| 7 | **Ignoring negative prompts** | Unwanted elements creep in (auto-tune, trap hi-hats, reverb) | Explicitly state what to avoid: \"no auto-tune, avoid heavy reverb\" |\n\n---\n\n## Effective vs Ineffective — Side-by-Side Examples\n\n### Example 1: Pop Song\n```\n❌ \"A pop song about love that sounds good\"\n✅ \"bright synth-pop, uplifting, 120 BPM, arpeggiated synths, punchy electronic drums, female vocal with light reverb, 2020s clean production, summer anthem feel\"\n```\n\n### Example 2: Lo-Fi Background\n```\n❌ \"lofi music for studying\"\n✅ \"lo-fi hip-hop, warm and mellow, 75 BPM, dusty vinyl crackle, jazzy Rhodes chords, muted boom-bap drums, no vocals, late-night study session atmosphere\"\n```\n\n### Example 3: Cinematic\n```\n❌ \"epic movie music\"\n✅ \"cinematic orchestral, tension building to triumphant climax, 95 BPM, strings staccato → legato swell, French horns, timpani rolls, choir in final section, Hans Zimmer-style layered percussion\"\n```\n\n### Example 4: Rock Song\n```\n❌ \"energetic rock song, male vocals, guitar solo\"\n✅ \"alternative rock, energetic and raw, 140 BPM, distorted electric guitar riffs, driving bass line, punchy drums, raspy male vocals, anthemic chorus, guitar solo section, garage rock aesthetic, festival anthem energy\"\n```\n\n### Example 5: Traditional Chinese\n```\n❌ \"Chinese music, sad\"\n✅ \"Chinese traditional guofeng, melancholic and nostalgic, 60 BPM, dizi bamboo flute lead melody, guzheng plucked strings, subtle erhu, misty atmosphere, Jiangnan water town imagery, rain and mist soundscape, instrumental only\"\n```\n\n---\n\n## Lyrics Writing: What Separates Good from Bad\n\n### Structure Tags (always use these)\n\n```\n[Intro]\n[Verse]\n[Pre-Chorus]\n[Chorus]\n[Bridge]\n[Break]\n[Outro]\n```\n\n**Standard structure order**: Verse → Chorus → Verse → Chorus → Bridge → Final Chorus → Outro. The Bridge always appears after the second chorus — never before the first.\n\nIf your generated bridge sounds like a second verse, regenerate it with:\n```bash\npython generate_lyrics.py extend \"<existing lyrics>\" \"write a contrasting bridge that shifts perspective, strips back to a single instrument, and sets up the final chorus\"\n```\n\n### Golden Rules for Lyrics That Sing Well\n\n1. **Keep lines short** — 6-10 words per line. Long lines get rushed.\n   ```\n   ❌ \"I've been walking through the streets of this old town thinking about everything we used to do together\"\n   ✅ \"Walking through the old town streets\\n   Thinking of what we used to be\"\n   ```\n\n2. **Match syllable count across verse lines** — Creates natural rhythm.\n   ```\n   ✅ \"Shadows fall on empty streets\"    (7 syllables)\n      \"Whispers lost in evening heat\"    (7 syllables)\n      \"Dancing lights through window panes\" (7 syllables)\n   ```\n\n3. **Use rhyme patterns intentionally** — ABAB or AABB, not random.\n   ```\n   ✅ [Verse]\n      The city sleeps beneath the stars (A)\n      While dreamers chase the fading light (B)\n      We trace our names on passing cars (A)\n      And disappear into the night (B)\n   ```\n\n4. **Chorus should be simpler and more repetitive than verses** — Fewer words, not more. Whitespace and repetition create impact; repetition IS the melody.\n\n5. **Don't over-explain in lyrics** — Imagery > exposition.\n\n---\n\n## Writing a Memorable Hook\n\nThe hook is the most important line in your song. Get it right:\n\n### 1. Length and singability\n4-8 words, singable on first listen, usually contains the song's title.\n\n```\n✅ \"I will always love you\" — simple, universal, title, singable\n✅ \"Rolling in the deep\" — 4 words, vivid, singable\n❌ \"I feel the way I feel when I think about our story\" — too long, too vague\n```\n\n### 2. End chorus lines on open vowels\nAI vocals hold the last syllable of each line. Open vowels (oh, ah, ay, ee) sustain beautifully. Closed consonants (mm, th, ff, ss) sound awkward when held.\n\n```\n✅ \"Let me go\" → ends on \"oh\" — sustains well\n❌ \"Let me breathe\" → ends on closed \"th\" sound — awkward to hold\n```\n\n### 3. Chorus density\nA chorus should have FEWER words than a verse, not more. The space around the hook gives it impact.\n\n```\n❌ \"I feel sad because you left me and now I'm alone\"\n✅ \"Empty chair across the table\\n   Coffee cold, the morning grey\"\n```\n\n---\n\n## Auto-Generate Lyrics First, Then Refine\n\n```bash\n# Generate lyrics from a concept\npython generate_lyrics.py generate \"a bittersweet farewell song, two old friends parting ways after summer\"\n\n# Extend if you need more sections\npython generate_lyrics.py extend \"[Verse]\\nThe last light paints the pier in gold...\"\n```\n\n---\n\n## Iteration Strategy (How Pros Refine)\n\n1. **First generation**: Use your best-guess prompt + n=3\n2. **Listen to all choices**: Note what's good and what's off\n3. **Adjust ONE element**: If rhythm is wrong → change BPM/drums description. If mood is off → change mood descriptors\n4. **Re-generate**: Same lyrics, tweaked prompt\n5. **Compare**: Does the change improve or worsen?\n6. **Repeat** until satisfied\n\n### What to Listen For\n\n**For vocal songs:**\n| Symptom | Fix |\n|---------|-----|\n| Vocals feel rushed / words swallowed | Shorten lyric lines, reduce syllables per line |\n| No energy build between verse and chorus | Add mood progression arc to prompt (e.g., \"sparse → full cathartic release\") |\n| Hook doesn't stick | Simplify chorus to 4-8 words, repeat title phrase, check lines end on open vowels |\n| Tempo feels wrong | Adjust BPM ±10 and regenerate |\n| Listed instruments not audible | Verify each instrument is named explicitly in the prompt |\n\n**For instrumentals / ambient:**\n| Symptom | Fix |\n|---------|-----|\n| Tempo feels wrong | Adjust BPM ±10 |\n| Mood doesn't match intent | Audit all mood descriptors for internal consistency |\n| Instruments missing | Verify each is named explicitly in the prompt |\n\n**Never rewrite the entire prompt at once.** You'll lose track of what works.\n\n---\n\n## Production Checklist (Before You Generate)\n\nBefore hitting generate, verify:\n\n- [ ] **Genre is specific**: Not just \"pop\" but \"synth-pop, 2020s, clean production\"\n- [ ] **Mood is consistent**: No contradictions (slow + energetic = confused AI)\n- [ ] **BPM is set**: Even approximate (\"~90 BPM, slow groove\") helps\n- [ ] **3-5 instruments listed**: Gives the AI sonic anchors\n- [ ] **Vocal style specified**: Or \"no vocals\" / \"instrumental only\"\n- [ ] **Lyrics have structure tags**: [Verse], [Chorus], [Bridge], [Outro]\n- [ ] **Lines are short**: ≤10 words per line\n- [ ] **Avoid list included**: What you DON'T want (auto-tune, trap hi-hats, etc.)\n- [ ] **N > 1**: Generate 2-3 choices and pick the best. Never rely on a single generation\n\nArchive v1.0.1: 5 files, 19894 bytes\n\nFiles: README.md (9245b), references/prompt_guide.md (10296b), scripts/mureka.py (10880b), SKILL.md (16460b), _meta.json (138b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: skywork-music-maker\ndescription: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop songs, orchestral scores, K-POP, reggaetón, guofeng, and more. Supports vocal cloning, reference track style transfer, lyric writing, and full music production workflows. Just say \"make me a chill lo-fi beat\" or describe any musical idea and this skill handles the rest. \nenv:\n  - name: MUREKA_API_KEY\n    required: true\n    description: \"API key from Mureka platform (https://platform.mureka.ai). Register → API Keys → generate key.\"\npermissions:\n  - network\ntags:\n  - music\n  - ai\n  - mureka\n  - skywork\n  - song-generation\n  - lyrics\n  - instrumental\n  - vocal-cloning\n  - music-production\n  - reggaeton\n  - latin-music\n  - 音乐生成\n  - AI作曲\n  - 歌词创作\n  - 音楽生成\n  - AI作曲ツール\n  - 음악생성\n  - AI작곡\n  - generador-de-musica\n  - composicion-musical\n---\n\n# Skywork Music Maker (Mureka API)\n\nGenerate professional-quality music using the Mureka API at https://api.mureka.ai. This skill covers the complete music production workflow: lyrics writing → song/instrumental generation.\n\n## 多语言简介 | Multilingual Overview\n\n### 中文简介\nSkywork Music Maker 是基于 Mureka AI API 的专业音乐创作工具。支持从自然语言描述生成歌曲、纯音乐和歌词，覆盖完整的音乐制作流程。支持中文输入，可根据中文描述自动生成英文提示词。适用于流行音乐、国风音乐、电子音乐等多种风格。主要功能包括：AI 作词、歌曲生成（含人声）、纯音乐生成、人声克隆、参考音频风格迁移。\n\n### 日本語の概要\nSkywork Music Maker は Mureka AI API を使用したプロフェッショナルな音楽制作ツールです。自然言語の説明から楽曲・インストゥルメンタル・歌詞を生成でき、完全な音楽制作ワークフローをカバーします。日本語入力に対応し、日本語の説明から自動的に英語プロンプトを生成します。ポップス、ロック、J-POP、アニソン風、エレクトロニカなど、多様なジャンルに対応。主な機能：AI 作詞、ボーカル付き楽曲生成、インストゥルメンタル生成、ボーカルクローン、リファレンストラックによるスタイル転写。\n\n### 한국어 개요\nSkywork Music Maker는 Mureka AI API를 기반으로 한 전문 음악 제작 도구입니다. 자연어 설명으로 노래, 인스트루멘탈, 가사를 생성하며 완전한 음악 제작 워크플로우를 지원합니다. 한국어 입력을 지원하며, 한국어 설명에서 자동으로 영어 프롬프트를 생성합니다. K-POP, 발라드, 힙합, 인디, 트로트 등 다양한 장르에 대응합니다. 주요 기능: AI 작사, 보컬 포함 곡 생성, 인스트루멘탈 생성, 보컬 클론, 레퍼런스 트랙 기반 스타일 전사.\n\n### Descripción en español\nSkywork Music Maker es una herramienta profesional de creación musical basada en la API de Mureka AI. Permite generar canciones, instrumentales y letras a partir de descripciones en lenguaje natural, cubriendo el flujo completo de producción musical. Compatible con entrada en español: describe tu idea musical en español y el sistema generará automáticamente prompts optimizados en inglés. Soporta una amplia variedad de géneros: reggaetón, salsa, bachata, cumbia, pop latino, flamenco, bossa nova, rock en español y más. Funciones principales: composición de letras con IA, generación de canciones con vocales, producción de instrumentales, clonación de voz y transferencia de estilo mediante pistas de referencia.\n\n---\n\n## Privacy & Data Usage\n\n- **API endpoint**: All API calls are made exclusively to `https://api.mureka.ai` (official Mureka endpoint by Skywork AI)\n- **Data transmitted**: Lyrics text, music prompts, and uploaded audio files (reference tracks, vocal samples, melodies) are sent to Mureka servers for music generation\n- **No third-party sharing**: No data is sent to any service beyond the official Mureka API\n- **Local output**: Generated audio files and lyrics are saved locally to the user-specified output directory\n- **No local caching of credentials**: The API key is read from the `MUREKA_API_KEY` environment variable at runtime; this skill does not store or cache credentials\n- **User-managed billing**: Users must register their own Mureka account at https://platform.mureka.ai; all usage billing is handled directly by Mureka\n- **Upload consent**: File uploads (reference audio, vocal samples, melodies) are initiated only when the user explicitly requests reference-based or vocal-cloning generation\n\n---\n\n## First-Time Setup\n\nBefore running any API command, check if `MUREKA_API_KEY` is set. If not, guide the user to get an API key at https://platform.mureka.ai/ (register → API Keys → generate key → `export MUREKA_API_KEY=\"...\"`), then **STOP** — do not attempt any API calls until the key is configured.\n\n## Smart Prompt Conversion (CRITICAL WORKFLOW)\n\n**Default behavior**: When the user doesn't specify song type, always generate a song with lyrics (use `mureka.py song`). Only use `mureka.py instrumental` when the user explicitly asks for instrumental, BGM, background music, or \"no vocals\".\n\n**Output defaults**: Use mp3 format unless the user requests otherwise. The `--output` flag specifies a directory — the script creates it and saves all results inside (audio files + lyrics.txt for songs). If the user doesn't specify a location, choose a user-friendly path with a descriptive folder name based on the song theme (e.g., `summer_pop_song/`).\n\nWhen users provide music descriptions in natural language (in any language), you **MUST** convert them to structured Mureka API prompts using this workflow:\n\n### Conversion Process\n\n**User Input Examples:**\n- \"upbeat pop song, female vocals, guitar, perfect for summer\"\n- \"sad piano ballad about lost love\"\n- \"epic orchestral music for a fantasy game\"\n- \"traditional Chinese music with bamboo flute and zither, misty atmosphere\"\n- \"明るいJ-POP風の夏の曲を作って\" (Japanese: bright J-POP style summer song)\n- \"슬픈 발라드 만들어줘, 피아노 위주로\" (Korean: make a sad ballad, piano-focused)\n- \"做一首国风古典音乐，要有二胡和古筝\" (Chinese: make a guofeng classical piece with erhu and guzheng)\n- \"Hazme una canción de reggaetón romántico con guitarra acústica\" (Spanish: make a romantic reggaeton song with acoustic guitar)\n\n**Your Task:**\n1. Extract structured parameters using the extraction rules below\n2. Validate the prompt meets quality standards (see Quality Checklist)\n3. Present to user for confirmation before generating\n4. Run the generation command with the structured prompt\n\n### Parameter Extraction Rules\n\nWhen users provide natural language music descriptions, directly extract and structure the following parameters:\n\n**Required Parameters:**\n- **genres**: music genres including fusion styles (e.g., Pop, Rock, Jazz, Pop Rap Fusion, Alternative Rock, Guofeng, J-POP, K-POP, Trot, Reggaetón, Salsa, Bachata, Cumbia, Flamenco, Bossa Nova)\n- **moods**: emotional tones (e.g., Happy, Melancholic, Energetic, Nostalgic, Bright)\n- **instruments**: specific instruments (e.g., Piano, Guitar, Drums, Erhu, Guzheng, Synth Pads, Dizi, Shamisen, Gayageum, Cajón, Congas, Bongos, Tres, Charango)\n- **rhythms**: rhythm characteristics (e.g., 4/4, Slow, Syncopated, Driving, Flowing)\n- **vocals**: vocal attributes (e.g., Female, Husky, Whispered, Male, Soft, Clear) or \"instrumental only\"\n- **key**: musical key if specified (e.g., C Major, A Minor, C# Major)\n- **bpm**: beats per minute (e.g., 120) or tempo descriptor (e.g., \"slow groove\", \"uptempo\")\n- **description**: concise summary (under 50 words) capturing mood progression, melody, harmony, timbre, texture, dynamics\n\n**Extraction Instructions:**\n- **Translate non-English terms**: Convert ALL non-English musical terms to English while preserving cultural and musical meaning\n- **Preserve specificity**: Keep detailed information including specific styles, subgenres, and cultural context (e.g., \"Chinese traditional guofeng\" not just \"Chinese music\")\n- **Design dynamic arc**: Include mood progression where appropriate (e.g., \"sparse opening → building tension → cathartic chorus\")\n- **Infer intelligently**: Make reasonable assumptions based on genre conventions when parameters are not explicitly stated\n- **English output**: Final prompt string MUST be entirely in English\n\n**Generate Structured Prompt:** Combine all extracted parameters into a comprehensive, natural-flowing description that captures the essence of the user's vision.\n\n### Quality Checklist (Validate BEFORE Generation)\n\nBefore running the generation command, verify the prompt meets these criteria:\n\n**MUST HAVE:**\n- ☑ Specific genre (NOT \"pop song\" but \"synth-pop, 2020s\")\n- ☑ BPM or tempo descriptor (e.g., \"120 BPM\" or \"slow groove\")\n- ☑ 3-5 instruments explicitly named\n- ☑ Mood/emotion descriptors (2-3 words)\n- ☑ Vocal style (or \"instrumental only\")\n- ☑ Structure tags in lyrics: [Verse], [Chorus], [Bridge], [Outro]\n\n**WATCH OUT FOR:**\n- Vague terms: \"nice\", \"good\", \"beautiful\" → replace with specific descriptors\n- Contradictions: \"slow\" + \"energetic\", \"sad\" + \"uplifting\" → pick one direction\n- Too short: <50 chars → add more detail\n- Long lyric lines: >10 words per line → split into shorter lines\n- No dynamic arc: add mood progression (e.g., \"sparse → building → full\")\n\n**AVOID:**\n- Command verbs: \"create a song\" → use descriptions \"upbeat pop song\"\n- Famous artist names: \"sounds like Taylor Swift\" → describe qualities instead\n- Unrealistic combos: melody_id cannot combine with other control options\n\nAfter validation, present the generated prompt to the user for confirmation before proceeding.\n\n---\n\n## Core Workflow: Production Pipeline\n\n1. **Conceptualize** → User describes in natural language → YOU convert to structured prompt\n2. **Validate** → Check prompt quality against Quality Checklist (see above)\n3. **Write Lyrics** → Use lyrics/generate or write manually\n4. **Upload References** → Optional: reference track, vocal sample, melody\n5. **Generate** → Submit song/instrumental task (async) with validated prompt\n6. **Evaluate** → Listen to all N choices, pick best\n7. **Iterate** → Refine prompt based on what you heard\n\n**Critical Steps:**\n- Step 1 is mandatory when user provides natural language input (especially non-English)\n- Step 2 validation prevents 80% of common generation failures\n- Step 3: Read `references/prompt_guide.md` for prompt crafting examples, lyrics structure rules (line length, syllable count, rhyme patterns, hook writing), and iteration best practices\n- Do NOT skip conceptualization — jumping straight to generation without a clear concept is the #1 reason for generic results\n\n**Your Role as AI Assistant:**\n1. Convert user's natural language → structured Mureka prompt (using Smart Prompt Conversion)\n2. Validate prompt quality → flag issues → suggest fixes\n3. Write or generate lyrics with proper structure\n4. Present prompt to user for confirmation\n5. Execute generation command with validated prompt\n6. Help iterate and refine based on generation results\n\n---\n\n## CLI Tool\n\nAll operations go through a single script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\nRun `python scripts/mureka.py --help` for full usage. Note: use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n## Common Scenarios\n\n### \"I just want background music for my video\"\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion, background music for tech product video\" \\\n  --output ./bg_music\n```\n\n### \"I want a song but don't have lyrics\"\n```bash\n# Step 1: Generate lyrics with proper structure\npython scripts/mureka.py lyrics generate \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Copy/refine the output, then generate the song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste lyrics here)\\n[Chorus]\\n(paste chorus here)\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, soft drums, male vocal\" \\\n  --output ./summer_song\n```\n\n---\n\n## Advanced Features\n\n### Reference-Based Generation\nUpload a reference track (must be exactly 30s, mp3/m4a) to guide the style:\n```bash\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# → File ID: 542321\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --reference-id 542321 --output ./song\n```\n\n### Vocal Cloning\nUpload a vocal sample (15-30s, mp3/m4a) to use a specific voice:\n```bash\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# → File ID: 789012\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --vocal-id 789012 --prompt \"R&B, smooth, 90 BPM\" --output ./song\n```\n\n---\n\n## Control Options & Rules\n\n### Song Generation Control Combos\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- `melody_id` does NOT support any combination — use it alone\n- `prompt` and `reference_id` are mutually exclusive — use one or the other\n\n### Instrumental Generation Rules\nFor instrumentals, `prompt` and `instrumental_id` are mutually exclusive — use one or the other.\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| reference | mp3/m4a | exactly 30s | Excess trimmed |\n| vocal | mp3/m4a | 15-30s | Excess trimmed |\n| melody | mp3/m4a/mid | 5-60s | MIDI recommended |\n| instrumental | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\nAlways use `mureka-8` — it is the latest and highest quality model.\n\n---\n\n## Error Handling\n\nScripts raise `RuntimeError` or `requests.HTTPError` on failure. Handle common errors:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| 401 Unauthorized | Invalid or expired API key | Ask user to verify `MUREKA_API_KEY` |\n| 429 Too Many Requests | Rate limit exceeded | Wait 30-60 seconds, then retry |\n| 402 / Insufficient balance | Account balance depleted | Direct user to https://platform.mureka.ai to top up |\n| Task ended with status: failed | Generation failed (bad prompt, server error) | Check prompt against Quality Checklist, retry |\n| Task ended with status: timeouted | Generation took too long | Retry; if persistent, simplify the prompt or try a different model |\n| ConnectionError / Timeout | Network issue | Retry after a few seconds |\n\n**General strategy:** Read the error message carefully. If it's a client error (4xx), fix the input. If it's a server error (5xx) or timeout, retry once before escalating to the user.\n\n## Troubleshooting Common Issues\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | Check prompt meets quality checklist; verify lyrics have structure tags; retry the generation |\n| Vocals sound rushed | Shorten lyric lines (≤10 words); reduce syllables per line |\n| Listed instruments not audible | Verify each instrument named explicitly in prompt; add more specific descriptors |\n| Prompt doesn't match output | Increase specificity (exact genre, BPM, instruments); add mood progression; generate n=3 choices |\n| melody_id error | melody_id MUST be used alone — remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | File IDs only valid for account that uploaded — re-upload file if from another session |\n\nFor parameter help:\n```bash\npython scripts/mureka.py --help\npython scripts/mureka.py song --help\n```\n\n---\n\n## Environment\n\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **Base URL**: https://api.mureka.ai\n- **Dependencies**: Python 3, `requests` library\n- **Billing**: Check balance with `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\nFile v1.0.1:README.md\n\n# Skywork Music Maker 1.0.0\n\nAI-powered music generation skill for Claude Code and other AI agent frameworks. Create professional songs, instrumentals, and lyrics using Mureka AI API with natural language descriptions in any language.\n\n## Quick Links\n\n- **[SKILL.md](SKILL.md)** - Complete agent guide (start here)\n- **[references/prompt_guide.md](references/prompt_guide.md)** - Music craftsmanship guide (MANDATORY reading for lyrics tasks)\n- **[scripts/mureka.py](scripts/mureka.py)** - Unified CLI tool for all operations\n\n## Installation\n\n### For Claude Code / Codex\n```bash\n# Option 1: Use directly from this repo\n# Reference as: @skywork-music-maker-1.0.0\n\n# Option 2: Install to ~/.claude/skills\ncp -r skywork-music-maker-1.0.0 ~/.claude/skills/\n```\n\n### For Gemini CLI\n```bash\n# Install to skills directory (check your platform's docs)\ncp -r skywork-music-maker-1.0.0 /path/to/gemini/skills/\n```\n\n### For Other AI Frameworks\nCopy the directory to your framework's skills location. The skill follows standard conventions and should work with any framework supporting tool-based agents.\n\n## Key Features\n\n✅ **Natural language to music** - Describe in any language, get structured prompts\n✅ **Smart validation** - Quality checks before generation\n✅ **Complete workflow** - Lyrics → Song/Instrumental → Analysis → Extension\n✅ **Unified CLI** - Single `mureka.py` script for all operations\n✅ **Agent-optimized** - Self-documenting code, clear documentation structure\n✅ **Production-ready** - Best practices from real music production practitioners\n\n## Quick Start\n\n### 1. Set up API key\n\n```bash\n# Get your API key from https://platform.mureka.ai\nexport MUREKA_API_KEY=\"your_api_key\"\n```\n\n### 2. Generate music with natural language\n\n```bash\n# The AI agent will convert your description to a structured prompt\nUser: \"create an upbeat summer pop song with female vocals\"\nAI: [Converts to structured prompt, validates, generates]\n\n# Or use the CLI directly\ncd scripts/\npython mureka.py song \\\n  --lyrics \"[Verse]\\nWalking down the beach...\" \\\n  --prompt \"indie pop, 110 BPM, acoustic guitar, female vocal, warm and nostalgic\" \\\n  --output ./my_song\n```\n\n### 3. Check the results\n\n```bash\n# Generated files will be in the output directory:\nls ./my_song/\n# output_0.mp3  output_1.mp3  lyrics.txt\n```\n\n## CLI Tool\n\nAll operations use a single unified script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics using AI\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\n**Usage:**\n```bash\npython scripts/mureka.py --help              # Show all commands\npython scripts/mureka.py song --help         # Song-specific options\npython scripts/mureka.py instrumental --help # Instrumental options\npython scripts/mureka.py lyrics --help       # Lyrics generation options\npython scripts/mureka.py upload --help       # Upload options\n```\n\n**Important:** Use `-n 2` (single dash) to generate multiple choices, not `--n`.\n\n## Common Scenarios\n\n### Background music for videos\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion\" \\\n  --output ./bg_music\n```\n\n### Song without lyrics yet\n```bash\n# Step 1: Generate lyrics\npython scripts/mureka.py lyrics generate \\\n  \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Use the generated lyrics for your song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste generated lyrics here)\\n[Chorus]\\n...\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, male vocal\" \\\n  --output ./summer_song\n```\n\n### With reference track (style transfer)\n```bash\n# Upload 30-second reference track\npython scripts/mureka.py upload my_reference.mp3 --purpose reference\n# Returns: File ID: 542321\n\n# Generate song using that style\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --reference-id 542321 \\\n  --output ./song_with_style\n```\n\n### Vocal cloning\n```bash\n# Upload 15-30 second vocal sample\npython scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# Returns: File ID: 789012\n\n# Generate song with cloned voice\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n...\" \\\n  --vocal-id 789012 \\\n  --prompt \"R&B, smooth, 90 BPM, emotional\" \\\n  --output ./cloned_voice_song\n```\n\n## File Structure\n\n```\nskywork-music-maker-1.0.0/\n├── SKILL.md                    # Complete agent guide\n├── README.md                   # This file\n├── references/\n│   └── prompt_guide.md        # Music craftsmanship guide (MANDATORY for lyrics)\n└── scripts/\n    └── mureka.py              # Unified CLI tool (use --help for docs)\n```\n\n## Smart Prompt Conversion\n\nWhen you describe music in natural language (in any language), the AI agent automatically:\n\n1. **Extracts structured parameters** - Genres, moods, instruments, BPM, vocals, key\n2. **Validates quality** - Checks against quality checklist to prevent generation failures\n3. **Presents for confirmation** - Shows you the structured prompt before generation\n4. **Executes generation** - Runs the API call with the validated prompt\n\nThis prevents 80% of common generation failures and ensures high-quality results.\n\n## Control Options & Requirements\n\n### Song Generation Combinations\n\n| Combo | prompt | reference_id | vocal_id | melody_id |\n|-------|--------|-------------|----------|-----------|\n| Style only | ✅ | | | |\n| Reference only | | ✅ | | |\n| Voice only | | | ✅ | |\n| Melody only | | | | ✅ |\n| Style + Voice | ✅ | | ✅ | |\n| Reference + Voice | | ✅ | ✅ | |\n\n**Important:**\n- `melody_id` does NOT support any combination — use it alone\n- `prompt` and `reference_id` are mutually exclusive\n\n### File Upload Requirements\n\n| Purpose | Format | Duration | Notes |\n|---------|--------|----------|-------|\n| `reference` | mp3/m4a | exactly 30s | Excess trimmed |\n| `vocal` | mp3/m4a | 15-30s | Excess trimmed |\n| `melody` | mp3/m4a/mid | 5-60s | MIDI recommended |\n| `instrumental` | mp3/m4a | exactly 30s | For instrumental reference |\n\n### Model Selection\n\nAlways use `mureka-8` — it is the latest and highest quality model (default in scripts).\n\n## Error Handling\n\nCommon errors and solutions:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `401 Unauthorized` | Invalid/expired API key | Verify `MUREKA_API_KEY` |\n| `429 Too Many Requests` | Rate limit exceeded | Wait 30-60 seconds, retry |\n| `402 / Insufficient balance` | Account depleted | Top up at https://platform.mureka.ai |\n| `Task failed` | Bad prompt/server error | Check Quality Checklist, retry |\n| `Task timeouted` | Generation took too long | Simplify prompt, retry |\n| `ConnectionError` | Network issue | Retry after a few seconds |\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| Task failed or timeouted | • Check prompt meets quality checklist<br>• Verify lyrics have structure tags<br>• Retry |\n| Vocals sound rushed | • Shorten lyric lines (≤10 words)<br>• Reduce syllables per line |\n| Instruments not audible | • Name each instrument explicitly<br>• Add specific descriptors (e.g., \"acoustic guitar strumming\") |\n| Output doesn't match prompt | • Increase specificity (exact genre, BPM)<br>• Add mood progression (\"sparse → full\")<br>• Generate n=3 choices |\n| melody_id error | • melody_id MUST be used alone<br>• Remove --prompt, --reference-id, --vocal-id |\n| Invalid file_id | • File IDs only valid for uploading account<br>• Re-upload if from another session |\n\n## Environment Requirements\n\n- **Python**: 3.7+\n- **Dependencies**: `requests` library (`pip install requests`)\n- **API Key**: `MUREKA_API_KEY` environment variable (required)\n- **API Base URL**: `https://api.mureka.ai`\n\n## Support & Resources\n\n- **Issues & Feedback**: [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)\n- **Mureka API Docs**: [platform.mureka.ai](https://platform.mureka.ai)\n- **Get API Key**: [platform.mureka.ai](https://platform.mureka.ai) → Register → API Keys → Generate\n- **Check Balance**: `curl -H \"Authorization: Bearer $MUREKA_API_KEY\" https://api.mureka.ai/v1/account/billing`\n\n## Examples\n\n### Traditional Chinese Music\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n春风拂面...\" \\\n  --prompt \"Chinese traditional guofeng, 90 BPM, bamboo flute (dizi), guzheng, erhu, misty atmosphere, ancient poetry aesthetic\" \\\n  --output ./chinese_style\n```\n\n### Electronic Dance Music\n```bash\npython scripts/mureka.py instrumental \\\n  --prompt \"progressive house, 128 BPM, synth leads, deep bass, atmospheric pads, building energy\" \\\n  -n 3 \\\n  --output ./edm_track\n```\n\n### Jazz Ballad\n```bash\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\nUnder the midnight sky...\" \\\n  --prompt \"jazz ballad, slow groove, piano, upright bass, soft brushed drums, female husky vocal, intimate\" \\\n  --output ./jazz_ballad\n```\n\n## License\n\nSame as parent repository.\n\n---\n\n**For detailed music production guidance, prompt crafting examples, and lyric writing best practices, see [references/prompt_guide.md](references/prompt_guide.md).**\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn70ct0m3p4538a9t49cjcwern82ky02\",\n  \"slug\": \"skywork-music-maker\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1773828685667\n}\n\nFile v1.0.1:references/prompt_guide.md\n\n# Music Prompt Crafting Guide\n\nComprehensive guide to writing effective music prompts for Mureka AI.\n\n## The Golden Rule: DESCRIBE, Don't Command\n\n```\n❌ \"Create an energetic pop song with drums\"\n✅ \"energetic pop, driving four-on-the-floor drums, bright synth hooks, 128 BPM, female vocal, festival anthem vibe\"\n```\n\nThe AI responds to descriptions of the music, not instructions to \"make\" or \"create\" it.\n\n---\n\n## Design a Dynamic Arc, Not a Static Description\n\nThe most common reason AI-generated songs sound flat is that the prompt describes one mood level throughout. Great songs are tension/release journeys — design yours explicitly.\n\nExpress the arc as a **mood progression string** in your prompt:\n```\n✅ \"sparse and intimate opening → rising tension → full cathartic chorus → stripped-back bridge → bigger final chorus\"\n✅ \"melancholic and sparse → building urgency → explosive release → quiet resolution\"\n```\n\nThe AI interprets this as an emotional journey across the song. Without it, every section gets the same energy and density.\n\n---\n\n## Effective Prompt Structure\n\n### Minimum Viable Prompt (always include these)\n```\n[genre + sub-genre], [mood/emotion], [tempo/BPM], [key instruments], [vocal style]\n```\n\n### Standard Prompt (recommended for good results)\n```\nGenre: [specific genre + era, e.g., \"90s trip-hop\"]\nMood: [2-3 descriptors, e.g., \"melancholic, introspective, nocturnal\"]\nTempo: [BPM or description, e.g., \"85 BPM, slow groove\"]\nInstruments: [3-5 key instruments, e.g., \"turntable scratches, Rhodes piano, upright bass\"]\nVocals: [style, e.g., \"breathy female vocals, intimate delivery\"]\nScene: [usage context, e.g., \"late-night city driving\"]\n```\n\n### Production Brief (for maximum control)\n```\nGenre: trip-hop | Era: mid-90s Bristol\nBPM: 85 | Key: D minor\nMood: melancholic → building tension → cathartic release\nLead: Rhodes piano, tremolo\nRhythm: breakbeat, vinyl crackle texture\nBass: deep sub-bass, Moog-style\nTexture: tape saturation, lo-fi warmth\nVocals: breathy female, close-mic intimacy\nStructure: Intro(8bars) / Verse / Chorus / Verse / Bridge / Chorus / Outro\nAvoid: auto-tune, bright synths, four-on-the-floor kick\nReference: Portishead \"Roads\" (breakbeat texture, Rhodes tone)\n```\n\n**Note on references**: Only use specific songs as sonic benchmarks when all other parameters are already specified. Different from \"sound like [artist]\" — use for named production qualities (e.g., \"Roads-style breakbeat texture\").\n\n---\n\n## What Makes Prompts FAIL (Top 7 Mistakes)\n\n| # | Mistake | Why It Fails | Fix |\n|---|---------|-------------|-----|\n| 1 | **Vague prompts** (\"nice pop song\") | AI defaults to the statistical average — generic, forgettable | Be ruthlessly specific: sub-genre + era + mood + instruments + BPM |\n| 2 | **Contradictions** (\"slow and relaxing, high energy, 160 BPM\") | Conflicting signals make the AI unpredictable | Check every descriptor agrees with the mood. Pick one direction |\n| 3 | **\"Sound like [famous artist]\"** | Copyright risk + AI interprets literally, often misses the point | Describe the *qualities* you like: \"warm analog synths, driving bass, 80s production style\" |\n| 4 | **Too many words per lyric line** | AI rushes through words → slurred, unnatural vocals | Keep lines ≤10 words. Short lines = better vocal delivery |\n| 5 | **No structure tags in lyrics** | Song has no shape — verse/chorus blur together | Always use [Verse], [Chorus], [Bridge], [Outro] tags |\n| 6 | **Rewriting entire prompt between iterations** | Can never isolate what improved (or worsened) the output | Change ONE element at a time. A/B test systematically |\n| 7 | **Ignoring negative prompts** | Unwanted elements creep in (auto-tune, trap hi-hats, reverb) | Explicitly state what to avoid: \"no auto-tune, avoid heavy reverb\" |\n\n---\n\n## Effective vs Ineffective — Side-by-Side Examples\n\n### Example 1: Pop Song\n```\n❌ \"A pop song about love that sounds good\"\n✅ \"bright synth-pop, uplifting, 120 BPM, arpeggiated synths, punchy electronic drums, female vocal with light reverb, 2020s clean production, summer anthem feel\"\n```\n\n### Example 2: Lo-Fi Background\n```\n❌ \"lofi music for studying\"\n✅ \"lo-fi hip-hop, warm and mellow, 75 BPM, dusty vinyl crackle, jazzy Rhodes chords, muted boom-bap drums, no vocals, late-night study session atmosphere\"\n```\n\n### Example 3: Cinematic\n```\n❌ \"epic movie music\"\n✅ \"cinematic orchestral, tension building to triumphant climax, 95 BPM, strings staccato → legato swell, French horns, timpani rolls, choir in final section, Hans Zimmer-style layered percussion\"\n```\n\n### Example 4: Rock Song\n```\n❌ \"energetic rock song, male vocals, guitar solo\"\n✅ \"alternative rock, energetic and raw, 140 BPM, distorted electric guitar riffs, driving bass line, punchy drums, raspy male vocals, anthemic chorus, guitar solo section, garage rock aesthetic, festival anthem energy\"\n```\n\n### Example 5: Traditional Chinese\n```\n❌ \"Chinese music, sad\"\n✅ \"Chinese traditional guofeng, melancholic and nostalgic, 60 BPM, dizi bamboo flute lead melody, guzheng plucked strings, subtle erhu, misty atmosphere, Jiangnan water town imagery, rain and mist soundscape, instrumental only\"\n```\n\n---\n\n## Lyrics Writing: What Separates Good from Bad\n\n### Structure Tags (always use these)\n\n```\n[Intro]\n[Verse]\n[Pre-Chorus]\n[Chorus]\n[Bridge]\n[Break]\n[Outro]\n```\n\n**Standard structure order**: Verse → Chorus → Verse → Chorus → Bridge → Final Chorus → Outro. The Bridge always appears after the second chorus — never before the first.\n\nIf your generated bridge sounds like a second verse, regenerate it with:\n```bash\npython generate_lyrics.py extend \"<existing lyrics>\" \"write a contrasting bridge that shifts perspective, strips back to a single instrument, and sets up the final chorus\"\n```\n\n### Golden Rules for Lyrics That Sing Well\n\n1. **Keep lines short** — 6-10 words per line. Long lines get rushed.\n   ```\n   ❌ \"I've been walking through the streets of this old town thinking about everything we used to do together\"\n   ✅ \"Walking through the old town streets\\n   Thinking of what we used to be\"\n   ```\n\n2. **Match syllable count across verse lines** — Creates natural rhythm.\n   ```\n   ✅ \"Shadows fall on empty streets\"    (7 syllables)\n      \"Whispers lost in evening heat\"    (7 syllables)\n      \"Dancing lights through window panes\" (7 syllables)\n   ```\n\n3. **Use rhyme patterns intentionally** — ABAB or AABB, not random.\n   ```\n   ✅ [Verse]\n      The city sleeps beneath the stars (A)\n      While dreamers chase the fading light (B)\n      We trace our names on passing cars (A)\n      And disappear into the night (B)\n   ```\n\n4. **Chorus should be simpler and more repetitive than verses** — Fewer words, not more. Whitespace and repetition create impact; repetition IS the melody.\n\n5. **Don't over-explain in lyrics** — Imagery > exposition.\n\n---\n\n## Writing a Memorable Hook\n\nThe hook is the most important line in your song. Get it right:\n\n### 1. Length and singability\n4-8 words, singable on first listen, usually contains the song's title.\n\n```\n✅ \"I will always love you\" — simple, universal, title, singable\n✅ \"Rolling in the deep\" — 4 words, vivid, singable\n❌ \"I feel the way I feel when I think about our story\" — too long, too vague\n```\n\n### 2. End chorus lines on open vowels\nAI vocals hold the last syllable of each line. Open vowels (oh, ah, ay, ee) sustain beautifully. Closed consonants (mm, th, ff, ss) sound awkward when held.\n\n```\n✅ \"Let me go\" → ends on \"oh\" — sustains well\n❌ \"Let me breathe\" → ends on closed \"th\" sound — awkward to hold\n```\n\n### 3. Chorus density\nA chorus should have FEWER words than a verse, not more. The space around the hook gives it impact.\n\n```\n❌ \"I feel sad because you left me and now I'm alone\"\n✅ \"Empty chair across the table\\n   Coffee cold, the morning grey\"\n```\n\n---\n\n## Auto-Generate Lyrics First, Then Refine\n\n```bash\n# Generate lyrics from a concept\npython generate_lyrics.py generate \"a bittersweet farewell song, two old friends parting ways after summer\"\n\n# Extend if you need more sections\npython generate_lyrics.py extend \"[Verse]\\nThe last light paints the pier in gold...\"\n```\n\n---\n\n## Iteration Strategy (How Pros Refine)\n\n1. **First generation**: Use your best-guess prompt + n=3\n2. **Listen to all choices**: Note what's good and what's off\n3. **Adjust ONE element**: If rhythm is wrong → change BPM/drums description. If mood is off → change mood descriptors\n4. **Re-generate**: Same lyrics, tweaked prompt\n5. **Compare**: Does the change improve or worsen?\n6. **Repeat** until satisfied\n\n### What to Listen For\n\n**For vocal songs:**\n| Symptom | Fix |\n|---------|-----|\n| Vocals feel rushed / words swallowed | Shorten lyric lines, reduce syllables per line |\n| No energy build between verse and chorus | Add mood progression arc to prompt (e.g., \"sparse → full cathartic release\") |\n| Hook doesn't stick | Simplify chorus to 4-8 words, repeat title phrase, check lines end on open vowels |\n| Tempo feels wrong | Adjust BPM ±10 and regenerate |\n| Listed instruments not audible | Verify each instrument is named explicitly in the prompt |\n\n**For instrumentals / ambient:**\n| Symptom | Fix |\n|---------|-----|\n| Tempo feels wrong | Adjust BPM ±10 |\n| Mood doesn't match intent | Audit all mood descriptors for internal consistency |\n| Instruments missing | Verify each is named explicitly in the prompt |\n\n**Never rewrite the entire prompt at once.** You'll lose track of what works.\n\n---\n\n## Production Checklist (Before You Generate)\n\nBefore hitting generate, verify:\n\n- [ ] **Genre is specific**: Not just \"pop\" but \"synth-pop, 2020s, clean production\"\n- [ ] **Mood is consistent**: No contradictions (slow + energetic = confused AI)\n- [ ] **BPM is set**: Even approximate (\"~90 BPM, slow groove\") helps\n- [ ] **3-5 instruments listed**: Gives the AI sonic anchors\n- [ ] **Vocal style specified**: Or \"no vocals\" / \"instrumental only\"\n- [ ] **Lyrics have structure tags**: [Verse], [Chorus], [Bridge], [Outro]\n- [ ] **Lines are short**: ≤10 words per line\n- [ ] **Avoid list included**: What you DON'T want (auto-tune, trap hi-hats, etc.)\n- [ ] **N > 1**: Generate 2-3 choices and pick the best. Never rely on a single generation\n\nArchive v1.0.0: 5 files, 17487 bytes\n\nFiles: README.md (9245b), references/prompt_guide.md (10296b), scripts/mureka.py (10880b), SKILL.md (11972b), _meta.json (138b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: skywork-music-maker\ndescription: Create professional music with Mureka AI API — songs, instrumentals, and lyrics from natural language descriptions in any language. Use when users want to generate a song, create a beat or instrumental, write lyrics, clone vocals, upload reference tracks, or do anything related to AI music creation, even casual requests like \"make me a chill lo-fi beat\".\n---\n\n# Skywork Music Maker (Mureka API)\n\nGenerate professional-quality music using the Mureka API at `https://api.mureka.ai`. This skill covers the **complete music production workflow**: lyrics writing → song/instrumental generation.\n\n## First-Time Setup\n\nBefore running any API command, check if `MUREKA_API_KEY` is set. If not, guide the user to get an API key at https://platform.mureka.ai/ (register → API Keys → generate key → `export MUREKA_API_KEY=\"...\"`), then STOP — do not attempt any API calls until the key is configured.\n\n---\n\n## Smart Prompt Conversion (CRITICAL WORKFLOW)\n\n**Default behavior**: When the user doesn't specify song type, always generate a **song with lyrics** (use `mureka.py song`). Only use `mureka.py instrumental` when the user explicitly asks for instrumental, BGM, background music, or \"no vocals\".\n\n**Output defaults**: Use mp3 format unless the user requests otherwise. The `--output` flag specifies a directory — the script creates it and saves all results inside (audio files + `lyrics.txt` for songs). If the user doesn't specify a location, choose a user-friendly path with a descriptive folder name based on the song theme (e.g., `summer_pop_song/`).\n\nWhen users provide music descriptions in **natural language** (in any language), you MUST convert them to structured Mureka API prompts using this workflow:\n\n### Conversion Process\n\n**User Input Examples:**\n- \"upbeat pop song, female vocals, guitar, perfect for summer\"\n- \"sad piano ballad about lost love\"\n- \"epic orchestral music for a fantasy game\"\n- \"traditional Chinese music with bamboo flute and zither, misty atmosphere\"\n\n**Your Task:**\n1. **Extract structured parameters** using the extraction rules below\n2. **Validate** the prompt meets quality standards (see Quality Checklist)\n3. **Present to user** for confirmation before generating\n4. **Run the generation** command with the structured prompt\n\n### Parameter Extraction Rules\n\nWhen users provide natural language music descriptions, directly extract and structure the following parameters:\n\n**Required Parameters:**\n- **genres**: music genres including fusion styles (e.g., Pop, Rock, Jazz, Pop Rap Fusion, Alternative Rock, Guofeng)\n- **moods**: emotional tones (e.g., Happy, Melancholic, Energetic, Nostalgic, Bright)\n- **instruments**: specific instruments (","readmeExcerpt":"Skill: Skywork Music Maker Owner: gxcun17 Summary: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop s... Tags: latest:1.0.4 Version history: v1.0.4 | 2026-04-09T12:32:02.909Z | user **skywork-music-maker 1.0.4 Changelog** - Added _meta.json for enhanced metadata and compatibility. - Expanded SKILL.md intro and d","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"mureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics\nmureka.py upload         Upload reference audio, vocals, melodies"},{"language":"bash","snippet":"python scripts/mureka.py instrumental \\\n  --prompt \"ambient electronic, calm, 80 BPM, soft pads, no percussion, background music for tech product video\" \\\n  --output ./bg_music"},{"language":"bash","snippet":"# Step 1: Generate lyrics with proper structure\npython scripts/mureka.py lyrics generate \"a nostalgic summer love song, bittersweet, looking back at memories\"\n\n# Step 2: Copy/refine the output, then generate the song\npython scripts/mureka.py song \\\n  --lyrics \"[Verse]\\n(paste lyrics here)\\n[Chorus]\\n(paste chorus here)\" \\\n  --prompt \"indie pop, warm, 110 BPM, acoustic guitar, soft drums, male vocal\" \\\n  --output ./summer_song"},{"language":"bash","snippet":"python scripts/mureka.py upload my_reference.mp3 --purpose reference\n# → File ID: 542321\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --reference-id 542321 --output ./song"},{"language":"bash","snippet":"python scripts/mureka.py upload my_voice.mp3 --purpose vocal\n# → File ID: 789012\npython scripts/mureka.py song --lyrics \"[Verse]\\n...\" --vocal-id 789012 --prompt \"R&B, smooth, 90 BPM\" --output ./song"},{"language":"bash","snippet":"python scripts/mureka.py --help\npython scripts/mureka.py song --help"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: skywork-music-maker\ndescription: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop songs, orchestral scores, K-POP, reggaetón, guofeng, and more. Supports vocal cloning, reference track style transfer, lyric writing, and full music production workflows. Just say \"make me a chill lo-fi beat\" or describe any musical idea and this skill handles the rest.\nmetadata:\n  openclaw:\n    requires:\n      env:\n        - MUREKA_API_KEY\n      bins:\n        - python3\n    install:\n      - kind: uv\n        package: requests\n    primaryEnv: MUREKA_API_KEY\n    homepage: https://clawhub.ai/gxcun17/skywork-music-maker\n---\n\n# Skywork Music Maker (Mureka API)\n\nGenerate professional-quality music using the Mureka API at https://api.mureka.ai. This skill covers the complete music production workflow: lyrics writing → song/instrumental generation.\n\n## 多语言简介 | Multilingual Overview\n\n### 中文简介\nSkywork Music Maker 是基于 Mureka AI API 的专业音乐创作工具。支持从自然语言描述生成歌曲、纯音乐和歌词，覆盖完整的音乐制作流程。支持中文输入，可根据中文描述自动生成英文提示词。适用于流行音乐、国风音乐、电子音乐等多种风格。主要功能包括：AI 作词、歌曲生成（含人声）、纯音乐生成、人声克隆、参考音频风格迁移。\n\n### 日本語の概要\nSkywork Music Maker は Mureka AI API を使用したプロフェッショナルな音楽制作ツールです。自然言語の説明から楽曲・インストゥルメンタル・歌詞を生成でき、完全な音楽制作ワークフローをカバーします。日本語入力に対応し、日本語の説明から自動的に英語プロンプトを生成します。ポップス、ロック、J-POP、アニソン風、エレクトロニカなど、多様なジャンルに対応。主な機能：AI 作詞、ボーカル付き楽曲生成、インストゥルメンタル生成、ボーカルクローン、リファレンストラックによるスタイル転写。\n\n### 한국어 개요\nSkywork Music Maker는 Mureka AI API를 기반으로 한 전문 음악 제작 도구입니다. 자연어 설명으로 노래, 인스트루멘탈, 가사를 생성하며 완전한 음악 제작 워크플로우를 지원합니다. 한국어 입력을 지원하며, 한국어 설명에서 자동으로 영어 프롬프트를 생성합니다. K-POP, 발라드, 힙합, 인디, 트로트 등 다양한 장르에 대응합니다. 주요 기능: AI 작사, 보컬 포함 곡 생성, 인스트루멘탈 생성, 보컬 클론, 레퍼런스 트랙 기반 스타일 전사.\n\n### Descripción en español\nSkywork Music Maker es una herramienta profesional de creación musical basada en la API de Mureka AI. Permite generar canciones, instrumentales y letras a partir de descripciones en lenguaje natural, cubriendo el flujo completo de producción musical. Compatible con entrada en español: describe tu idea musical en español y el sistema generará automáticamente prompts optimizados en inglés. Soporta una amplia variedad de géneros: reggaetón, salsa, bachata, cumbia, pop latino, flamenco, bossa nova, rock en español y más. Funciones principales: composición de letras con IA, generación de canciones con vocales, producción de instrumentales, clonación de voz y transferencia de estilo mediante pistas de referencia.\n\n---\n\n## Privacy & Data Usage\n\n- **API endpoint**: All API calls are made exclusively to `https://api.mureka.ai` (official Mureka endpoint by Skywork AI)\n- **Data transmitted**: Lyrics text, music prompts, and uploaded audio files (reference tracks, vocal samples, melodies) are sent to Mureka servers for music generation\n- **No third-party sharing**: No data is sent to any service beyond the official Mureka API\n- **Local output**: Generated audio files and lyrics are saved locally to the user-specified output directory\n- **No local caching of "},{"path":"README.md","content":"# Skywork Music Maker 1.0.0\n\nAI-powered music generation skill for Claude Code and other AI agent frameworks. Create professional songs, instrumentals, and lyrics using Mureka AI API with natural language descriptions in any language.\n\n## Quick Links\n\n- **[SKILL.md](SKILL.md)** - Complete agent guide (start here)\n- **[references/prompt_guide.md](references/prompt_guide.md)** - Music craftsmanship guide (MANDATORY reading for lyrics tasks)\n- **[scripts/mureka.py](scripts/mureka.py)** - Unified CLI tool for all operations\n\n## Installation\n\n### For Claude Code / Codex\n```bash\n# Option 1: Use directly from this repo\n# Reference as: @skywork-music-maker-1.0.0\n\n# Option 2: Install to ~/.claude/skills\ncp -r skywork-music-maker-1.0.0 ~/.claude/skills/\n```\n\n### For Gemini CLI\n```bash\n# Install to skills directory (check your platform's docs)\ncp -r skywork-music-maker-1.0.0 /path/to/gemini/skills/\n```\n\n### For Other AI Frameworks\nCopy the directory to your framework's skills location. The skill follows standard conventions and should work with any framework supporting tool-based agents.\n\n## Key Features\n\n✅ **Natural language to music** - Describe in any language, get structured prompts\n✅ **Smart validation** - Quality checks before generation\n✅ **Complete workflow** - Lyrics → Song/Instrumental → Analysis → Extension\n✅ **Unified CLI** - Single `mureka.py` script for all operations\n✅ **Agent-optimized** - Self-documenting code, clear documentation structure\n✅ **Production-ready** - Best practices from real music production practitioners\n\n## Quick Start\n\n### 1. Set up API key\n\n```bash\n# Get your API key from https://platform.mureka.ai\nexport MUREKA_API_KEY=\"your_api_key\"\n```\n\n### 2. Generate music with natural language\n\n```bash\n# The AI agent will convert your description to a structured prompt\nUser: \"create an upbeat summer pop song with female vocals\"\nAI: [Converts to structured prompt, validates, generates]\n\n# Or use the CLI directly\ncd scripts/\npython mureka.py song \\\n  --lyrics \"[Verse]\\nWalking down the beach...\" \\\n  --prompt \"indie pop, 110 BPM, acoustic guitar, female vocal, warm and nostalgic\" \\\n  --output ./my_song\n```\n\n### 3. Check the results\n\n```bash\n# Generated files will be in the output directory:\nls ./my_song/\n# output_0.mp3  output_1.mp3  lyrics.txt\n```\n\n## CLI Tool\n\nAll operations use a single unified script: `scripts/mureka.py`\n\n```\nmureka.py song           Generate a song with lyrics and vocals\nmureka.py instrumental   Generate an instrumental track\nmureka.py lyrics         Generate or extend lyrics using AI\nmureka.py upload         Upload reference audio, vocals, melodies\n```\n\n**Usage:**\n```bash\npython scripts/mureka.py --help              # Show all commands\npython scripts/mureka.py song --help         # Song-specific options\npython scripts/mureka.py instrumental --help # Instrumental options\npython scripts/mureka.py lyrics --help       # Lyrics generation options\npython scripts/mureka.py upload --help       # Upload options\n```\n\n**Imp"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn70ct0m3p4538a9t49cjcwern82ky02\",\n  \"slug\": \"skywork-music-maker\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1775737922909\n}"},{"path":"references/prompt_guide.md","content":"# Music Prompt Crafting Guide\n\nComprehensive guide to writing effective music prompts for Mureka AI.\n\n## The Golden Rule: DESCRIBE, Don't Command\n\n```\n❌ \"Create an energetic pop song with drums\"\n✅ \"energetic pop, driving four-on-the-floor drums, bright synth hooks, 128 BPM, female vocal, festival anthem vibe\"\n```\n\nThe AI responds to descriptions of the music, not instructions to \"make\" or \"create\" it.\n\n---\n\n## Design a Dynamic Arc, Not a Static Description\n\nThe most common reason AI-generated songs sound flat is that the prompt describes one mood level throughout. Great songs are tension/release journeys — design yours explicitly.\n\nExpress the arc as a **mood progression string** in your prompt:\n```\n✅ \"sparse and intimate opening → rising tension → full cathartic chorus → stripped-back bridge → bigger final chorus\"\n✅ \"melancholic and sparse → building urgency → explosive release → quiet resolution\"\n```\n\nThe AI interprets this as an emotional journey across the song. Without it, every section gets the same energy and density.\n\n---\n\n## Effective Prompt Structure\n\n### Minimum Viable Prompt (always include these)\n```\n[genre + sub-genre], [mood/emotion], [tempo/BPM], [key instruments], [vocal style]\n```\n\n### Standard Prompt (recommended for good results)\n```\nGenre: [specific genre + era, e.g., \"90s trip-hop\"]\nMood: [2-3 descriptors, e.g., \"melancholic, introspective, nocturnal\"]\nTempo: [BPM or description, e.g., \"85 BPM, slow groove\"]\nInstruments: [3-5 key instruments, e.g., \"turntable scratches, Rhodes piano, upright bass\"]\nVocals: [style, e.g., \"breathy female vocals, intimate delivery\"]\nScene: [usage context, e.g., \"late-night city driving\"]\n```\n\n### Production Brief (for maximum control)\n```\nGenre: trip-hop | Era: mid-90s Bristol\nBPM: 85 | Key: D minor\nMood: melancholic → building tension → cathartic release\nLead: Rhodes piano, tremolo\nRhythm: breakbeat, vinyl crackle texture\nBass: deep sub-bass, Moog-style\nTexture: tape saturation, lo-fi warmth\nVocals: breathy female, close-mic intimacy\nStructure: Intro(8bars) / Verse / Chorus / Verse / Bridge / Chorus / Outro\nAvoid: auto-tune, bright synths, four-on-the-floor kick\nReference: Portishead \"Roads\" (breakbeat texture, Rhodes tone)\n```\n\n**Note on references**: Only use specific songs as sonic benchmarks when all other parameters are already specified. Different from \"sound like [artist]\" — use for named production qualities (e.g., \"Roads-style breakbeat texture\").\n\n---\n\n## What Makes Prompts FAIL (Top 7 Mistakes)\n\n| # | Mistake | Why It Fails | Fix |\n|---|---------|-------------|-----|\n| 1 | **Vague prompts** (\"nice pop song\") | AI defaults to the statistical average — generic, forgettable | Be ruthlessly specific: sub-genre + era + mood + instruments + BPM |\n| 2 | **Contradictions** (\"slow and relaxing, high energy, 160 BPM\") | Conflicting signals make the AI unpredictable | Check every descriptor agrees with the mood. Pick one direction |\n| 3 | **\"Sound like [famous artist]\"** | Copyright risk + AI "},{"path":"skill-card.md","content":"## Description:\n\nSkywork Music Maker helps agents turn multilingual music descriptions into structured Mureka API prompts and generate songs, instrumentals, lyrics, and uploaded-reference music workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[gxcun17](https://clawhub.ai/user/gxcun17)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to guide agents through music prompt shaping, lyrics creation, Mureka API calls, reference uploads, vocal cloning workflows, and local audio-file output.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Vocal cloning and reference-track workflows can upload voice samples or copyrighted audio without clear consent safeguards.\n\nMitigation: Use only voice samples and reference audio that the user owns or has documented permission to use, and review vocal-cloning requests before running upload commands.\n\nRisk: Prompts, lyrics, and uploaded audio are transmitted to the Mureka API for generation.\n\nMitigation: Tell users what data will be sent before generation or upload, and avoid sending confidential or sensitive content.\n\nRisk: The documented billing curl pattern can expose MUREKA_API_KEY locally on shared or monitored machines.\n\nMitigation: Prefer commands or clients that read MUREKA_API_KEY from the process environment without placing the token directly in shell history or process listings.\n\nRisk: Unpinned dependency installation can reduce reproducibility.\n\nMitigation: Pin the requests dependency in controlled deployments.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/gxcun17/skills/skywork-music-maker)\n- [OpenClaw Homepage](https://clawhub.ai/gxcun17/skywork-music-maker)\n- [Music Prompt Crafting Guide](references/prompt_guide.md)\n- [Mureka API Endpoint](https://api.mureka.ai)\n- [Mureka Platform](https://platform.mureka.ai)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, files]\n\n**Output Format:** [Markdown guidance with inline shell commands and local audio or lyrics files produced by the CLI]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires MUREKA_API_KEY and sends prompts, lyrics, and uploaded audio to the Mureka API when generation or upload commands are run.]\n\n## Skill Version(s):\n\n1.0.4 (source: release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop s... Skill: Skywork Music Maker Owner: gxcun17 Summary: AI song and music generator — create songs with vocals, instrumentals, beats, and lyrics from a text description in any language. Generate lo-fi beats, pop s... Tags: latest:1.0.4 Version history: v1.0.4 | 2026-04-09T12:32:02.909Z | user **skywork-music-maker 1.0.4 Changelog** - Added _meta.json for enhanced metadata and compatibility. - Expanded SKILL.md intro and d","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1813,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:14:02.446Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:14:02.446Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T19:04:37.278Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}