---
name: igapyon-miku-score
description: Use only when the user explicitly says `igapyon-miku-score`, `miku-score`, or `miku-score-skills`, or uses the documented compatibility triggers `mikuscore` or `mikuscore-skills` for miku-score-specific score conversion, diagnostics, AI handoff, or CLI workflows. Do not auto-activate for generic music theory, generic MIDI editing, or general notation discussion.
---

# Miku Score

Use this skill for `miku-score`-specific score conversion, rendering, diagnostics, AI handoff, and workflow guidance.
Treat `miku-score` as a conversion engine with a product contract, not as a generic notation discussion mode.

The stable framing is:

- canonical score source remains `MusicXML`
- current generative-AI full-score handoff and new-score generation use `ABC`
- the documented `ABC` baseline is `ABC standard 2.2`
- some `ABC` standard features remain partially implemented or unimplemented

## Activation

`igapyon-miku-score` is opt-in by default.
Do not trigger from format names alone.

Formal triggers are `igapyon-miku-score`, `miku-score`, and `miku-score-skills`.
Compatibility triggers are `mikuscore` and `mikuscore-skills`; they invoke this
same skill identity and do not require a legacy skill directory.

Start `igapyon-miku-score` mode when at least one of these is true:

- the user explicitly names a formal or compatibility trigger
- the user clearly asks for `miku-score`-specific behavior such as its `MusicXML-first` policy, `ABC` AI handoff policy, diagnostics model, or CLI workflow
- the recent conversation is already inside an active `miku-score` workflow started from an explicit trigger

Without one of these triggers, do not force `miku-score` just because the request mentions `MusicXML`, `ABC`, `MIDI`, `MuseScore`, `MEI`, `LilyPond`, `VSQX`, `xml`, or score conversion.
In that case, answer normally or ask a brief clarifying question.

## Core Stance

- prefer agent-internal execution over visible handoff whenever the runtime can continue internally
- keep intermediate score artifacts off-screen unless the user explicitly asks to inspect them
- once an active `miku-score` workflow has started, keep follow-up work inside `miku-score` terms when that remains the natural continuation
- use the vendored `miku-score` CLI or documented runtime flow before falling back to ad-hoc rewrites, one-off converters, or generic music-tool advice
- move from route selection to execution quickly on straightforward file-producing requests
- present generated outputs first and keep process narration short

## Product Contract

- preserve `miku-score`'s split framing in explanations: canonical `MusicXML` internally, `ABC` for the current AI-facing full-score boundary
- prefer `MusicXML` as the canonical explanation axis across format pairs
- prefer `ABC` when the question is specifically about current AI-facing score exchange
- explain limitations as diagnostics, coverage gaps, or format-scope constraints
- distinguish `supported`, `experimental`, `future`, and `non-goal` areas explicitly
- when docs conflict, prefer `vendor/miku-score/docs/spec/*` over README-level summaries
- do not describe `miku-score` as a feature-complete score engraving editor
- do not imply structural repairs or guarantees that the current specs do not define

## Operations

Prefer the reusable upstream CLI and documented runtime flow exposed by the vendored `miku-score`.
Use those before direct file reads, hand-written rewrites, or UI-oriented flows.

Primary workflow categories:

- `convert`: execute or explain source-to-target conversion in `miku-score` terms
- `render`: produce user-facing render outputs such as `SVG`
- `diagnostics`: explain warnings, errors, preservation, and conversion loss
- `format-guidance`: explain how a format is positioned inside the current product contract
- `ai-handoff`: explain why current generative-AI full-score handoff uses `ABC`
- `workflow`: explain CLI, build, test, bundle, and local verification usage

## Runtime Discipline

For explicit `miku-score` convert/render requests, first attempt the vendored CLI or documented vendored runtime flow before broad repository exploration or generic tool discovery.

Use this order:

1. read this `SKILL.md` and, when a file inventory is useful, `index.json`
2. check the vendored `miku-score` runtime first
3. use the vendored CLI or documented runtime flow immediately if present
4. only if that path is missing or unusable, search for alternatives

For this repository:

- in the development repo, prefer `vendor/miku-score`
- in bundled installs, prefer the skill-local `vendor/miku-score`
- do not search broadly through the workspace before checking the vendored runtime
- do not conclude that runtime dependencies are missing until the bundled skill-local runtime path has also been checked

The vendored tree is a documented transition runtime. Do not add further runtime lookup paths or skill-local conversion logic around it. When upstream provides `runtime/miku-score.mjs` or `runtime/miku-score.jar`, use those declared artifacts according to the updated runtime reference.

## Conversion Discipline

- identify `source` and `target` first
- current documented CLI pairs include `ABC <-> MusicXML`, `ABC -> MIDI`, `MIDI -> MusicXML`, `MusicXML <-> MEI`, `MusicXML <-> LilyPond`, and `MusicXML <-> MuseScore`
- keep `MEI` and `LilyPond` marked as experimental when explaining them
- explain or execute routes through `MusicXML` when that matches the documented product model
- resolve short follow-up format requests such as `svg`, `musicxml`, `abc`, `midi`, `mei`, `lilypond`, or `mscx` as `miku-score` conversion or render requests when that is the natural continuation of the active workflow
- when the user wants `SVG` from an `ABC`-friendly request, prefer `ABC -> MusicXML -> SVG` unless a better direct path is clearly documented
- do not show raw intermediate `ABC` or `MusicXML` unless the user explicitly asks to inspect them or the runtime path has failed
- do not turn a normal conversion request into a runtime-inspection task unless the actual conversion path has failed

## Output Discipline

Unless the user asks for another location, use a workspace-local `miku-score/` tree:

- state-like or handoff artifacts -> `miku-score/state/`
- final deliverables -> `miku-score/output/`
- temporary files -> `miku-score/tmp/`

For file-producing conversions:

- report the primary generated file first
- mention intermediate files only after the primary output
- use repo-relative paths or clickable file links, not bare filenames
- include a one-line route or command summary
- include one concrete verification fact if you claim success
- do not surface `/tmp/...` paths unless they are the user-facing output

Preferred close-out shape:

1. primary generated file path
2. optional intermediate file path(s)
3. one-line route summary such as `ABC -> MusicXML -> SVG`
4. one concrete verification fact
5. optional next adjustment

## Error Model

Treat these as hard errors:

- unknown or ambiguous `source` / `target` when the workflow depends on that distinction
- unsupported format-pair claims
- claims that conflict with normative specs under `vendor/miku-score/docs/spec/*`
- unsupported or out-of-scope behavior presented as if it were implemented

Treat these as soft warnings:

- round-trip loss risk
- experimental-format caveats
- CLI scope caveats such as `.mscx` vs compressed `.mscz`
- metadata or diagnostics notes that expose lossy conversion boundaries

On soft warnings, continue and report them concisely.

## Boundaries

- do not pretend `miku-score` replaces a full notation editor
- do not claim textual XML identity guarantees that the specs reject
- do not claim unsupported or future format flows are already stable
- do not collapse a `miku-score` workflow question into generic music software advice when `miku-score`-specific guidance is needed

## References

Read these only when needed:

- [references/INDEX.md](references/INDEX.md) for workflow, runtime, output, and example references
- [index.json](index.json) for the generated file inventory of this skill package