ms

ms — meta_skill 検索／読み込みエンジン

中核となる考え方： ms は、設定済みの両方のコーパス（agentops + jsm）を対象とするスキル検索エンジンです。利用には MCP、書き込み／管理には CLI を使用します。 守るべきルールは1つです。インデックスの再構築または消去を行った後は、実行中の ms mcp serve をすべて必ず終了させてください（セッションは新たに起動します）。終了していないサーバーは消去前のデータを黙って読み込み、孤立したファイルへの書き込みに対して recorded:true を返します。

制約

• スキルを実行する意図がある場合は、full: true または --full を指定して読み込んでください。メタデータカードや圧縮された概要には、実行可能なガイダンスが含まれていないためです。
• 利用と書き込みの境界を明確にしてください。検索と読み込みには MCP を使い、フィードバックと結果の記録には CLI を使ってください。ライブデータベースへの書き込みが検証済みとなるのは CLI のみです。
• 接続済みの mcp__ms__* ツールが利用できない場合は、検索にスキル固有のワンショット MCP ヘルパーを使ってください。ms search CLI の検索結果が0件でも、MCP BM25 で一致が見つからなかったことの証拠にはならず、黙ってその代わりに使ってはいけません。
• インデックスの再構築には scripts/ms-reindex.sh のみを使ってください。古いサーバーを一掃し、インデックス再構築後にソースとの同等性を証明するためです。
• ローカルインデックスは信頼できる情報源ではなく、破棄可能な状態として扱ってください。インデックス化された内容を編集するのではなく、skills/** を編集することが目的です。
• 本番のスキル作業では、ms は検索と読み込み専用にしてください。検索結果と読み込み結果を返し、作成、検証、その後のあらゆる判断は呼び出し側が担います。

セッションの証拠と指示の変更

指示の改善を求められた場合は、CASS を使って関連するエピソードを見つけ、ms で、その動作を説明できる、またはすでに対処している可能性のある既存のガイダンスを探してください。関連するスキルのみを読み込んだうえで、編集を提案する前にその正式なソースを確認してください。AGENTS.md やタスクプロンプトの変更に、スキルを新たに作成したり、無関係なスキルを読み込んだりする必要はありません。

上流の MS では build --from-cass も利用できますが、このアダプターはその作成経路を意図的に呼び出しません。呼び出し側が別途選択した場合は、ms build --help を確認してください。生成されたスキル、検索順位、繰り返しのプロンプト、記録された結果は、下流で改善があった証拠にはなりません。

CASS の検索／パック機能は、候補となる証拠を提供します。選択した CASS の出力だけでは特定できない正確な生の範囲、リテラルのフィールド、または指示の同一性が調査に必要な場合に限り、AO の範囲を限定した抜粋ビューを使ってください。これらは任意の機能であり、すべてのタスクで必須の手順ではありません。候補となる編集、または変更しないという判断、独立したレビュー、その後の有用性テストは、呼び出し側が担います。検索機能自体がそうした結果をもたらすことはありません。

クイックスタート

スキルを見つけ（MCP を優先 — BM25 は現時点で CLI 検索を明確に上回ります）、その後、実行可能な完全版の SKILL.md を1回の呼び出しで読み込みます（使う意図がある場合は、必ず full: true を指定してください）。

mcp__ms__search {query: "handle a rate limit switching accounts"}
mcp__ms__load {skill: "account-rotation", full: true}

接続済みの MCP ツールがない場合：使い捨ての stdio サーバーを1つ起動し、構造化された検索 JSON のみを返してください。成功時、エラー時、タイムアウト時のいずれでもサーバーを終了させてください。

python3 skills/ms/scripts/mcp-search.py "switch accounts on rate limit"
ms load account-rotation --full -O json | jq -r '.data.content'

状態ルート：~/Library/Application Support/ms/。

---

使用 — MCP を最優先（mcp__ms__*）

ms mcp serve が接続されている場合は、MCP ツールを優先してください。高速で、検証済みの読み取り経路です。

ツール	用途
mcp__ms__search {query}	BM25 検索。現在、CLI 検索より明確に優れています（「落とし穴」を参照 — CLI のハイブリッド検索は BM25 のみです。ms はドキュメントの埋め込みを保存しません）。
mcp__ms__load {skill, full: true}	実行可能な SKILL.md 全体を 1 回の呼び出しで返します。抽出の手間はありません。full: false が返すのは役に立たないメタデータカードです — スキルを使う場合は、必ず full: true を指定してください。
mcp__ms__show {skill}	スキルのメタデータカードです。
mcp__ms__suggest {cwd}	ディレクトリに合ったスキルを提案します。動作しますが、プロジェクト言語の検出結果は無視してください（Makefile を含むリポジトリを C と誤検出します。実害はありません）。

MCP ツールが接続されていない場合： サーバーを使ったワンショットヘルパーを使用してください。これにより、取得は引き続き MCP の BM25 経路を通ります。

python3 skills/ms/scripts/mcp-search.py "<query>"

ヘルパーは、整形済みの検索オブジェクト（query、count、results）を標準出力に書き込み、転送／プロトコルエラーを標準エラー出力に報告します。デフォルトで 30 秒のタイムアウトを適用し、終了と回収まで使い捨てサーバープロセスグループを管理します。実行ファイルは MS_BIN、タイムアウトは MS_MCP_SEARCH_TIMEOUT または --timeout で上書きできます。

検索後の全件読み込み用フォールバックとして、サポート対象の CLI を引き続き使用してください。

ms load <id> --full -O json | jq -r '.data.content'   # content lives in .data.content

ヘルパーを ms search に置き換えないでください。CLI 経路は、検索結果の同等性に関する差が解消されるまでは、診断にのみ役立ちます。特に、CLI の検索結果がゼロでも、コーパスに一致するスキルがないとは限りません。

---

書き込み／管理 — CLI のみ（稼働中の DB への書き込みを検証済み）

MCP のフィードバックツールは存在しますが、書き込みが反映されることを検証済みなのは CLI の書き込み経路のみです — 書き込みには CLI を使用してください。

ms feedback add <skill> --positive --comment "..."   # feedback on a skill
ms feedback add <skill> --negative --comment "..."

ms outcome <skill> --success   # record only AFTER downstream factory use + validation
ms outcome <skill> --failure

ms doctor                      # admin: health
scripts/ms-reindex.sh          # (re)index THE way: rebuild + sweep + probe + source-equivalence check
scripts/ms-reindex.sh --check-source  # read-only freshness proof against current skills/** source
# Optional operator policy only; rebuild completeness is derived from live
# discovered/indexed/errors accounting, not a historical absolute count:
MS_REINDEX_MIN_INDEXED=100 scripts/ms-reindex.sh
ms list -O jsonl --limit 1000  # counting / enumeration
ms config                      # resolved config + skill_paths

出力仕様

• パス： 検索、読み込み、管理の結果は stdout に返されます。永続的なインデックスの状態は ~/Library/Application Support/ms/ に保持されます。
• ファイル名： このスキルによって結果ファイルが作成されることはありません。永続的な成果物が必要な場合は、呼び出し元が CLI の出力を明示的に保存します。
• 形式： 接続済み MCP は構造化されたツールデータを返します。ワンショットヘルパーは MCP コンテンツを整形済みの検索 JSON に展開します。CLI の自動化では JSON または JSONL を使用し、ms load --full -O json の場合、スキル全文は .data.content に含まれます。
• 検証コマンド： 取得境界の検証には skills/ms/scripts/validate.sh を、正規化済みソースの同等性の検証には scripts/ms-reindex.sh --check-source を実行してください。
• 後続工程への引き渡し： 読み込んだガイダンスとソースの識別情報を呼び出し元に返してください。取得処理がワークフローを選択または開始することはありません。

本番用スキルの引き渡し

本番利用を目的とした引き渡し： クエリがスキルの作成または編集に関するものである場合、ms は関連するガイダンスを取得して停止します。呼び出し元は、別途 skill-builder（作成、修復、監査モード）または別のオーサリングツールを呼び出せます。

権限の境界： skills/** が正規のソースです。ジェネレーターが ms の Codex ツインおよびその他の投影を管理します。インデックス、読み込み済みのコピー、生成された投影をソースとして編集しないでください。

ms は後続の作業を検証も解釈もしません。検索、読み込み、書き込み、または再インデックスに失敗した場合、その結果を証拠として返し、この呼び出しを終了します。

結果を記録するタイミング： ms outcome を記録するのは、後続の作業にどれほど役立ったかを示す独立した証拠を呼び出し元が得た後に限ります。取得しただけでは記録しません。この観測によってコアの状態が変わることはありません。

---

落とし穴（2026-07-15 までの測定）

落とし穴	実態
DB の消去／再インデックス後も MCP サーバーが稼働し続ける	ms mcp serve はハンドルを再度開くことがありません。名前変更された inode をバックアップ先まで追跡するため、古いデータを読み取るだけでなく、気付かないまま書き込み先を誤ります（孤立したファイルに recorded:true が書き込まれます）。scripts/ms-reindex.sh で再インデックスしてください。これが唯一の方法です（再構築し、ライブ検出されたすべてのスキルがインデックス化されたか、許可されたエラーとして報告されたことを検証し、すべてのサーバーを終了させ、新しいサーバーを起動してプローブし、正規化したローカル読み込み結果を現在の skills/** ソースと比較します）。サーバーを稼働させたまま ms index を単独で実行してはいけません。セッションは新たに起動します。
ms load --pack N	落とし穴：N が何であっても、内容が削られた overview ティアが上限になります（800 でも 20000 でも同じです）。実行可能な手順が失われ、フラグなしのデフォルトより少ない内容しか返りません。--full（CLI）または full: true（MCP）を使用してください。
-O plain	load では名前のみを出力し、リストの出力は切り詰められます（[N more lines]）。内容は -O json → .data.content にあります。
CLI の ms search の「ハイブリッド」	実質的には BM25 のみです。ms はドキュメントの埋め込みを保存しません（upsert_embedding が呼び出されるのは単体テストからのみです）。そのため、どのバックエンドでもハイブリッド ≡ BM25 であり、設定やバックエンドを変更しても解決しません（上流の不足機能として記録済み。測定日：2026-07-02、age-s3jf）。MCP の BM25 が順位付きの一致を返す一方で、結果がゼロになることがあります。ツールが接続されていない場合は scripts/mcp-search.py を使用してください。CLI の結果がゼロの場合に、MCP のフォールバックが成功したものとして扱ってはいけません。
古い ms.lock	ms doctor は PID が停止済みでも「Lock held」と表示し、すべて合格とも表示します。停止済み PID のロックは安全に削除できます。
シンボリックリンク	ms はディレクトリのシンボリックリンクをたどりません。skill_paths には両方のルート、つまり ~/.claude のスキルディレクトリと ~/dev/agentops/skills のリポジトリディレクトリを明示的に指定する必要があります。
バイナリ	ソースからのビルドのみです（~/dev/meta_skill、ブランチ local/frontmatter-id）。リリース版の 0.1.2 バイナリは、Anthropic-frontmatter 形式のスキルの ID を破損させます。更新：git fetch && git rebase origin/main && cargo install --path . --locked。

並行処理

CLI と MCP の load を並行して実行しても問題がないことを測定済みです。ロックの危険があるのは、上記の消去後もサーバーが稼働し続けるケース（serve を停止してください）であり、読み取りの並行実行ではありません。

---

シナリオ

Scenario: Load a skill's full runnable guidance
  Given an ms mcp serve is attached
  When I call mcp__ms__load {skill: "account-rotation", full: true}
  Then the full runnable SKILL.md content is returned in one call

Scenario: Search without an attached MCP tool
  Given mcp__ms__search is unavailable
  When I run python3 skills/ms/scripts/mcp-search.py with the query
  Then it returns only structured MCP search JSON
  And its disposable ms mcp serve process is reaped on success, error, or timeout

Scenario: Reindex invalidates every running server
  Given one or more ms mcp serve processes are running
  When I run ms index (or wipe/rebuild the DB)
  Then I kill every ms mcp serve so sessions respawn against fresh data
  And a surviving server would silently read pre-wipe data and mis-land writes

Scenario: A stale local projection fails closed
  Given AgentOps skills are authoritative and ms is a disposable local index
  When a full ms load has a different normalized name or description from source
  Then scripts/ms-reindex.sh exits nonzero and names the stale skill

品質チェックリスト

• 完全な読み込みでは、メタデータカードや圧縮された概要ではなく、実行可能なガイダンス全体が保持されます。
• 検索では接続済みの MCP ツールか単発の MCP ヘルパーを使用し、結果がゼロの CLI に黙って置き換えることはありません。完全な読み込みでは MCP または検証済みの CLI 形式を使用します。
• 再構築の際は、ライブ検出されたすべてのスキルを確認し、検索可能なインデックスが空でないことを検証したうえで、古いサーバーをすべて終了させ、ソースとの同等性を報告します。
• 本番のスキルの意図は取得後に ms の外部に保持します。生成された複製や読み込み／インデックス化されたコピーをソースとして直接編集してはいけません。
• 検索結果と読み込み結果は参考情報として扱い、後続の作業が正しいことの証明として扱ってはいけません。
• ms outcome は、後続の作業で独立した根拠が得られた後に限り、観察された有用性を記録します。

参考資料

• 上流プロジェクト：Jeffrey Emanuel の meta_skill（ソースは ~/dev/meta_skill、ブランチは local/frontmatter-id）。
• このリポジトリ内の関連するツール利用スキル：cass（セッションの調査）。jsm の手続き的メモリツール cass-memory（cm）は書き込み側の補完機能です（別途インストールするもので、このリポジトリには含まれません）。
• ライフサイクル契約のバリデーター：scripts/validate.sh。