English日本語
定義のバージョン 2026-11-19正式な定義は英語の文書で、このページはその日本語訳です

musubiの定義

定義のバージョンは2026-11-19。

musubiは、文書の書式や書き方のルールのように、エージェントのスキルが提供するコンテンツと、そのコンテンツに準拠するスキルを結び付ける。あるスキルがコンテンツを名前とバージョン付きで宣言し、別のスキルがそのコンテンツに準拠すると宣言する。SKILL.mdを読むエージェントはどれも同じ方法でコンテンツを読み込み、コンテンツが変わると、準拠するスキルが再チェックされる。正式な定義は英語のmusubi.mdで、この文書はその日本語訳である。

概要

musubiに参加するスキルは、Agent Skillsが定めるSKILL.mdをそのまま持ち、その隣にmusubi.jsonというファイルを1つ追加する。

ファイル書く人持つもの
SKILL.mdスキルの作者Agent Skillsのフロントマターと本文で、変更しない。本文がエージェントに、どのコンテンツを読むかを伝える
musubi.json作者かmusubi addスキルが提供するコンテンツと、準拠するコンテンツ
コンテンツのファイルprovider書式や書き方のルールなど、consumerが準拠する文書
チェックのファイルprovidermusubi checkがconsumerの例に適用する、JSONのルール
skills/
├── design-doc/              providerのスキル
│   ├── SKILL.md             提供するコンテンツごとにファイルを指定する
│   ├── musubi.json          "provides": design 1.0.0
│   ├── formats/design.md    コンテンツ
│   └── checks/design.json   チェックのルール
└── api-design/              consumerのスキル
    ├── SKILL.md             design-doc/design を指す3行
    ├── musubi.json          "follows": design-doc/design ^1.0.0 とフィンガープリント
    └── examples/orders-api.md   チェックを適用する例

ここで使う用語はGLOSSARY.ja.mdで定義する。

providerの宣言

providerのスキルは、提供するコンテンツをmusubi.jsonのprovidesに並べる。

{
  "$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" }
  }
}
フィールド必須意味
$schemaいいえエディタがJSON Schemaを見つける場所。schema/<日付>/musubi.schema.jsonを指す
musubiはいこのファイルが準拠する定義のバージョン
provides.<名前>コンテンツごとに1つコンテンツの名前。小文字の単語を-でつなぐ
provides.<名前>.versionはいコンテンツのバージョン。MAJOR.MINOR.PATCHの形で書く
provides.<名前>.fileはいコンテンツのファイル。スキルのフォルダからの相対パスで書く
provides.<名前>.checkいいえJSONのルールのファイル。スキルのフォルダからの相対パスで書き、形はチェックのルールの節で定める

コンテンツは1つのファイルと、最大1つのチェックからなり、design-doc/designのように<スキル名>/<名前>で呼ぶ。コンテンツごとにバージョンを持つので、1つを変えても、ほかのコンテンツのバージョンは変わらない。パスはスキルのフォルダの中に限り、musubi checkは絶対パスとフォルダの外へ出るパスを拒否する。エージェントはproviderのSKILL.mdの本文を読んでファイルを見つけるので、providerの本文はコンテンツごとにファイルを指定する (判断の記録0002)。

宣言をフロントマターの項目でなく別のmusubi.jsonに書くのは、SKILL.mdがAgent Skillsのチェックを通り続けるようにするためである (判断の記録0001)。

consumerの宣言

consumerのスキルは、準拠するコンテンツをmusubi.jsonのfollowsに並べる。

{
  "musubi": "2026-11-19",
  "follows": {
    "design-doc/design": {
      "version": "^1.0.0",
      "integrity": "sha256-yNSwpBT+xXEV5bGBqedpHmjWIHVi+JaAnRATAJ0s7wM=",
      "examples": ["examples/orders-api.md"]
    }
  }
}
フィールド必須意味
follows.<スキル名>/<名前>コンテンツごとに1つ準拠するコンテンツ
follows.<参照>.versionはいconsumerが受け入れるバージョン。形はバージョンとフィンガープリントの節で定める
follows.<参照>.integrityはい最後にチェックした時のコンテンツのフィンガープリント
follows.<参照>.examplesいいえproviderのチェックを適用する、consumerのファイル

consumerのSKILL.mdの本文には、準拠するコンテンツごとに次の3行を書く。この3行はmusubi addが出力する。

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.

コンテンツのファイルがスクリプトの時は、1行目が、書式として読む代わりに実行するようエージェントに伝える。スクリプトかどうかは拡張子.py、.sh、.bash、.js、.mjs、.cjs、.tsで判定し、大文字と小文字は区別しない。

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

consumerは、準拠するコンテンツに自分の節を追加できる。ただし、providerのチェックが求めるものを削除したり、名前を変えたりはできない。1つのスキルが、コンテンツを提供しながら別のコンテンツに準拠してもよい。たとえば、providerの書式が、共通の書き方のルールに準拠することがある。

見つけ方と読み込み方

エージェントはSKILL.mdの本文を読んでコンテンツを読み込み、スキルを使っている間にmusubi.jsonを読むことはない。そのため、musubiを知らないエージェントも、musubiコマンドを使えるエージェントと同じ方法でコンテンツを読み込む。

  1. エージェントは、ほかのスキルと同じように、consumerのSKILL.mdを読む。
  2. 本文は、providerのスキルとコンテンツを名前で示す。エージェントはインストール済みのスキルからproviderのスキルを名前で開き、providerの本文がそのコンテンツについて指定するファイルを読む。
  3. エージェントはそのファイルだけを全文読む。providerのほかのコンテンツは読まない。
  4. providerのスキルがインストールされていない時、エージェントは作業を始めない。足りないスキルとそのインストール方法をユーザーに伝えて止まる。

Claude Code、Codex、GitHub Copilot CLI、Gemini CLIはどれもインストール済みのスキルを名前で一覧にするので、スキルがどこにインストールされていても名前で開ける。別々のプラグインからインストールした2つのスキルは同じ場所に並ぶとは限らないので、スキルのフォルダどうしの相対パスは使わない。

musubi checkとmusubi graphは、コマンドラインで指定したフォルダからスキルを読む。フォルダを指定しない時は、カレントフォルダとホームフォルダにある.claude/skills、.agents/skills、.github/skills、.gemini/skillsを読む。そのいずれかの直下にあり、SKILL.mdを持つフォルダがスキルで、スキルの名前はフォルダの名前である。同じ名前のスキルが2つのフォルダにある時は、上の順で先のフォルダのスキルを使い、musubi checkがもう一方について警告する。

エージェントはコンテンツのファイルを全文読むので、musubi checkは500行を超えるコンテンツを警告する。500行は、Agent SkillsがSKILL.mdに勧める長さである。そのようなコンテンツも拒否はしない。長いコンテンツは、providerが複数のコンテンツに分ける。

バージョンとフィンガープリント

コンテンツのバージョンはMAJOR.MINOR.PATCHの形で書く。

コンテンツかチェックの変更上げる番号
consumerがチェックを通らなくなりうる変更。必須の節や列を削除するか名前を変える、チェックを厳しくするMAJOR
consumerが使えるものを追加する変更。任意の節を追加するなどMINOR
全てのconsumerが通ったままになる、言い回しの変更PATCH

consumerは、受け入れるバージョンを次の3つの形のいずれかで書く。読み方はnpmと同じである。

形受け入れるバージョン例
^X.Y.ZX.Y.Zから次のMAJORの手前まで。0.Y.Zの時は次のMINORの手前まで^1.2.0は1.9.4を受け入れ、2.0.0は受け入れない
~X.Y.ZX.Y.Zから次のMINORの手前まで~1.2.0は1.2.7を受け入れ、1.3.0は受け入れない
X.Y.ZX.Y.Zだけ1.2.0

フィンガープリントは、consumerが最後にどの内容に対してチェックされたかを正確に記録する。エージェントはproviderのSKILL.mdとコンテンツのファイルを読み、チェックはconsumerが通るかを決めるので、フィンガープリントはこの3つのファイルを対象にする。

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)

パスはproviderのスキルのフォルダからの相対パスで、区切りに/を使う。バージョンの範囲とフィンガープリントはmusubi.jsonに並べて書き、ロックファイルは持たない (判断の記録0003)。

定義そのもののバージョンは日付で表す。musubi.jsonとチェックのファイルは、準拠する日付をmusubiのフィールドに書く。musubi checkは知っている日付を全て読み、それ以外の日付を拒否する。知っている日付は、schema/の下にあるフォルダの名前である。

再チェック

consumerは、スキルをインストールした後と、スキルを更新した後に再チェックされる。musubiコマンドが使える時は、エージェントがコンテンツを読む前にも再チェックされる。

musubi checkは次の場合に、ファイルと行を示して拒否する。

  • musubi.jsonがJSONとして正しくない、定義にないフィールドを持つ、知らない定義のバージョンを指定している
  • バージョンがMAJOR.MINOR.PATCHの形でない、範囲が3つの形のどれでもない
  • ファイル、チェック、例のパスがスキルのフォルダの外へ出るか、存在しないファイルを指している
  • チェックがJSONのルールのファイルでない
  • consumerが、インストールされていないスキルか、そのスキルが提供していないコンテンツに準拠している
  • providerのバージョンがconsumerの範囲の外にある
  • フィンガープリントが一致しない。最後のチェックの後にコンテンツが変わったことを表す
  • 例がproviderのチェックのルールに違反している
  • スキルどうしが循環して準拠している (alpha -> beta -> alphaなど)

循環しない限り、準拠の連鎖はどれだけ深くてもよい。フィンガープリントが一致しない時、そのコンテンツはまだ受け入れられていないので、musubi checkはそのproviderのチェックを適用しない。musubi check --updateは変わったコンテンツにチェックを適用し、全ての例が通った時だけフィンガープリントを書き換える。

1つでも通らなかった時は、フィンガープリントを元のまま残す。--updateを付けないmusubi checkは、ファイルを書き込まない。

終了コード意味
0全ての宣言と例が通った。警告を出力することがある
11つ以上の問題があり、<ファイル>:<行>: <メッセージ>の形で出力した
2コマンドの呼び出し方が間違っている

チェックのルール

チェックのファイルは、定義のバージョンとルールの一覧を持つJSONである。musubi checkはルールを読み、consumerが指定した例それぞれに適用する。providerのコードは実行しない (判断の記録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"] }
  ]
}
種類フィールド例が通る条件
headingsheadingsに見出しの行を並べる全ての見出しの行がこの順番で現れる。間にほかの見出しがあってもよい
forbidtextに文字列を並べるどの行も、並べた文字列のいずれも含まない
table-columnsheadingとcolumns見出しの下の最初の表が全ての列を持つ。ほかの列があってもよい

ルールは、コードブロックの中の行を読み飛ばす。各ルールは求めるものだけを探すので、consumerが追加した節は通る。新しい種類のルールは、新しい定義のバージョンで追加する。

既存の仕組みとの関係

仕組みすることmusubiとの関係
スキルのインストーラー (APM、npx skills、skillpmなど)スキルとその依存をインストールし、バージョンを固定するスキルの入手先はインストーラーが管理する。musubi.jsonはスキルとコンテンツとバージョンだけを書くので、入手先を書くのは1か所で済む
Claude Codeのプラグインのdependenciesプラグインが依存するプラグインをインストールするインストーラーと同じ。このようなフィールドを持たないエージェントでは、consumerの本文にある作業を止める1行に頼る
Agent SkillsSKILL.mdとスキルのフォルダを定めるSKILL.mdは変えず、フォルダの中にmusubi.jsonが1つ増えるだけである。musubiは実際のスキルで動くようになった後に、Agent Skillsへ提案する
Agent Skillsの依存ファイルとロックファイルの提案スキルが必要とするスキルを宣言するこれらはどのスキルをインストールするかを書く。musubiは、そのスキルのどのコンテンツにどのバージョンで準拠するかを書き、再チェックする

musubiコマンド

コマンドはNode.js 22.18以降で動き、実行時の依存を持たない。

コマンドすること
musubi check [<フォルダ>...] [--update]フォルダの中の全てのmusubi.jsonを、再チェックの節のとおりにチェックする
musubi add <スキル名>/<名前> [<フォルダ>...]consumerのフォルダで実行する。musubi.jsonに範囲^<今のバージョン>とフィンガープリントを書き込み、既にあるフィールドは残し、SKILL.mdに置く3行を出力する
musubi graph [<フォルダ>...] [--out <ファイル>]各スキルと、準拠するコンテンツへの矢印を描いたHTMLのページを1つ書き出す