Music Genre Finder

Intelligent music genre search assistant based on RateYourMusic's database of 5947 music genres, supporting quick lookup, smart recommendations, and hierarchical exploration.

Data Structure Description

This skill uses hierarchical data in the

~/.claude/skills/music-genre-finder/references/

directory:

references/
├── _index.json          # Overview of 49 main categories (must-read, 13KB)
├── _meta.json           # Metadata and usage instructions (399B)
├── main/                # 49 files, direct subgenres of each main category
│   ├── ambient.json
│   ├── rock.json
│   └── ...
└── detailed/            # 578 files, details of subgenres with further subcategories
    ├── dark-ambient.json
    ├── shoegaze.json
    └── ...

Data Statistics:

Total genres: 5947
Main categories: 49 (Rock, Jazz, Ambient, Electronic, etc.)
Subgenres: 737 (level: sub)
Third-level and below categories: 5161 (sub-2/sub-3/sub-4)

Data fields for each genre:

json

{
  "name": "Dark Ambient",
  "url": "https://rateyourmusic.com/genre/dark-ambient/",
  "description": "Emphasizes an ominous, gloomy, and dissonant atmosphere.",
  "level": "sub",           // main, sub, sub-2, sub-3, sub-4
  "parent": "Ambient"       // Parent category name
}

Core Features

1. Quick Lookup (Exact Match)

User says: "Look up Shoegaze"

Execution Flow:

Step 1: Read _index.json to check if it's a main category
Step 2: If not, search in main/*.json using grep/find
Step 3: Once found, display genre information + link + subgenres (if any)

Sample Output:

🎵 Shoegaze
📝 Characterized by ethereal vocals buried beneath walls of distorted guitars...

🔗 https://rateyourmusic.com/genre/shoegaze/

📂 Belongs to: Alternative Rock > Noise Pop > Shoegaze

💡 Shoegaze has 3 subgenres:
  - Blackgaze (blends black metal elements)
  - Nu-Gaze (modern revival)
  - Dream Pop (softer variant)

2. Smart Recommendations (Semantic Match)

User says: "Recommend some styles suitable for late night, a bit ethereal"

Execution Flow:

Step 1: Read _index.json and scan descriptions of all 49 main categories
Step 2: Match with keywords (deep night, ethereal, ambient, atmospheric)
Step 3: After finding candidate main categories, read corresponding main/*.json files
Step 4: Further filter subgenres based on descriptions
Step 5: Return Top 3-5 recommendations with brief explanations

Keyword Mapping Table (built-in semantic rules):

User Description	Matching Keywords	Recommendation Direction
Late night, relaxation, meditation	ambient, atmospheric, calm, soothing	Ambient, Drone, Space Ambient
Energetic, intense	energetic, fast, aggressive, intense	Punk, Hardcore, Drum and Bass
Dark, depressive	dark, gloomy, ominous, dissonant	Dark Ambient, Black Metal, Industrial
Ethereal, dreamy	ethereal, dreamy, atmospheric, reverb	Dream Pop, Shoegaze, Ambient Pop
Electronic, tech-feeling	electronic, synthetic, futuristic, digital	Techno, IDM, Ambient Techno
Retro, nostalgic	vintage, retro, nostalgic, classic	Synthwave, Vaporwave, Chillwave
Experimental, avant-garde	experimental, avant-garde, unconventional	Noise, Free Jazz, Musique Concrète

Sample Output:

🌙 Based on "late night + ethereal", here are your recommended styles:

1. ⭐ Dark Ambient
   "Emphasizes an ominous, gloomy, and dissonant atmosphere"
   🔗 https://rateyourmusic.com/genre/dark-ambient/

2. ⭐ Space Ambient
   "Fluid and relaxing synth music, often centered around outer space imagery"
   🔗 https://rateyourmusic.com/genre/space-ambient/

3. ⭐ Drone
   "Sustained or repeated sounds, notes, or clusters, emphasizing timbre changes"
   🔗 https://rateyourmusic.com/genre/drone/

💡 Want to learn more about a style? Reply with its name.

3. Hierarchical Exploration (Tree View)

User says: "Show me what's under Ambient"

Execution Flow:

Step 1: Read main/ambient.json
Step 2: List all direct subgenres (level: sub)
Step 3: If the user further asks about a subgenre, read detailed/{subgenre}.json
Step 4: Display the complete hierarchical tree

Sample Output:

🎵 Subgenre tree for Ambient:

Ambient (Main Category)
├── Ambient Americana
│   └── Uses traditional American country instruments to create pastoral atmosphere
├── Dark Ambient ⭐
│   ├── Black Ambient (blends black metal elements)
│   ├── Ritual Ambient (ritualistic, mysterious)
│   └── ...
├── Space Ambient
│   └── Space-themed, synth-focused
└── Tribal Ambient
    └── Combines global traditional instruments and ambient elements

💡 Click on categories marked with ⭐ to expand more subgenres

4. Integration with Suno (Automated Flow)

When users want to generate music with Suno but haven't specified a style, this skill is triggered automatically:

User says: "Use Suno to generate a song for me"

Execution Flow:

Step 1: Ask users about the desired atmosphere/scenario (or directly recommend popular styles)
Step 2: Use the smart recommendation feature to provide 3-5 styles
Step 3: After user selects, pass the style name to suno-music-creator
Step 4: When Suno generates, include the style name in the tags parameter

Sample Dialogue:

User: Use Suno to generate a song for me
AI: Sure! What style do you want? I can recommend:
    1. Synthwave (retro electronic, 80s vibe)
    2. Lo-fi Hip Hop (relaxing background music for study)
    3. Shoegaze (ethereal, wall of guitar noise)
    Or tell me the atmosphere you want (e.g., energetic, suitable for late night, dark, etc.)

User: Energetic
AI: Recommendations: Drum and Bass, Hardcore Punk, Electro House
    Which one?

User: Drum and Bass
AI: [Calls suno-music-creator with tags including "drum and bass, energetic"]

Implementation Details

Loading Optimization Strategy

Principle: Progressive loading to minimize context consumption

Must-read Files:
- ```
_index.json
```
  (13KB) - Read in every query as an index
On-demand Loading:
- Exact lookup: Only read 1 main/.json or detailed/.json file
- Smart recommendation: Read _index.json + up to 3 candidate main/*.json files
- Hierarchical exploration: Expand layer by layer, only read next layer when user clicks
Context Budget:
- Single query usually consumes < 30KB (_index + 1-3 category files)
- Far less than the original 1.7MB full dataset

Search Algorithm

Exact Match:

bash

# First search in main categories
jq '.genres[] | select(.name == "Ambient")' _index.json

# If not found, search in all main/*.json files
grep -l "\"name\": \"Shoegaze\"" main/*.json

# Then search in detailed/*.json files
grep -l "\"name\": \"Blackgaze\"" detailed/*.json

Fuzzy Match (when user description is imprecise):

bash

# Keyword match in descriptions
jq '.genres[] | select(.description | test("dark|ominous|gloomy"; "i"))' _index.json

Output Format Specification

Unified Template:

🎵 {Genre Name}
📝 {Description}
🔗 {RateYourMusic Link}
📂 {Hierarchical Path} (if not a main category)
💡 {Additional Information} (e.g., number of subgenres, recommendation reason, etc.)

Usage Examples

Example 1: Quick Lookup

User: Look up Vaporwave
AI: 🎵 Vaporwave
    📝 Nostalgic, surrealist take on elevator music, sampling 1980s-90s muzak,
        smooth jazz, and lounge music, often with a chopped and screwed aesthetic.
    🔗 https://rateyourmusic.com/genre/vaporwave/
    📂 Electronic > Vaporwave

    💡 Vaporwave has 5 subgenres:
      - Hardvapour (more aggressive variant)
      - Mallsoft (mall environment music)
      - Future Funk (blends Funk elements)
      - Eccojams (looping and distortion)
      - Signalwave (broadcast signal aesthetics)

Example 2: Smart Recommendation

User: Recommend some music styles suitable for coding
AI: 🖥️ Based on the "coding" scenario, here are recommended styles (non-distracting + rhythmic):

    1. ⭐ Lo-fi Hip Hop
       "Relaxing hip-hop beats + jazz samples, top choice for focused study/work"

    2. ⭐ Ambient Techno
       "Electronic atmosphere + steady rhythm, neither boring nor distracting"

    3. ⭐ Post-Rock
       "Instrumental-focused, progressive development, suitable for long-term focus"

    4. ⭐ Downtempo
       "Slow-tempo electronic, calm but not hypnotic"

    💡 Want to learn more? Reply with the style name or number.

Example 3: Hierarchical Exploration

User: What major categories are under Electronic?
AI: 🎵 Main subgenres of Electronic:

    📂 Electronic (Main Category)
    ├── 🎛️ Ambient (Ambient Electronic)
    ├── 💃 Dance (Dance Music)
    │   ├── House
    │   ├── Techno
    │   ├── Trance
    │   └── Drum and Bass
    ├── 🧠 IDM (Intelligent Dance Music, Experimental Electronic)
    ├── 🌊 Downtempo (Slow-tempo)
    ├── 🔊 Bass Music (Bass-focused)
    └── 🎹 Synthwave (Synthwave)

    There are 37 total subgenres, these are the most popular ones.

    💡 Want to dive into a category? Tell me its name.

Error Handling

When Genre is Not Found

User: Look up Qiaomu Style
AI: ❌ "Qiaomu Style" was not found.

    💡 Possible reasons:
    - Spelling mistake in the genre name? Try similar ones: Shoegaze, Noise Pop
    - This genre doesn't exist in the RateYourMusic database

    🔍 You can:
    1. Describe the characteristics of this style, and I'll help you find similar ones
    2. Visit https://rateyourmusic.com/genres/ directly to browse the full list

When Description is Too Vague

User: Recommend some good music styles
AI: 🤔 "Good" is subjective! Can you be more specific?

    For example:
    - Scenario: suitable for late night/exercise/work/driving
    - Atmosphere: relaxing/intense/dark/cheerful
    - Instruments: guitar-focused/electronic/orchestral
    - Reference: similar to XX band/artist

    Or can I recommend some general popular styles?

Data Maintenance

Update Data

If RateYourMusic website updates, re-scrape the data:

bash

# Re-run the scraping script (using playwright)
python scrape_rateyourmusic.py

# Re-split the data
python split_genres.py

Add Custom Tags

You can add a

custom_tags

field in

_meta.json

for more precise recommendations:

json

{
  "custom_tags": {
    "coding": ["Lo-fi Hip Hop", "Ambient Techno", "Post-Rock"],
    "workout": ["Drum and Bass", "Hardcore Punk", "Trap"],
    "sleep": ["Dark Ambient", "Drone", "Field Recordings"]
  }
}

Technical Specifications

File Reading Priority

Prefer using the
```
Read
```
tool (fast, direct)
Use the
```
Grep
```
tool when search is needed
Avoid using
```
Bash
```
cat/grep (Read and Grep are more efficient)

JSON Parsing

Use
```
jq
```
for complex queries (e.g., filtering, sorting)
Use Python scripts for batch processing or complex logic

Link Handling

All RateYourMusic links in output must be complete and clickable

Format:

🔗 https://rateyourmusic.com/genre/{genre-slug}/

Collaboration with Other Skills

Integration with suno-music-creator

music-genre-finder → Recommend style → suno-music-creator generates music

Workflow:

User says "Use Suno to generate a song"
music-genre-finder recommends styles (e.g., "Synthwave")
After user confirms, call suno-music-creator with the style name included in tags
Suno generates music that matches the style

Integration with qiaomu-writer

music-genre-finder → Look up style → qiaomu-writer writes style interpretation article

Sample:

User: "Write an article about Shoegaze"
music-genre-finder provides detailed information about Shoegaze (description, history, subgenres)
qiaomu-writer generates an article in Qiaomu style based on this information

Best Practices

DO ✅

Always read
```
_index.json
```
first to build an index
Load progressively based on user needs (don't read too many files at once)
Include RateYourMusic links in output to help users learn more
Use emojis to make output more intuitive (🎵 🔗 📂 💡)
Provide 3-5 options for recommendations (avoid overwhelming users)

DON'T ❌

Don't read all main/.json and detailed/.json files at once (wastes context)
Don't assume users know professional jargon (use simple descriptions + links)
Don't only return a list of genre names (include descriptions and recommendation reasons)
Don't ignore users' implicit needs (e.g., "generate with Suno" implicitly requires style recommendation)

Changelog

v1.1 (2026-01-31)

Standardized skill structure: Added YAML frontmatter
Renamed data/ → references/ (complies with skill best practices)
Optimized description field and integrated trigger conditions

v1.0 (2026-01-31)

Initial release
Supports lookup, recommendation, and exploration of 5947 music genres
Based on RateYourMusic data from 2026-01-31
Three-layer data structure (_index.json, main/, detailed/)
Integrated with suno-music-creator

Author

Created by Qiaobangzhu with Claude Code Data source: https://rateyourmusic.com/genres/

music-genre-finder

NPX Install

Tags

SKILL.md Content (Chinese)

Music Genre Finder

Data Structure Description

Core Features

1. Quick Lookup (Exact Match)

2. Smart Recommendations (Semantic Match)

3. Hierarchical Exploration (Tree View)

4. Integration with Suno (Automated Flow)

Implementation Details

Loading Optimization Strategy

Search Algorithm

Output Format Specification

Usage Examples

Example 1: Quick Lookup

Example 2: Smart Recommendation

Example 3: Hierarchical Exploration

Error Handling

When Genre is Not Found

When Description is Too Vague

Data Maintenance

Update Data

Add Custom Tags

Technical Specifications

File Reading Priority

JSON Parsing

Link Handling

Collaboration with Other Skills

Integration with suno-music-creator

Integration with qiaomu-writer

Best Practices

DO ✅

DON'T ❌

Changelog

v1.1 (2026-01-31)

v1.0 (2026-01-31)

Author