English日本語
Definition version 2026-11-19

The musubi definition

Definition version 2026-11-19.

musubi binds the content one agent skill provides, such as a document format or writing rules, to the skills that follow it. A skill declares that content under a name and a version, another skill declares that it follows it, agents load it the same way in every agent that reads SKILL.md, and the skills that follow it are checked again when it changes. This English text is the normative definition; musubi.ja.md is its Japanese translation.

Overview

A skill that takes part keeps its SKILL.md as Agent Skills defines it and adds one file, musubi.json, next to it.

FileWritten byHolds
SKILL.mdThe skill's authorThe Agent Skills frontmatter and body, unchanged. The body tells agents which content to read
musubi.jsonThe author, or musubi addThe content the skill provides and the content it follows
A content fileThe providerA format, writing rules, or any other text that consumers follow
A check fileThe providerJSON rules that musubi check applies to the consumers' examples
skills/
├── design-doc/              provider skill
│   ├── SKILL.md             names the file of each content it provides
│   ├── musubi.json          "provides": design 1.0.0
│   ├── formats/design.md    the content
│   └── checks/design.json   the check rules
└── api-design/              consumer skill
    ├── SKILL.md             three lines that point at design-doc/design
    ├── musubi.json          "follows": design-doc/design ^1.0.0 and its fingerprint
    └── examples/orders-api.md   an example the check is applied to

GLOSSARY.md defines the terms used here.

Provider declaration

A provider skill lists its content under provides in musubi.json.

{
  "$schema": "../../../schema/2026-11-19/musubi.schema.json",
  "musubi": "2026-11-19",
  "provides": {
    "design": { "version": "1.0.0", "file": "formats/design.md", "check": "checks/design.json" }
  }
}
FieldRequiredMeaning
$schemaNoWhere editors find the JSON Schema, schema/<date>/musubi.schema.json
musubiYesThe definition version the file follows
provides.<name>Yes, one per contentThe content name: lowercase words joined by -
provides.<name>.versionYesThe content's version, MAJOR.MINOR.PATCH
provides.<name>.fileYesThe content file, relative to the skill folder
provides.<name>.checkNoA JSON rules file, relative to the skill folder, described in Check rules

Each content is one file with at most one check, and it is named <skill>/<name>, such as design-doc/design. Each content has its own version, so changing one does not change the version of the others. Paths stay inside the skill folder; musubi check refuses absolute paths and paths that leave it. The provider's SKILL.md body names the file of each content, because agents find the file by reading that body (decision record 0002). musubi.json is a separate file, not a frontmatter field, so that SKILL.md keeps passing the Agent Skills checks (decision record 0001).

Consumer declaration

A consumer skill lists the content it follows under follows in musubi.json.

{
  "musubi": "2026-11-19",
  "follows": {
    "design-doc/design": {
      "version": "^1.0.0",
      "integrity": "sha256-yNSwpBT+xXEV5bGBqedpHmjWIHVi+JaAnRATAJ0s7wM=",
      "examples": ["examples/orders-api.md"]
    }
  }
}
FieldRequiredMeaning
follows.<skill>/<content>Yes, one per contentThe content followed
follows.<ref>.versionYesThe versions the consumer accepts, described in Versions and fingerprints
follows.<ref>.integrityYesThe fingerprint of the content at the last check
follows.<ref>.examplesNoFiles of the consumer that the provider's check is applied to

The consumer's SKILL.md body carries three lines for each content it follows, which musubi add prints.

Write in the `design` format of the `design-doc` skill: open the `design-doc` skill by name and read the file it names for `design`.
If the `musubi` command is available, run `musubi check` before reading, and stop if it fails.
If the `design-doc` skill is not installed, do not start: tell the user that `design-doc` is missing and how to install it, then stop.

When the content's file is a script, told apart by the extensions .py, .sh, .bash, .js, .mjs, .cjs, and .ts in any case, the first line tells the agent to run it instead of reading it as a format.

Run the `verify` of the `design-doc` skill: open the `design-doc` skill by name and run the file it names for `verify`.

A consumer may add its own sections to the content it follows. It may not remove or rename what the provider's check requires. A skill may both provide content and follow content; a provider's format may follow shared writing rules, for example.

Discovery and loading

Agents load content by reading SKILL.md bodies, and never read musubi.json while they use a skill. An agent that knows nothing of musubi therefore loads content the same way as one that has the command.

  1. The agent reads the consumer's SKILL.md, as it does for any skill.
  2. The body names the provider skill and the content. The agent opens the provider skill by name from the skills it has installed and reads the file that the provider's body names for that content.
  3. The agent reads only that file, whole. It does not read the provider's other content.
  4. When the provider skill is not installed, the agent does not start; it tells the user which skill is missing and how to install it, and stops.

Claude Code, Codex, GitHub Copilot CLI, and Gemini CLI each list installed skills by name, so opening a skill by name works wherever the skill is installed. Relative paths between skill folders are not used, because two skills from different plugins are not installed side by side.

musubi check and musubi graph read skills from the folders named on the command line. Without folders they read .claude/skills, .agents/skills, .github/skills, and .gemini/skills in the current folder and in the home folder. A skill is a folder directly inside one of them that holds SKILL.md, and its name is the folder name. When two folders hold a skill of the same name, the first folder in that order wins and musubi check warns about the other.

Agents read a content file whole, so musubi check warns when one is over 500 lines, the length Agent Skills suggests for SKILL.md. It does not refuse such content; a provider splits a long content into several.

Versions and fingerprints

A content version is MAJOR.MINOR.PATCH.

Change to the content or its checkRaise
A consumer can break: a required section or column is removed or renamed, or the check becomes stricterMAJOR
Something is added that consumers may use, such as an optional sectionMINOR
Wording changes that keep every consumer validPATCH

A consumer writes the versions it accepts in one of three forms, read the way npm reads them.

FormAcceptsExample
^X.Y.ZFrom X.Y.Z up to the next MAJOR; for 0.Y.Z, up to the next MINOR^1.2.0 accepts 1.9.4, not 2.0.0
~X.Y.ZFrom X.Y.Z up to the next MINOR~1.2.0 accepts 1.2.7, not 1.3.0
X.Y.ZOnly X.Y.Z1.2.0

The fingerprint records exactly what the consumer was last checked against. It covers the provider's SKILL.md, the content file, and the check file, because an agent reads the first two and the check decides whether the consumer passes.

for each path in [SKILL.md, <file>, <check, when present>]:
    hash.update(path + "\n" + byte length in decimal + "\n")
    hash.update(the file's bytes)
    hash.update("\n")
integrity = "sha256-" + base64(sha256 digest)

Paths are relative to the provider's skill folder and use /. The range and the fingerprint sit together in musubi.json; there is no lockfile (decision record 0003).

The definition itself is versioned by date. Each musubi.json and each check file names the date it follows in musubi, and musubi check reads every date it knows and refuses the others. The dates it knows are the folders under schema/.

Re-checking

A consumer is checked again after a skill is installed, after a skill is updated, and, when the musubi command is available, before an agent reads the content.

musubi check refuses, naming the file and the line, when:

  • musubi.json is not valid JSON, has a field the definition does not know, or names a definition version it does not know
  • a version is not MAJOR.MINOR.PATCH, or a range is not one of the three forms
  • a file, check, or example path leaves the skill folder or names a missing file
  • a check is not a JSON rules file
  • a consumer follows a skill that is not installed, or a content that skill does not provide
  • the provider's version is outside the consumer's range
  • the fingerprint does not match, which means the content changed after the last check
  • an example breaks a rule of the provider's check
  • skills follow each other in a cycle, such as alpha -> beta -> alpha

Chains of any depth are allowed as long as they do not form a cycle. When a fingerprint does not match, musubi check does not apply that provider's check, because its content has not been accepted. musubi check --update applies the check to the changed content and rewrites the fingerprint only when every example passes; when one fails, the fingerprint stays as it was. musubi check without --update never writes a file.

Exit statusMeaning
0Every declaration and example passed; warnings may be printed
1At least one problem, printed as <file>:<line>: <message>
2The command was called the wrong way

Check rules

A check file is JSON with the definition version and a list of rules. musubi check reads the rules and applies them to each example the consumer names; it never runs provider code (decision record 0004).

{
  "musubi": "2026-11-19",
  "rules": [
    { "kind": "headings", "headings": ["## Purpose and scope", "## Decisions", "## Open decisions"] },
    { "kind": "forbid", "text": ["Fill in:"] },
    { "kind": "table-columns", "heading": "## Decisions", "columns": ["Option", "Chosen", "Why"] }
  ]
}
KindFieldsAn example passes when
headingsheadings: heading linesEvery heading line appears, in this order. Other headings may come between them
forbidtext: pieces of textNo line contains any of the text
table-columnsheading, columnsThe first table under the heading has every column. It may have more

Rules skip lines inside fenced code blocks. A consumer's added sections pass, because each rule looks only for what it requires. A new kind of rule is added by a new definition version.

Relation to existing systems

SystemWhat it doesHow musubi relates
Skill installers (APM, npx skills, skillpm, and others)Install skills and their dependencies, and lock versionsThey own where a skill comes from. musubi.json names only the skill, the content, and the version, so the source is written once
Claude Code plugin dependenciesInstall the plugins a plugin depends onSame as installers. Agents without such a field rely on the stop line in the consumer's body
Agent SkillsDefines SKILL.md and the skill folderSKILL.md is unchanged and musubi.json is one more file in the folder. musubi is to be proposed to Agent Skills once it runs on real skills
Agent Skills proposals for dependency files and lockfilesDeclare which skills a skill needsThey say which skill to install. musubi says which content of it a skill follows, at which version, and checks it again

The musubi command

The command needs Node.js 22.18 or later and has no runtime dependencies.

CommandDoes
musubi check [<folder>...] [--update]Checks every musubi.json in the folders, as described in Re-checking
musubi add <skill>/<content> [<folder>...]Run in a consumer's folder: writes the range ^<current version> and the fingerprint into its musubi.json, keeps the fields already there, and prints the three lines for its SKILL.md
musubi graph [<folder>...] [--out <file>]Writes one HTML page that draws each skill and an arrow to each content it follows