Suno

📄 SKILL.md

Setup

On first use, read setup.md for integration guidelines.

When to Use

User wants to generate a song. Agent handles the full workflow: writes lyrics, crafts the prompt, guides generation via web or API, and delivers the audio.

Architecture

Memory at ~/suno/. See memory-template.md for structure.

The agent creates this folder to store:

User preferences and favorite styles

Successful prompts for reuse

Quick Reference

| Topic | File |

|-------|------|

| Setup process | setup.md |

| Memory template | memory-template.md |

| API options | api-reference.md |

How to Generate

Option A: Suno Website (Default)

Most users generate directly at suno.com/create:

1. Go to suno.com and log in

2. Choose Simple mode (describe) or Custom mode (lyrics + style)

3. Click Create and wait 30-60 seconds

4. Download the audio

The agent helps craft the perfect prompt before you paste it.

Option B: Third-Party APIs (For Automation)

For programmatic access, see api-reference.md which documents:

aimusicapi.ai (hosted, API key)

EvoLink (hosted, API key)

Self-hosted options (advanced users)

The agent can guide you through API calls if you have one configured.

Core Rules

1. Prompt Structure

Effective prompts follow this pattern:

[Genre] [mood] song about [topic], [vocal description], [tempo/energy], [instruments]

Example: "Indie folk melancholic song about lost love, soft female vocals, slow tempo, acoustic guitar and piano"

2. Be Specific About Vocals

Gender: male, female, duet, choir

Style: raspy, smooth, powerful, whispered, operatic

Range: deep, high-pitched, baritone, soprano

3. Genre + Subgenre = Better Results

| Generic (weak) | Specific (strong) |

|----------------|-------------------|

| Rock | 90s grunge rock |

| Electronic | Deep house with analog synths |

| Pop | 2010s synth-pop |

| Hip hop | Lo-fi boom bap |

4. Mood Layering

Combine 2-3 mood descriptors:

Energy: energetic, chill, explosive, dreamy

Emotion: melancholic, euphoric, nostalgic, hopeful

Atmosphere: dark, bright, ethereal, cinematic

5. Custom Mode Lyrics

[Verse 1]
Your lyrics here
Keep verses 4-6 lines
[Chorus]
Catchy hook here
Repeat key phrases
[Bridge]
Contrast section
[Outro]
Fade out

6. Style Tags

Genres: rock, pop, jazz, classical, electronic, hip-hop, country, R&B, metal, folk, reggae, blues, soul, funk, disco, ambient, lo-fi
Decades: 60s, 70s, 80s, 90s, 2000s, 2010s, modern
Production: lo-fi, polished, raw, clean, vintage, futuristic
Instruments: guitar, piano, synth, drums, bass, strings, brass

7. What to Avoid

Copyrighted artist names ("sounds like Taylor Swift")

Overly long prompts (under 200 chars optimal)

Conflicting styles ("heavy metal lullaby")

Workflow

1. Understand the vision — Genre, mood, purpose

2. Craft the prompt — Apply rules above

3. Write lyrics (if custom mode)

4. User generates — At suno.com or via API

5. Iterate — Refine prompt based on results

Lyric Writing

Hook Patterns

Repetition: Repeat key phrase 2-3x in chorus

Question: End verse with question, answer in chorus

Contrast: Verse low energy, chorus explosive

Rhyme Schemes

AABB: Simple, catchy (pop, country)
ABAB: Classic, narrative (rock, folk)
ABCB: Subtle, sophisticated (jazz, R&B)
Free: Modern, emotional (indie, hip-hop)

Syllable Matching

Keep counts similar:

OK: "Walking down the street" (5) / "Looking for the beat" (5)
Bad: "Walking down" (3) / "I am looking everywhere for something" (10)

Common Traps

Vague prompts ("make a good song") → garbage output

No vocal description → random voice

Incompatible genres → confused generation

Forgetting tempo → inconsistent pacing

Unstructured lyrics → awkward phrasing

Data Storage

This skill stores preferences locally in ~/suno/:

Music preferences and favorite styles

Successful prompts for reuse

All data stays on your machine. The skill itself makes no external requests.

Related Skills

Install with clawhub install <slug> if user confirms:

audio — audio processing and editing

ffmpeg — convert and manipulate audio files

video — combine music with video content

Feedback

If useful: clawhub star suno

Stay updated: clawhub sync

# Setup — Suno

Read this when `~/suno/` doesn't exist or is empty.

## Your Attitude

You're helping someone create music with AI. Your role is to craft great prompts and lyrics that will produce excellent results when they use Suno.

Focus on their creative vision. Keep technical details minimal.

## Priority Order

### 1. First: Understand What They Want

Start by understanding their music:
- "What kind of song are you thinking? Genre, mood?"
- "Do you have lyrics in mind, or should I write them?"
- "Any specific vocal style you prefer?"

### 2. Then: Craft and Deliver

Once you understand their vision:
1. Write an optimized prompt following the Core Rules
2. Write lyrics if they want custom mode
3. Give them ready-to-paste content for suno.com

### 3. Finally: Learn Their Preferences

As you work together, note:
- Genres they gravitate toward
- Vocal styles they like
- Prompts that produced great results

Save these to `~/suno/memory.md` for future sessions.

## What You're Saving

In `~/suno/memory.md`:
- Favorite genres and styles
- Vocal preferences
- Successful prompts that worked well
- Projects they mention

## Generation

Most users generate at suno.com/create directly. Your job is to give them:
- A well-crafted prompt (Simple mode)
- Or lyrics + style tags (Custom mode)

If they ask about APIs or automation, point them to `api-reference.md` which documents third-party options.

## When Done

Once you:
1. Understand their music taste
2. Have delivered a working prompt or lyrics
3. They've successfully generated a song

...you're set. Future sessions will be faster with preferences saved.

# Memory Template — Suno

Create `~/suno/memory.md` with this structure:

```markdown
# Suno Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending

## Music Preferences
<!-- Genres, artists, styles they gravitate toward -->
<!-- Add as you learn from conversations -->

## Vocal Preferences
<!-- Male/female, specific vocal styles they like -->
<!-- Any vocal characteristics they prefer -->

## Use Cases
<!-- What they typically create music for -->
<!-- Projects, videos, podcasts, personal, etc. -->

## Successful Prompts
<!-- Prompts that generated good results -->
<!-- Format: prompt -> result description -->

## Notes
<!-- Observations about their taste -->
<!-- Things that worked or didn't work -->

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Still learning their taste | Gather preferences through creation |
| `complete` | Know their style well | Apply preferences automatically |
| `paused` | User said "not now" | Don't ask, work with what you have |

## Generations Log (Optional)

For users who create frequently, create `~/suno/generations/` folder with:

```markdown
# Generation Log

## YYYY-MM-DD: [Title/Description]
- Prompt: "[full prompt used]"
- Style: [genre, mood]
- Result: [kept/discarded/extended]
- Notes: [what worked, what to improve]
```

## Key Principles

- Learn preferences through creation, not interrogation
- Remember what prompts worked well for reuse
- Note their reactions to different styles
- Track projects they mention for context
- Update `last` date on each session

# API Options — Suno

This document lists third-party services for programmatic Suno access. All require separate accounts and API keys from their respective providers.

## Overview

Suno doesn't have an official public API. These are third-party alternatives:

| Service | Type | Website |
|---------|------|---------|
| **AI Music API** | Hosted | aimusicapi.ai |
| **EvoLink** | Hosted | evolink.ai |
| **gcui-art/suno-api** | Self-hosted | github.com/gcui-art/suno-api |
| **SunoAI-API** | Self-hosted | github.com/SunoAI-API/Suno-API |

## Hosted Services

### AI Music API (aimusicapi.ai)
- Sign up and get API key from their dashboard
- Pay-per-use pricing
- Endpoints for generate, lyrics, extend

### EvoLink (evolink.ai)
- Sign up and get API key
- Supports Suno v4, v4.5, v5
- MCP tools available for agent integration

## Self-Hosted Options

For users who want full control, these GitHub projects let you run your own Suno proxy:

### gcui-art/suno-api
- Requires: Docker, Suno account cookie, 2Captcha account
- Deploy via Docker Compose or Vercel
- Handles CAPTCHA automatically

### SunoAI-API/Suno-API
- Requires: Python, Suno account cookie
- Simpler setup, FastAPI-based
- Manual CAPTCHA handling

## When to Use APIs

APIs are useful when:
- Building apps that need music generation
- Automating music creation workflows
- Integrating with other tools

For casual use, the Suno website (suno.com/create) is simpler and doesn't require any setup.

## API Call Pattern

Most Suno APIs follow this pattern:

1. **Generate** — Send prompt, receive task ID
2. **Poll** — Check task status every 5-10 seconds
3. **Retrieve** — Get audio URL when complete

Generation typically takes 30-90 seconds.

## Example (conceptual)

```
POST /api/generate
{
  "prompt": "indie rock song about city nights",
  "make_instrumental": false
}

Response: { "task_id": "abc123" }

GET /api/status?id=abc123

Response: { 
  "status": "completed",
  "audio_url": "https://..."
}
```

Specific endpoints vary by service — see each provider's documentation.