agentskills.codes
MX

mx-api-add-feature

by webernSource

>

Install

mkdir -p .claude/skills/mx-api-add-feature && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/13206" && unzip -o skill.zip -d .claude/skills/mx-api-add-feature && rm skill.zip

Installs to .claude/skills/mx-api-add-feature

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Use this skill when the user wants to add a MusicXML feature to the `mx::api` layer. This skill provides a step-by-step guide to add something to mx::api and wire it up through mx::impl. It may also help answer the question "how do I use {{xyz}} feature of MusicXML". If the feature is not yet included in the api layer then it may be necessary to open a PR adding support. This skill is also useful when implementing PRs with names like "Add support for segno" or "Repeats are inaccessible".
492 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)

About this skill

Add mx::api Feature

The mx::api namespace is the public interface of the mx library: a deliberate subset of MusicXML expressed in a simple object model that is easier to work with than the MusicXML DOM. Because it is a subset, a frequent user request is "add X".

Architecture: three layers

A feature flows through three layers. Know which one you are touching:

  • mx::core (src/private/mx/core/generated/) -- the strongly-typed MusicXML XSD model, generated from the schema by gen/. The element/attribute you are adding almost always ALREADY EXISTS here, fully parseable. Do NOT regenerate core or edit gen/ for a normal feature.
  • mx::impl (src/private/mx/impl/) -- the translation layer. *Reader classes turn core into api; *Writer classes turn api into core. See Step 3.
  • mx::api (src/include/mx/api/) -- the public data model (ScoreData, PartData, MeasureData, NoteData, DirectionData, ...). This is the surface you expose the feature on. See Step 2.

So a typical feature is two-sided work in mx::api + mx::impl only; mx::core already has it.

Read AGENTS.md (repo root) for the layout and the "Key files to understand" table before you start.

Understand the Feature

Do not blindly add every element or attribute. Keep the api lean and easy to use -- obscure things (for example, per-note color) just bloat the surface. In a targeted way, add what the user actually needs and nothing extra. Before writing any code:

  1. Identify the exact MusicXML element and/or attributes in play. Confirm they are NOT already exposed in src/include/mx/api/ (grep the *Data.h headers).
  2. Confirm mx::core already models them (grep src/private/mx/core/generated/). It almost always does. If it genuinely does not, stop and tell the user -- that is a gen//core change, out of scope for this skill.
  3. Decide the minimal api surface and which existing aggregate the feature belongs in (for example, a direction-like marking joins the measure's directions; a note-attached marking joins NoteData). Step 2 covers these patterns.

Step 1: Test Strategy

First, determine how it will be tested. See ./steps/step-1-test-strategy.md

Step 2: mx::api Data Model

Add (or update) the enums and plain-old-data types in mx::api, matching existing patterns. See ./steps/step-2-mx-api-data-model.md

Step 3: mx::impl Algorithms

Wire the new data types to the DOM through the mx::impl reader/writer layer, keeping the read and write paths symmetric. See ./steps/step-3-mx-impl.md

Step 4: Run tests

Run make test for the unit suites and make test-api-roundtrip for the corpus roundtrip gate (Step 1 explains both, along with make discover-api-roundtrip). Verify everything passes. Then run make fmt and make check so the CI quality gates will pass.

(optional) Step 5: Open a PR

If the user asks you to open a PR, see ./resources/pr-template.md

Search skills

Search the agent skills registry