Guides the addition of features to the MusicXML API library, ensuring lean design and correct layer wiring.
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.zipInstalls 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".Key capabilities
- →Identify MusicXML elements and attributes not yet exposed in the API
- →Confirm `mx::core` models the target elements
- →Decide the minimal API surface for a feature
- →Add or update enums and plain-old-data types in `mx::api`
- →Wire new data types to the DOM through the `mx::impl` reader/writer layer
- →Run unit and corpus roundtrip tests to verify changes
How it works
The skill guides the user through understanding the feature, adding it to the `mx::api` data model, wiring it through the `mx::impl` translation layer, and running tests.
Inputs & outputs
When to use mx-api-add-feature
- →Adding support for a new MusicXML element
- →Exposing library features to the API
- →Extending the MusicXML object model
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.
Architecture: three layers
A feature flows through three layers. Know which one you are touching:
mx::core-- generated XSD model; almost always already has your element. Do NOT editgen/.mx::impl-- translation layer:*Readercore -> api,*Writerapi -> core. See Step 3.mx::api(src/include/mx/api/) -- the public data model 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:
- Identify the exact MusicXML element and/or attributes in play. Confirm they are NOT already
exposed in
src/include/mx/api/(grep the*Data.hheaders). - Confirm
mx::corealready models them (grepsrc/private/mx/core/generated/). It almost always does. If it genuinely does not, stop and tell the user -- that is agen//core change, out of scope for this skill. - 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. - Read the
mx-api-doctrineskill (required): which MusicXML defect (stateful / flat / duplicated / id-linked / order-dependent) does the element carry, and which principle applies? Never mirror the element's raw shape.
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 api-test for the unit suites and make api-roundtrip for the corpus roundtrip gate
(Step 1 explains both, along with make api-roundtrip-discover). Verify everything passes. Then run
make fmt and make fmt-check so the CI quality gates will pass.
(optional) Step 5: Open a PR
If the user asks for a PR, use the mx-open-pr skill.
When not to use it
- →When the feature is already exposed in `mx::api`
- →When the feature is not modeled in `mx::core`
- →When the goal is to add every element or attribute without curation
Limitations
- →It does not handle changes to the `gen/`/`mx::core` layer
- →It focuses on adding features to the API, not general library development
- →It requires understanding of the `mx-api-doctrine` skill
How it compares
This skill provides a structured, layered approach to extending the `mx` library's public interface, ensuring minimal bloat and proper integration, unlike directly modifying the generated core model.
Compared to similar skills
mx-api-add-feature side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| mx-api-add-feature (this skill) | 0 | 1mo | No flags | Advanced |
| arm-cortex-expert | 29 | 4mo | No flags | Advanced |
| game-engine-resources | 14 | 3mo | No flags | Advanced |
| pc-games | 5 | 6mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
arm-cortex-expert
sickn33
Senior embedded software engineer specializing in firmware and driver development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD). Decades of experience writing reliable, optimized, and maintainable embedded code with deep expertise in memory barriers, DMA/cache coherency, interrupt-driven I/O, and peripheral drivers.
game-engine-resources
gmh5225
Guide for game engine development resources including engine source code, plugins, and development guides. Use this skill when researching game engines (Unreal, Unity, Godot, custom engines), engine architecture, or game development frameworks.
pc-games
davila7
PC and console game development principles. Engine selection, platform features, optimization strategies.
mlir-development
gmh5225
Expertise in MLIR (Multi-Level Intermediate Representation) and CIR (Clang IR) development for domain-specific compilation and high-level optimizations. Use this skill when building ML compilers, domain-specific languages, or working with multi-level compilation pipelines.
port-c-module
RediSearch
Guide for porting a C module to Rust
compiler-development
gmh5225
Expertise in compiler development using LLVM infrastructure including frontend design, IR generation, optimization passes, and code generation. Use this skill when building custom programming languages, implementing DSL compilers, or working on compiler internals.