How do I install the Music Assistant skill?

Run npx skillmds@latest add diegosouzapw/music-assistant in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Music Assistant safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Music Assistant?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Music Assistant free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Music Assistant?

diegosouzapw (@diegosouzapw) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Music Assistant by diegosouzapw — Agent Skill

Name: Music Assistant
Rating: 4.2 (5 reviews)
Author: diegosouzapw

File contents

Music Assistant Skill

Control Home Assistant with Music Assistant integration - browse your music library, search for tracks, manage playback, set preferences, and create mood-based playlists.

Requirements

Home Assistant instance with Music Assistant integration
HA_URL - Your Home Assistant URL (e.g., https://ha.example.com)
HA_TOKEN - Long-lived access token from Home Assistant

Commands

Speakers & Discovery

# List available media player speakers
ha-ma speakers

# Show Music Assistant configuration
ha-ma ma-config [--cached] [--refresh]

Browse Library

# Browse by type: artists, albums, tracks, playlists, radio
ha-ma browse <type> [--parent <id>] [--limit <n>] [--offset <n>]

# Examples
ha-ma browse artists --limit 20
ha-ma browse albums --parent "artist:123"
ha-ma browse tracks --parent "album:456"

Search

# Search for music
ha-ma search <query> [--limit <n>] [--type <media_type>]

# Examples
ha-ma search "Beatles" --limit 10
ha-ma search "jazz" --type artists

Playback Control

# Play media on a speaker
ha-ma play --speaker <entity_id> --uri <uri> [--enqueue <mode>]

# Pause/Stop/Navigation
ha-ma pause --speaker <entity_id>
ha-ma stop --speaker <entity_id>
ha-ma next --speaker <entity_id>
ha-ma prev --speaker <entity_id>

# Volume control (0-100)
ha-ma volume --speaker <entity_id> --level <0-100>

# Add to queue
ha-ma queue --speaker <entity_id> --uri <uri>

Enqueue modes: play, replace, next, add

User Preferences

# Set preference for user or household
ha-ma prefs set --user <slug> --<entity-type> <value> --score <score>
ha-ma prefs set --household <slug> --<entity-type> <value> --score <score>

# Get preferences
ha-ma prefs get --user <slug>
ha-ma prefs get --household <slug>

# Clear specific preference
ha-ma prefs clear --user <slug> --<entity-type> <value>
ha-ma prefs clear --household <slug> --<entity-type> <value>

Entity types: --artist, --album, --genre, --track

Mood Mapping

# Create or update a mood
ha-ma mood set --user <slug> --name <name> --genres <g1,g2> [--decades <d1,d2>] [--energy <low|medium|high>]
ha-ma mood set --household <slug> --name <name> --genres <g1,g2> [--energy <level>]

# List moods
ha-ma mood list --user <slug>
ha-ma mood list --household <slug>

# Get specific mood
ha-ma mood get --user <slug> --name <name>

# Delete mood
ha-ma mood delete --user <slug> --name <name>

Play History

# Recent play history
ha-ma history recent --user <slug> [--limit 20]

# List listening sessions
ha-ma history sessions --user <slug> [--limit 10]

# Avoid list management
ha-ma history avoid --user <slug> --uri <uri> [--reason <text>]
ha-ma history unavoid --user <slug> --uri <uri>
ha-ma history avoidlist --user <slug>

Memory (Play Event Logging)

# Log a play event
ha-ma memory log --user <slug> --speaker-entity <entity_id> --uri <uri> [--title ...] [--artist ...] [--album ...]

# Recent play events
ha-ma memory recent --user <slug> [--limit 10]

Configuration

Set environment variables in your OpenClaw config:

{
  "skills": {
    "entries": {
      "music-assistant": {
        "env": {
          "HA_URL": "https://your-ha-instance.com",
          "HA_TOKEN": "your-long-lived-access-token"
        }
      }
    }
  }
}

Database

The skill uses SQLite with Prisma for storing:

User and household preferences
Mood definitions
Play history and sessions
Avoid lists

Database is automatically initialized on first use.

---name: music-assistantdescription: Control Home Assistant Music Assistant - browse library, search, play, manage preferences and moods.---# Music Assistant SkillControl Home Assistant with Music Assistant integration - browse your music library, search for tracks, manage playback, set preferences, and create mood-based playlists.## Requirements- Home Assistant instance with [Music Assistant](https://music-assistant.io/) integration- `HA_URL` - Your Home Assistant URL (e.g., `https://ha.example.com`)- `HA_TOKEN` - Long-lived access token from Home Assistant## Commands### Speakers & Discovery```bash# List available media player speakersha-ma speakers# Show Music Assistant configurationha-ma ma-config [--cached] [--refresh]```### Browse Library```bash# Browse by type: artists, albums, tracks, playlists, radioha-ma browse <type> [--parent <id>] [--limit <n>] [--offset <n>]# Examplesha-ma browse artists --limit 20ha-ma browse albums --parent "artist:123"ha-ma browse tracks --parent "album:456"```### Search```bash# Search for musicha-ma search <query> [--limit <n>] [--type <media_type>]# Examplesha-ma search "Beatles" --limit 10ha-ma search "jazz" --type artists```### Playback Control```bash# Play media on a speakerha-ma play --speaker <entity_id> --uri <uri> [--enqueue <mode>]# Pause/Stop/Navigationha-ma pause --speaker <entity_id>ha-ma stop --speaker <entity_id>ha-ma next --speaker <entity_id>ha-ma prev --speaker <entity_id># Volume control (0-100)ha-ma volume --speaker <entity_id> --level <0-100># Add to queueha-ma queue --speaker <entity_id> --uri <uri>```Enqueue modes: `play`, `replace`, `next`, `add`### User Preferences```bash# Set preference for user or householdha-ma prefs set --user <slug> --<entity-type> <value> --score <score>ha-ma prefs set --household <slug> --<entity-type> <value> --score <score># Get preferencesha-ma prefs get --user <slug>ha-ma prefs get --household <slug># Clear specific preferenceha-ma prefs clear --user <slug> --<entity-type> <value>ha-ma prefs clear --household <slug> --<entity-type> <value>```Entity types: `--artist`, `--album`, `--genre`, `--track`### Mood Mapping```bash# Create or update a moodha-ma mood set --user <slug> --name <name> --genres <g1,g2> [--decades <d1,d2>] [--energy <low|medium|high>]ha-ma mood set --household <slug> --name <name> --genres <g1,g2> [--energy <level>]# List moodsha-ma mood list --user <slug>ha-ma mood list --household <slug># Get specific moodha-ma mood get --user <slug> --name <name># Delete moodha-ma mood delete --user <slug> --name <name>```### Play History```bash# Recent play historyha-ma history recent --user <slug> [--limit 20]# List listening sessionsha-ma history sessions --user <slug> [--limit 10]# Avoid list managementha-ma history avoid --user <slug> --uri <uri> [--reason <text>]ha-ma history unavoid --user <slug> --uri <uri>ha-ma history avoidlist --user <slug>```### Memory (Play Event Logging)```bash# Log a play eventha-ma memory log --user <slug> --speaker-entity <entity_id> --uri <uri> [--title ...] [--artist ...] [--album ...]# Recent play eventsha-ma memory recent --user <slug> [--limit 10]```## ConfigurationSet environment variables in your OpenClaw config:```json{ "skills": { "entries": { "music-assistant": { "env": { "HA_URL": "https://your-ha-instance.com", "HA_TOKEN": "your-long-lived-access-token" } } } }}```## DatabaseThe skill uses SQLite with Prisma for storing:- User and household preferences- Mood definitions- Play history and sessions- Avoid listsDatabase is automatically initialized on first use.

Frequently asked questions

Music Assistant