# Cloud Skills ガイド

接続されたエージェント間で、再利用可能な手続き型スキルを作成、レビュー、公開し、段階的にリコールします。

- Canonical: https://docs.xmemo.dev/ja/docs/guides/cloud-skills
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: bff532eedc870bca9f5f7c7413891d20ab5e233fb9fdcccd4e6d38b38aba2d9e
- Edition-Digest: 3034fea007e66974e07fbb8a9cb8bdc8785a1e7ab920e17149b66825c94ab38d
- Source-Revision: sha256:2ed8d0fb7f3432c8695de21a099b7ce6fd715f59effbe3a2bb60822a68e1af34

## ユーザーの目標

手動でのコピー＆ペースト、エージェントごとの重複設定、コンテキストウィンドウの肥大化を招くことなく、接続されたエージェント間で再利用可能な手続き型スキル（ランブック、チェックリスト、標準運用手順書など）を作成、レビュー、公開、およびリコールします。

## 利用資格と前提条件

Cloud Skills は現在、Memory Console の https://xmemo.dev/me#skills にて Preview 提供されています。スキルを作成またはリコールする前に、ご使用の環境が次の要件を満たしていることを確認してください:

- 機能の有効化: アカウントで手続き型 Cloud Skills が有効化されている場合にアクティブになります。
- ワークスペースの選択: 個人スペース (https://xmemo.dev/me#skills) にはプライベートなスキルが保存されます。チームスペース (https://xmemo.dev/me?space=<team_id>#skills) では、ロールベースのガバナンスのもとで認証済みチームメンバー間でスキルが共有されます。
- エージェントトークンスコープ: エージェントのリコールには skills:read または memory:read スコープが必要です。スキルの作成およびリビジョンの公開には skills:write または memory:write スコープが必要です。
- サポートされているクライアントプロファイル: MCP ツール recall_cloud_skill および save_cloud_skill は、cursor-plugin および ordinary-full クライアントプロファイルで公開されています。一般的な公開インターフェースやチャットインターフェースではスキルオーサリングツールは直接公開されません。

## 1. Memory Console の Cloud Skills に移動する

Memory Console を開き、Cloud Skills セクションを選択します:

- 個人スペース: 個人用の手続き型ランブックを管理するには https://xmemo.dev/me#skills を開きます。
- チームスペース: 組織で共有されるスキルを管理するには https://xmemo.dev/me?space=<team_id>#skills を開きます。
- コンソールインターフェース: パネルにはスキル一覧、検索バー ("Search skills by name, slug, or keywords...")、および主要アクション ("New Skill" と "Import Skill") が表示されます。

## 2. 手続き型スキルと宣言されたコンポーネントを作成する

"New Skill" をクリックしてスキル作成モーダルを開きます。スキルのメタデータ、ルート指示、およびコンポーネントリソースを設定します:

- Skill Name: "Incident Response Checklist" と入力します (必須フィールド)。
- Slug: 小文字の識別子 "incident-response-checklist" を入力します (1〜64文字の英数字またはハイフン)。
- Description: "Standard operating procedure for triaging and resolving high-severity production incidents." と入力します。
- Instructions: Markdown でルート手続きガイダンスを作成します (64 KiB UTF-8 に制限)。
- Components: インシデントアンケートを含む type template のテンプレートコンポーネント templates/triage-template.md を追加します。

```markdown
# Incident Response Checklist

When a high-severity production alert triggers:
1. Identify the impacted service and declare an incident channel.
2. Verify service error rates and recent deployment events.
3. Complete the triage questionnaire at `templates/triage-template.md`.
4. Apply documented mitigation or initiate canary rollback.
5. Record timeline events and assign follow-up action items.
```

## 3. スキルリビジョンをレビューして公開する

スキルリビジョンを保存し、個人スペースとチームスペースで公開がどのように動作するか確認します:

- 個人での公開: 個人ワークスペースでは、公開の意図を持って保存するとリビジョン v1 が直接 "Published" に遷移し、承認されたエージェントから即座に発見可能になります。
- チームレビューワークフロー: チームワークスペースでは、保存するとステータス "proposed" のリビジョン v1 が作成されます。チームメンバーは指示を確認し、コンポーネントの差分を検査し、チームオーナーまたは管理者がリビジョンを公開する前に実行をテストできます。
- 下書きステージング: 公開のチェックを外して保存した場合、リビジョンは "Draft" ステータスのままとなり、エージェントによる検出に公開されることなくプライベートな編集とテストを行えます。

## 4. エージェントの段階的リコールを検証する

接続されたエージェントは、コンテキストバジェットを節約するために3つの段階的レベルにわたってオンデマンドで公開スキルを照会および取得します:

- レベル 0 (検出): エージェントはタスククエリで検索し、完全な指示を含まない軽量な記述子を受け取ります。
- レベル 1 (ルート指示): エージェントはスキルスラッグを使用してルート指示とコンポーネントマニフェストをリコールします。
- レベル 2 (固定リソース): エージェントはレベル 1 から返された正確な revision_id を提供して、宣言されたテンプレートコンポーネントを取得します。

```text
# Level 0: Discover relevant skills by task query
recall_cloud_skill(query="incident response")

# Level 1: Retrieve root instructions and component manifest
recall_cloud_skill(slug="incident-response-checklist")

# Level 2: Retrieve pinned component resource without resource tearing
recall_cloud_skill(
  slug="incident-response-checklist",
  revision_id="<revision-id-from-level-1>",
  resource="templates/triage-template.md",
)
```

## 5. 手順を更新しリビジョンの不可変性を確認する

運用の要件が変更されたら、スキルを更新して新しい不可変リビジョンを作成します:

- スキル詳細を開く: コンソールで "Incident Response Checklist" を選択し、"New Revision" をクリックします。
- 指示を変更する: ロールバックを実行する前に、必須のカナリア検証ステップを追加します。
- 新しいリビジョンを保存する: コンテンツを保存するとリビジョンカウンターが v2 にインクリメントされ、新しい不可変な revision_id および canonical_hash が生成されます。
- リビジョン固定による保護: リビジョン v1 に固定された進行中のエージェントワークフローはデータ破損なく v1 リソースを読み取り続け、新しいレベル 1 クエリは公開された v2 リビジョンを自動的に解決します。

## 観察可能な結果

Cloud Skill の作成と公開が成功すると、コンソールとエージェントインターフェース全体で観察可能な変化が生じます:

- コンソールステータスバッジ: スキルカードに "Published" バッジ、アクティブリビジョンタグ (v1 や v2 など)、およびコンポーネント数が表示されます。
- リソースエクスプローラー: 詳細ビューには、宣言された templates/triage-template.md コンポーネントが構文プレビューおよびコピーアクションとともに表示されます。
- エージェントリコールエンベロープ: レベル 1 は instruction_body、revision_id、および resources リストを含む型付きルートレスポンスを返します。レベル 2 は正確なコンポーネントテキストを返します。
- エクスポートの可用性: 詳細ビューで "Export" をクリックすると、SKILL.md、マニフェストメタデータ、および宣言されたコンポーネントを含む Source Capsule ZIP アーカイブがダウンロードされます。

## エージェントがアクセスできる範囲

エージェントと人間のユーザーは、厳格な認証および権限境界のもとで動作します:

- クライアントプロファイル: MCP ツール recall_cloud_skill および save_cloud_skill は、cursor-plugin および ordinary-full プロファイルで契約上公開されています。一般的な公開およびチャットクライアントプロファイルでは公開されません。
- スコープの強制: エージェントは skills:read または skills:write スコープを持つ API キーまたは OAuth トークンで認証します。個人メモリにスコープされたトークンは、明示的にバインドされていない限りチームスキルを検査できません。
- 下書きおよび提案の保護: エージェントは、レベル 0 クエリ検出において、下書きリビジョン、レビュー待ちの提案リビジョン、またはアーカイブされたスキルを発見またはリコールすることはできません。
- プロンプト実行可能なガイダンス: 接続されたエージェントは、手続き型の指示をプロンプトコンテキストとして直接解釈します。スキルがホスト上で自動的にコードを実行することはありません。

## 共有とライフサイクルの境界

Cloud Skills は、個人用ランブックと共同チームアセットの間で明確なテナント分離を維持します:

- スペースの境界: 個人スキル (/me#skills) は作成者に対してプライベートです。チームスキル (?space=<team_id>#skills) は認証されたチームメンバーと共有されます。
- チームの承認: チームリビジョンは、ステータスが "proposed" から "published" に遷移する前にオーナーまたは管理者によるレビューが必要です。
- アーカイブと削除の比較: スキルをアーカイブする (DELETE /v1/skills/{skill_id}) と、エージェントによる検出が無効化され、アクティブ一覧から非表示になりますが、不可変なリビジョン履歴は保持されます。
- リビジョンの不可変性: リビジョンは不変のコンテンツアドレス指定スナップショットです。更新を保存すると、既存のレコードを上書きするのではなく新しいリビジョンが作成されます。
- 候補レビューバナー: 候補が存在する場合、コンソールに Promote および Dismiss アクションを含む候補バナーを表示できます。候補には手動レビューが必要です。

## 障害復旧

次の修復手順を使用して、Cloud Skill の一般的な問題を診断および解決します:

- リソースリコールエラー (REVISION_PINNING_VIOLATION): レベル 2 のリソースリクエストには明示的な revision_id が必要です。省略された場合、サーバーはデータ破損を防ぐためにリクエストを拒否します。修正方法: レベル 1 レスポンスで返された revision_id を渡してください。
- スキルが見つからない (SKILL_NOT_FOUND): スラッグが完全に一致していること、およびクエリが適切なワークスペース (Personal 対 Team ?space=<team_id>) で実行されていることを確認してください。
- アクセス拒否 (403 Forbidden): エージェントトークンに skills:read (リコール用) または skills:write (保存用) が含まれていること、および認証されたユーザーが対象チームに所属していることを確認してください。
- チームリビジョンが提案状態のまま残る: チームスキルを照会するエージェントは、チームオーナーまたは管理者が提案されたリビジョンをレビューして公開するまで、現在公開されているリビジョンを受け取ります。
- ランタイム利用不可 (503): デプロイ環境で Cloud Skills サブシステムが無効化されているか未設定の場合に返されます。

## 関連リファレンス

概念アーキテクチャ、ツールパラメータ、およびチームコラボレーションについては、関連ドキュメントを参照してください:

- Cloud Skills の概念: 3層アーキテクチャ、コンポーネントモデル、およびリビジョン固定については /docs/concepts/cloud-skills を参照してください。
- recall_cloud_skill リファレンス: パラメータスキーマおよびレスポンス形式については /docs/tools/recall-cloud-skill を参照してください。
- save_cloud_skill リファレンス: 作成パラメータおよびコンポーネントアップロード形式については /docs/tools/save-cloud-skill を参照してください。
- Memory Console: Web コンソールのレイアウト、スペース選択、および設定については /docs/guides/memory-console を参照してください。
- Teams: チームワークスペースのコラボレーションおよびロール権限については /docs/capabilities/teams を参照してください。

## ChatGPT ユーザー

bearer token をチャットに貼り付けずに、ChatGPT が XMemo の設定、プロジェクト事実、意思決定、TODO に永続的にアクセスできるようにします。

ChatGPT/OpenAI app の OAuth フローで hosted XMemo MCP server に接続し、XMemo アカウントに memory:read と memory:write の許可を承認します。

合成の設定またはプロジェクトメモを保存し、新しいチャットを開始してから、作業を続ける前に ChatGPT に XMemo 経由でそれを呼び出させます。

OAuth が失敗する、またはツールが表示されない場合は、direct token を作成する前に、ホストアプリで MCP server からサインアウトし、XMemo server URL を再接続して再試行します。

## Copilot / Codex 開発者

リポジトリの判断、コーディング規約、バグ修正メモ、タスク履歴を IDE と CLI エージェント間で持ち運べます。

利用可能な場合は、VS Code / GitHub Copilot および Gemini CLI に OAuth を使用してください。Copilot CLI、Codex、Cursor、またはその他の直接 MCP クライアントの場合は、XMEMO_KEY をローカル環境またはシークレットストアに保持し、安定した XMEMO_AGENT_INSTANCE_ID を設定してください。

コードベースの判断またはバグ修正を記録し、次の IDE または CLI エージェントに、編集前に関連する XMemo コンテキストを呼び出させます。

呼び出し結果が空の場合は、選択した MCP 設定パス、direct client 用の XMEMO_KEY 環境変数、ホストアプリ内の古い OAuth 認証情報を確認します。

## チーム / エンタープライズ pilot owner

アカウント制御、ソース attribution、エクスポート/削除ワークフロー、レビュー担当者向けに安全な設定証跡で共有メモリを評価します。

保護された XMemo workspace を作成または開き、承認済みユーザーを招待してから、readiness badges に従って OAuth またはスコープ付き direct credential で各クライアントを接続します。

pilot メンバーに合成のチームメモリを保存してもらい、XMemo でソース attribution を確認し、削除/エクスポートとサポート経路をレビューします。

メンバーが接続できない場合は、新しい token を発行する前に、ロール権限、OAuth 承認、クライアント readiness 状態、サポートガイダンスを確認します。

## 自律エージェント operator

headless またはスケジュール済みエージェントが進捗を記録し、過去の判断を取得し、安定した非秘密のインスタンス ID を保持できるようにします。

/api/v1/mcp/config/autonomous-agent を取得します。runner が OAuth + custom headers をサポートする場合は auth_modes.oauth を優先し、完全 headless runner の場合のみ secret store の XMEMO_KEY で auth_modes.xmemo_key を使います。

XMemo に進捗を書き込む合成タスクを 1 つ実行し、runner を再起動して、同じ XMEMO_AGENT_INSTANCE_ID でその進捗を呼び出せることを確認します。

attribution が変わる、または呼び出し結果がインスタンス間で分かれる場合は、XMEMO_AGENT_INSTANCE_ID を git の外に永続化し、runner が起動ごとに再生成していないことを確認します。