メインコンテンツへ移動
AIチュートリアル

MuseAI-Skills読解チュートリアル：Muse AIのスキル、権限、Agentワークフローを解析

本チュートリアルでは、MuseAI-Skillsを取得して安全に読み解く方法を紹介します。スキル定義、コネクタ権限、評価シナリオ、実行環境スクリプトを理解し、Gmailなどのスキルを例に、再利用可能なAgentワークフローの分析手法を身につけます。

約21分で読了
MuseAI-Skills読解チュートリアル：Muse AIのスキル、権限、Agentワークフローを解析

プロジェクトとは

MuseAI-Skills は、muse.ai に関連する Muse / Hatch パーソナル AI Agent 環境のスナップショットです。リポジトリには、製品説明、スキル定義、コネクター権限一覧、動作評価シナリオ、Linux 実行スクリプト、および一部の同梱プログラムと依存関係が保存されています。

重要な境界：これは完全なソースコードリポジトリでも、ワンクリックでデプロイできるインストールパッケージでもありません。コアプログラムは主に Linux x86-64 ELF バイナリとして提供されますが、ビルド用ソース、完全なホスト設定、rootfs、一部の実行リソースは含まれていません。

そのため、このリポジトリは静的な読解、Agent ワークフローの研究、権限モデルの分析、指示設計の参考に最も適しており、Muse AI サービスを直接インストールする用途には適していません。リポジトリ内の資料では Muse、Hatch、Jarvis などの名称が使われていますが、このアーカイブ自体が公式リリース、承認、または出所の認証を意味するものではありません。

リポジトリから学べること

スキルワークフローの全体構造

リポジトリには 72 個の SKILL.md パスがあり、その内訳は 68 個の独立したスキルファイルと 4 個のシンボリックリンクによるエイリアスです。スキルは、Agent ワークフロー、ドキュメント成果物、旅行予約、オフィスツール、ソーシャルプラットフォーム、健康データ、メディア生成、デバイス制御、Muse 製品操作などの分野をカバーしています。

これらのスキルドキュメントから、通常は次のような点を研究できます。

  • どのユーザーリクエストがスキルを起動すべきか。
  • タスクをコーディネーター、worker、外部コネクターのいずれが処理すべきか。
  • 実行前に必要なアカウント接続、OAuth scope、ユーザー認証は何か。
  • ツールの失敗、入力不足、権限不足が発生した場合にどうフォールバックするか。
  • 出力形式をどのように定義し、最終成果物をどう検証するか。

権限と評価資料

リポジトリには、さらに 40 個の manifest パスと 12 個の eval YAML があります。manifest.yaml は、コネクターのメタデータ、権限のデフォルト値、scope 要件、コマンドマッピングを理解するために利用できます。eval/scenarios.yaml には、動作評価シナリオ、ユーザーの目標、期待される動作が記録されています。

注意：manifest が存在することは、アカウントが接続済みであることを意味しません。評価シナリオが存在することも、評価が実行済みまたは合格済みであることを意味しません。

実行環境に関する静的な手がかり

opt/hatch/runtime-cell/ 内のスクリプトには、rootfs パスの解決、起動前の準備、カーネルモジュールの確認、systemd-nspawn コンテナの起動、スキルとバイナリ overlay の組み立てなど、実行環境のライフサイクルの一部が示されています。ただし、完全なホスト unit、nspawn 設定、実際の rootfs はリポジトリに含まれていません。

ディレクトリ構成の概要

  • README.md：中国語の入口、スキルディレクトリ、境界に関する説明。
  • README.en.md：英語の入口。
  • PROJECT_ANALYSIS.md：アーキテクチャの判断、欠落コンポーネント、リスク、証拠インデックス。
  • SHA256SUMS：通常ファイルの内容チェックリスト。ただし出所の署名ではありません。
  • home/hatch/docs/：製品、コネクター、プライバシー、スケジューリング、ファイル、デバイス、メディアなどの説明。
  • home/hatch/config/：Agent とスキルの状態に関連する設定。
  • opt/hatch/skills/：スキルの入口、権限 manifest、評価シナリオ、参考資料。
  • opt/hatch/runtime-cell/：実行環境のライフサイクルスクリプトと設定テンプレート。
  • opt/hatch/bin/：Hatch 関連プログラム。
  • opt/hatch-image/：イメージ側のツール、npm、Bun、その他の同梱コンポーネント。

リポジトリのルートディレクトリはアーカイブのルートであり、実行中の Linux ルートディレクトリではありません。アーカイブ内の home/hatch/ は元の環境における /home/hatch に対応します。一方、ドキュメント内の /run、/var/lib、/etc は通常、欠落しているランタイムファイルシステムを指します。

リポジトリの取得と準備

方法 1：スキルとドキュメントだけを研究する

Markdown、YAML、Shell スクリプトの分析が目的であれば、サイズの大きい Git LFS バイナリをスキップできます。これは最も推奨される読解方法です。

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills

この方法では同梱プログラムを実行する必要はありません。リポジトリに入ったら、まず PROJECT_ANALYSIS.md と opt/hatch/skills/ を確認してください。

方法 2：完全なアーカイブオブジェクトを確認する

LFS に含まれる ELF プログラムやその他の大容量ファイルを実際に調査する必要がある場合に限り、Git LFS をインストールして関連オブジェクトを取得してください。バイナリをダウンロードしても、欠落しているソースコード、rootfs、認証情報、ホスト設定が補われるわけではなく、リポジトリがデプロイ可能なシステムになるわけでもありません。

git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills
git lfs pull

出所が独立して認証されていないバイナリについては、まずオフラインで静的検査を行い、本番マシンや機密性の高い認証情報を含む環境で直接実行しないでください。

通常ファイルの検証

関連ファイルを完全に取得した後、リポジトリが提供する SHA256SUMS を使って内容の完全性を確認できます。

sha256sum -c SHA256SUMS

チェックリスト自体とシンボリックリンクは対象外であり、公開者の身元や出所の真正性を示す暗号学的署名でもありません。これは、ローカルの通常ファイルがチェックリストに記録されたダイジェストと一致するかどうかを判断するためだけに役立ちます。

基本的な使い方：スキルの読解フローを構築する

ステップ 1：スキルの入口を選ぶ

初めて読む場合は、次のスキルから始めるとよいでしょう。

  • wide-research：研究コーディネーター、worker、統一出力契約、失敗時の対応範囲を研究します。
  • skill-creator：スキルの起動説明、ディレクトリ分割、参考資料のオンデマンド読み込みを扱います。
  • artifacts/testing：「生成に成功した」ことと「成果物が利用可能である」ことを区別します。
  • goals：目標の初回設定と、その後のフォローアップを区別します。
  • forget：コピー、派生状態、再書き込みされる可能性のあるデータを扱います。
  • travel-planning：旅程の調査、リアルタイム検索、取引の実行を分離します。
  • gmail：スキル本文、メソッド単位の権限、評価シナリオを組み合わせてコネクターを分析します。

たとえば、Gmail スキルの入口を確認します。

sed -n '1,240p' opt/hatch/skills/gmail/SKILL.md

ステップ 2：起動条件と境界を抽出する

SKILL.md を読む際は、「何ができるか」だけを記録せず、次の質問に順番に答えてください。

  1. どのリクエストがこのスキルを起動すべきか。
  2. どのような類似リクエストでは起動すべきでないか。
  3. 読み取り操作と書き込み操作をどのように区別するか。
  4. 送信、削除、購入、予約などの影響が大きい操作には確認が必要か。
  5. 権限不足、目的の曖昧さ、ツールの失敗が発生した場合にどう対処するか。
  6. 最終結果にどのフィールドや証拠を返す必要があるか。

これらを「起動、入力、認証、実行、失敗、受け入れ」の 6 つの部分に整理すると、自分の Agent 設計へ移植しやすくなります。

ステップ 3：権限 manifest と照合する

コネクター系のスキルでは、同じディレクトリにある manifest.yaml も続けて読んでください。

sed -n '1,260p' opt/hatch/skills/gmail/manifest.yaml

スキル本文で主張されている操作と、manifest に記載されたメソッド権限、グループのデフォルト値、scope、コマンドマッピングを重点的に比較します。メソッド単位の設定がグループのデフォルト値を上書きする場合があるため、トップレベルの権限説明だけを見てはいけません。

SKILL.md を別の Agent 環境にコピーしても、Gmail、Google Drive、Notion、その他のサービスへのアクセス権が自動的に付与されるわけではありません。実際の実行には、対応する CLI または MCP、アカウント接続、OAuth scope、ランタイムでの認証が必要です。

ステップ 4：評価シナリオを読む

スキルに eval/scenarios.yaml がある場合は、ルールをテスト可能な動作へ変換する方法を確認できます。

sed -n '1,260p' opt/hatch/skills/gmail/eval/scenarios.yaml

評価シナリオは、次のような動作の確認に適しています。

  • Agent が正しいスキルを選択したか。
  • 読み取り、下書き、送信、削除など、リスクレベルの異なる操作を区別したか。
  • 情報が不足している場合、受信者や操作対象を推測せず、先に確認したか。
  • 必要なときに認証や確認を求めたか。
  • 失敗後に未完了の項目を正直に報告したか。

シナリオファイルをテスト合格レポートとして扱ってはいけません。過去の問題を判断するには、opt/hatch/skills/flightaware/eval/findings.md のような発見記録も参照できますが、そのバージョンとテスト環境には注意してください。

ステップ 5：関連する参考資料を確認する

一部のスキルでは、詳細なルールを references/、guide/、creation/、guides/ に分割しています。この構造は重要な設計原則を示しています。つまり、メインのスキルファイルは簡潔に保ち、タスクで必要になった場合にのみ、より具体的な参考資料を読み込むという原則です。

たとえば、スキルの作成方法は次のファイルから読み始めることができます。

sed -n '1,260p' opt/hatch/skills/skill-creator/references/authoring_guide.md

実践例：Gmail スキルを分析する

実際にメールボックスへ接続したり操作したりせずに、次のテンプレートを使って Gmail スキルの設計を記録できます。

スキル入口：opt/hatch/skills/gmail/SKILL.md
権限定義：opt/hatch/skills/gmail/manifest.yaml
評価シナリオ：opt/hatch/skills/gmail/eval/scenarios.yaml

分析の観点：
1. メールの検索と閲覧を起動する条件
2. 下書き、送信、返信の操作境界
3. ラベルと配信停止のフロー
4. メソッド単位の権限と OAuth scope
5. 受信者、メールスレッド、操作意図が不明確な場合の処理
6. ツール失敗後の報告方法
7. ユーザーが最終的に受け取るべき結果と検証情報

完了後は、結果を自分の Agent 仕様へ変換できます。

  • 起動ルール：どの言語パターンがメールスキルに入るかを明確にする。
  • 読み取り優先：検索・閲覧と、送信・削除などの変更操作を分けて処理する。
  • 認証のしきい値：実行環境に応じて確認と OAuth のルールを再定義する。
  • 出力契約：成功、一部成功、失敗の場合にそれぞれ何を返すかを規定する。
  • 受け入れシナリオ：通常のリクエスト、曖昧なリクエスト、権限不足、コネクター障害のテストを追加する。

製品とシステムアーキテクチャを読む

製品の契約をすばやく理解する

次の順序で読むことをおすすめします。

  1. home/hatch/docs/muse.md：製品概要。
  2. home/hatch/docs/goals.md：目標、進捗、バックグラウンド処理の境界。
  3. home/hatch/docs/scheduling-and-watching.md：ポーリング、スケジューリング、実行履歴、通知。
  4. home/hatch/docs/self_improvement.md：バックグラウンドメモリ、調査、振り返り、証拠の追跡。
  5. home/hatch/docs/connectors.md：接続状態、OAuth、メソッド権限、失敗処理。
  6. home/hatch/docs/privacy-and-credentials.md：認証情報の参照、Vault、エクスポート、削除ルール。

これらのファイルが記述しているのは、スナップショット内の製品契約です。アカウント固有の機能や過去の利用可能性に関する説明を、現在すべての Muse アカウントが備えている事実として直接扱うべきではありません。

調査ランタイムの起動チェーン

Linux の分離環境に注目する場合は、次のスクリプトから呼び出し関係を構築できます：

opt/hatch/runtime-cell/pre-start.sh
opt/hatch/runtime-cell/ensure-rootfs.sh
opt/hatch/runtime-cell/resolve-rootfs-path.sh
opt/hatch/runtime-cell/require-modules.sh
opt/hatch/runtime-cell/launch-daemon.sh
opt/hatch/runtime-cell/post-start.sh

resolve-rootfs-path.sh が返す /var/lib/hatch-runtime/rootfs は実行環境内のパスであり、リポジトリに含まれるディレクトリではありません。launch-daemon.sh は systemd-nspawn コンテナを起動して overlay を組み立てます。欠落しているホスト設定や rootfs から切り離して、単独で起動手順を構成することはできません。

高度な分析手法

スキル、エイリアス、リソースディレクトリを区別する

リポジトリには 4 つのシンボリックリンクエイリアスがあります：facebook は facebook-cli を指し、meta-threads は threads を指し、podcast は generate_podcast を指し、voice-calls は voice-selector を指します。

リンクの実際の参照先を確認すると、重複カウントを避けられます：

find opt/hatch/skills -type l -name SKILL.md -print -exec readlink {} \;

特に、voice-calls という名前から、Agent が電話を代わりにかける機能を備えていると推測してはなりません。このエントリは実際には静的な音声ディレクトリを指しています。spaces にはランタイム文書とテンプレートが含まれていますが、トップレベルの SKILL.md はないため、別のスキルとして追加で数えるべきではありません。

宣言、権限、実行可能な依存関係を同時に検証する

スキルを分析する際は、次の 3 層の照合方法を使えます：

  1. 動作層：SKILL.md に記載されたトリガー、境界、出力を確認する。
  2. 権限層：manifest 内のメソッド、scope、デフォルト権限を確認する。
  3. 実行層：依存する CLI、MCP、補助プログラム、アカウント接続、ランタイムリソースが存在するか確認する。

リポジトリには、Artifacts の検証スクリプト、skill-creator のコネクタースキャフォールド、Magic Moment の mm 実行可能プログラム、さらに Spaces に必要な一部の SDK とビルドリソースなど、重要な依存関係が一部明確に欠けています。そのため、「文書を読める」ことは「実行チェーンが完全である」ことを意味しません。

成果物の生成と受け入れ検査を分ける

artifacts/testing は、汎用的な Agent パターンの研究対象として有用です。ファイルを生成した後、成果物の種類に応じて検査し、再レンダリングし、目視で受け入れ確認を行い、プレースホルダーをスキャンすることを重視しています。自分のシステムに移行する際は、フローを次のように分けられます：

  1. ドキュメント、表計算、PDF、プレゼンテーションを生成する。
  2. 生成結果を再度開く、またはレンダリングする。
  3. 構造、レイアウト、数式、リンク、欠落リソースを確認する。
  4. 未置換のプレースホルダーと仮テキストを検索する。
  5. 受け入れ確認に合格してから、ファイルを納品可能としてマークする。

マルチ Agent 協調を研究する

wide-research は、複数入力による並列調査における重要な制約を示しています。調整役と worker の責務を制限し、出力フィールドを統一し、カバレッジを報告し、失敗項目を保持します。移行時は、自分のオーケストレーションフレームワークに合わせてツール名とワークスペースのパスを置き換えつつ、統一された出力契約と失敗の可視性を維持すべきです。

データベースを探すのではなく、データベースの説明を確認する

opt/hatch/skills/muse_db/references/schema.md には、制限付き SQL ルール、識別子、複数の schema にまたがるリレーションが記載されており、データモデルとテーブル間の追跡方法を理解するために利用できます。これは実際のデータベースでも移行ソースコードでもないため、完全なサービスを復元する根拠にはなりません。

出典、ライセンス、証拠の境界を維持する

ワークフローを他のプロジェクトに移行する際は、出典の帰属を維持し、適用されるライセンスを確認すべきです。内部分析の記録では、次の項目を区別することを推奨します：

  • リポジトリのファイルに直接記載された事実。
  • ディレクトリ、スクリプト、manifest に基づく技術的推論。
  • まだ検証されていない製品の主張。
  • 実行環境が欠落しているため確認できない動作。

「アーカイブ内で確認できる」ことは、「公式の出典が認証済みである」「独立して実行できる」「自由に再許諾できる」ことを意味しません。

推奨学習ルート

  1. リポジトリをクローンする際は LFS をスキップし、不要なバイナリのダウンロードを避ける。
  2. PROJECT_ANALYSIS.md を読み、アーキテクチャ上の判断と欠落項目を把握する。
  3. skill-creator または wide-research を選び、ワークフローの構造を学ぶ。
  4. gmail を選び、スキル本文、manifest、eval を組み合わせて分析する。
  5. artifacts/testing を読み、納品物の受け入れ確認という考え方を身につける。
  6. 製品ドキュメントを読み、スキルのルールと製品契約を区別する。
  7. 最後に runtime-cell スクリプトを確認し、ランタイムの手がかりと欠落依存関係を理解する。

まとめ

MuseAI-Skills の主な価値は、直接デプロイできることではなく、個人向け AI Agent がスキルのトリガー、タスクの振り分け、コネクター権限、失敗処理、結果の受け入れ確認をどのように整理するかを示している点にあります。SKILL.md、manifest.yaml、評価シナリオ、実行依存関係をまとめて読むことで、自分の Agent システムに適用できる設計パターンを抽出できます。同時に、スナップショットを完全なソースコードや実行可能な製品と誤認することも避けられます。