Guide · Agent skill
How to use the MuseScore Notation CLI agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to install the MuseScore agent skill, which teaches an AI agent to run MuseScore 4 through its command-line interface, and how to ask for transposition, part extraction, instrument changes and exports in plain language. It is written for readers who have not used agent skills before. By the end you will know what the skill needs, how to add it to Claude, and how to check that it is working.
MuseScore Notation CLIHKUDS/CLI-Anything · Apache-2.0 Download the skill Quick start
- 1Install MuseScore 4. Install MuseScore 4 from musescore.org. The skill cannot run without it.
- 2Install the command-line tool. Make sure the cli-anything-musescore tool is available to the agent. The skill page does not give install steps for it, so check the HKUDS/CLI-Anything project it comes from.
- 3Download and unzip the skill. Download the skill ZIP from this page and unzip it so you have a musescore folder containing SKILL.md.
- 4Place the folder or upload it. Copy the musescore folder into ~/.claude/skills/ or a project's .claude/skills/, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 5Ask for a task. Describe the result and name your score file, such as transposing it to a new key or exporting a PDF.
- 6Check the output. Open the new file or ask the agent to verify the export, and use session undo if the change is wrong.
What the MuseScore skill lets an agent do
An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task with a tool. This skill covers music notation work in MuseScore 4. It wraps MuseScore's mscore backend and exposes it through the cli-anything-musescore command.
The skill covers transposition to a target key, by a number of semitones, or diatonically. It can extract individual parts, add or remove instruments, and export scores as PDF, PNG, MP3, MIDI, MusicXML or Braille. It can also inspect a score, compare two versions, and undo or redo changes in a session.
Before you install: requirements
The skill needs MuseScore 4 installed, available from musescore.org. It also needs the cli-anything-musescore command-line tool, which the skill calls as its entry point. The skill does not work on its own because it depends on MuseScore 4's mscore backend.
The skill accepts .mscz (MuseScore native), .mxl (compressed MusicXML), .musicxml or .xml, and .mid or .midi files.
- MuseScore 4 installed
- cli-anything-musescore command-line tool available to the agent
- A score in one of the supported input formats
Install the MuseScore skill
Download the skill ZIP from this page and unzip it. Put the resulting musescore folder in one of these locations, depending on how you want to use it.
For a personal setup available to all your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/musescore
- Project only: .claude/skills/musescore inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Ask for what you need in plain language
You do not need to type commands yourself. Describe the result you want and name the score file. The agent reads the skill and chooses the matching command. Mention the file name, the target and the output you expect, so the agent knows which -i input and -o output to create.
Transposition always writes a new file, so your original score is kept. For example, you might ask the agent to transpose a clarinet score up a semitone or move a piece to D major. Say which file to produce and where.
- Transpose: 'Transpose score.mscz to D major and save it as score_d.mscz.'
- Parts: 'Extract the Piano part from score.mscz into piano.mscz.'
- Export: 'Export score.mscz as a PDF at 300 dpi.'
Commands the skill uses
Behind the scenes the agent runs commands like the ones below. The skill's guidance asks the agent to always add --json for machine-readable output. You can read these to understand what happened, but you do not need to run them yourself.
Transposition needs both -i (input) and -o (output). Key names accept forms such as 'C', 'C major', 'Am', 'A minor', 'Db major' and 'F# minor'.
cli-anything-musescore --json transpose by-key -i score.mscz -o out.mscz --target-key "C major" --direction closest
cli-anything-musescore --json transpose by-interval -i score.mscz -o out.mscz --semitones 3
cli-anything-musescore --json parts extract -i score.mscz -o piano.mscz --part "Piano"
cli-anything-musescore --json export pdf -i score.mscz -o score.pdfSafety notes: scripts and network
The skill runs scripts, because it executes the cli-anything-musescore command and the MuseScore backend on your machine. It does not use the network. Review the skill files before installing if you are working with sensitive material, and check which folder the agent is writing to.
The skill's guidance says to use media probe to inspect an unknown score before operating on it, and to verify exports with export verify after rendering. Use session undo if a change is not what you wanted.
- Runs scripts: yes, so install only skills you trust
- Uses network: no, according to the skill's listing
- Transposition writes to the output file you name, so keep the original score separate
Tips for reliable results
Name an output file every time you transpose or extract, so you never overwrite the source. Ask the agent to probe the score first if the file is unfamiliar. Part names are case-insensitive for parts extract, so 'piano' and 'Piano' both work.
If you need a batch of outputs from one score, ask for several exports at once. The skill includes an export batch command that takes multiple -o outputs. Check the output folder afterwards.
- Use one output file per change
- Run media probe on unfamiliar scores
- Use session history to review what changed in this session
What people use it for
- Transposing a vocal or wind part into a key that suits a different singer or instrument
- Pulling individual instrument parts out of a full score for rehearsal or an ensemble library
- Exporting a score as PDF or PNG for printing, and as MP3 or MIDI for listening
- Converting a score to MusicXML or Braille for another program or a reader
- Comparing two versions of a score with media diff to see what changed
Frequently asked questions
Is the MuseScore agent skill free?
The skill's listed licence is Apache-2.0, and it is published in the HKUDS/CLI-Anything repository. This page does not state the cost or licence of MuseScore 4 itself, so check musescore.org for its terms.
What do I need to use the MuseScore skill?
You need MuseScore 4 installed and the cli-anything-musescore command-line tool. The skill wraps MuseScore's mscore backend, so it will not work without MuseScore 4.
Where do I install an agent skill for Claude?
Unzip the skill and place the musescore folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills.
Can this skill compose music or generate audio?
No. The skill edits and exports existing scores. It transposes, extracts parts, changes instruments and exports files, but it does not create new music.
Which file types can it read?
It accepts .mscz, .mxl, .musicxml, .xml, .mid and .midi files. It can export to PDF, PNG, MP3, MIDI, MusicXML and Braille.
Why does the skill fail or do nothing?
Check that MuseScore 4 is installed and that cli-anything-musescore is available to the agent, since the skill depends on both. Confirm your score is in a supported format and that you named both an input and an output file for transposition.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits musicians, arrangers and music teachers who regularly transpose scores, extract parts or export files from MuseScore 4, and developers building export pipelines around it. Skip it if you do not have MuseScore 4, or if you want an AI to compose or generate audio, since it only edits and exports existing scores.
Download the skill