heygen-avatar

HeyGen アバターデザイナー

エージェント、ユーザー、名前付きキャラクターなど、誰の HeyGen アバターでも作成・管理できます。アイデンティティの抽出、アバターの生成、音声の選択に対応し、一貫して再利用できるようすべてを AVATAR-<NAME>.md に保存します。

ファイルとパス

このスキルでは、以下のファイルを読み書きします。ユーザーから明示的な指示がない限り、その他のファイルにはアクセスしません。

操作	パス	目的
読み取り	SOUL.md、IDENTITY.md	エージェントのアバター作成時にアイデンティティの詳細を抽出します
読み取り	AVATAR-<NAME>.md	既存のアバターのアイデンティティを読み込みます（外見のバリエーション、音声の更新用）
書き込み	AVATAR-<NAME>.md	作成後の新しいアバターのアイデンティティを保存します
書き込み	AVATAR-AGENT.md、AVATAR-USER.md（シンボリックリンク）	役割のエイリアス。フェーズ 5 を参照してください
一時書き込み	/tmp/openclaw/uploads/	音声プレビュー（ユーザーが再生できるようダウンロードし、セッション後に削除します）
リモートへのアップロード	HeyGen（heygen asset create または MCP 経由）	ユーザー提供の写真を HeyGen にアップロードし、デジタルツインを作成します

ユーザーが明示的に提供したアセットのみ、HeyGen にアップロードします。

言語の認識

最初のメッセージからユーザーの言語を検出します。 user_language として保存します（例：en、ja、es、ko、zh、fr、de、pt）。

1. ユーザーの言語で会話します。 質問、進捗状況の更新、確認、エラーメッセージはすべて user_language で伝えます。
2. 音声のデザインプロンプトと選択では user_language を考慮します。 音声をデザインまたは選択する際は、対象言語を指定し、その言語を話す音声が音声ライブラリから返されるようにします。
3. 技術的な指示は英語のままにします — 列挙値（Young Adult、Realistic、landscape など）は API レベルの値であり、翻訳しません。

UX のルール

1. 簡潔にします。 チャットでアバター ID、グループ ID、生の API ペイロードを提示しません。内部の仕組みではなく、結果（アバターを作成し、使用できる状態になったこと）を伝えます。
2. 内部用語を使いません。 内部のフェーズ名（「Phase 0」「Phase 5 Symlink Maintenance」など）をユーザーに伝えてはいけません。「フェーズ 2 のアバター作成を実行しています」ではなく、「アバターを設定しています…」のような自然な会話にします。
3. 各フェーズで質問は 1 つか 2 つにします。 質問をまとめて一度にしないでください。フェーズを順番に進め、続行に必要な最小限の質問をします。
4. 質問する前にワークスペースのファイルを読みます。 ワークスペースのルートにある SOUL.md、IDENTITY.md、AVATAR-*.md にはアイデンティティが記載されています。まずこれらを確認し、本当に不足している情報だけをユーザーに尋ねます。
5. スキル内部の手順を説明しません。 「ワークフローを読みます」「参照ファイルを確認しています」「アバターの調査ガイドを読み込んでいます」と言ってはいけません。黙って読み込みます。ユーザーに見せるのは質問と結果であり、内部の操作ではありません。
6. これから行うことを予告しません。 「これからアバターを作成します」のようなメタコメントは省き、作業を進めます。時間のかかる手順がある場合、次にユーザーが聞くのは結果（または進行を確認する質問）にします。
7. 通信手段の選択について説明しません。 MCP と CLI の選択は内部処理です。黙って通信手段を選び、ユーザーには伝えません。どちらも利用できない場合は、理由を説明せず、設定を依頼します。

まずここから（重要）

デフォルトの対象はエージェントです。 このスキルの主な用途は、エージェントに表情と声を与え、動画をプレゼンできるようにすることです。「自分のアバター」「私」「自分の写真」と明示された場合に限り、対象を「ユーザー」にしてください。迷った場合は、エージェントのアバターを作成してください。

質問をまとめて一度にしないでください。 「写真、声の好み、長さ、対象プラットフォーム、トーン、伝えたいメッセージを教えてください」のように、すべてを一度に尋ねてはいけません。フェーズを順番に進め、各フェーズで尋ねることは一度に1つか2つまでにしてください。

エージェントのアバターを作る場合は、まず SOUL.md と IDENTITY.md を読み、その後すぐにプロンプトベースの作成に進んでください。 最初に写真や外見の詳細をユーザーに尋ねてはいけません。エージェントのアイデンティティは、ワークスペース内のこれらのファイルに記載されています。本当に不足している特徴だけをユーザーに尋ねてください。

作成方法のデフォルトはプロンプトベースです。 写真を使うのは、ユーザーが自分自身の実在人物のデジタルツインを明示的に希望する場合に限られます。エージェントや名前のあるキャラクターは、ほぼ常にプロンプトベースで作成します。

開始前（環境の検出）

ワークスペースのルートから SOUL.md を読み取ってみてください。

• 見つかった場合 → OpenClaw 環境です。このセクション全体をスキップして、フェーズ 0 に進んでください。ワークスペースにあるアイデンティティファイル（SOUL.md、IDENTITY.md）を使って、エージェントのオンボーディングを行います。
• 見つからない場合 → ワークスペースにアイデンティティファイルがない Claude Code 環境です。次はフェーズ 0 に進んでください。ユーザーのアバター一覧の表示や、ユーザーへの写真の依頼に先走ってはいけません。

⚠️ AVATAR ファイルに関する注意： ワークスペース内で見つかった AVATAR-*.md ファイルが、別の人物やエージェント（たとえば、Claude のアバターを作成する際の AVATAR-Eve.md）のものであれば、無視してください。現在作成対象としている人物にファイル名が一致する AVATAR ファイルのみ使用してください。

⚠️ まだ HeyGen のアバターを取得しないでください。 アバターの取得はフェーズ 0 のサブステップであり、対象を特定した後にのみ行います。フェーズ 0 より前に取得すると、デフォルトではエージェント自身のアバターを作るはずなのに、「既存のアバター」について会話を進めてしまいます。

API モードの検出

モードの選択は内部で行います。 セッションの最初に一度だけ検出してモードを選び、そのまま進めてください。通信方法の選択について説明してはいけません（「CLI が動きません」「MCP に切り替えます」など）。ユーザーは呼び出し方法を気にしていません。

MCP（推奨）： HeyGen MCP ツール（mcp__heygen__* に一致するツール）が利用可能な場合は、それらを使用してください。MCP は OAuth で認証するため、API キーは不要です。ユーザーが現在利用している HeyGen プランのクレジットで実行されます。

CLI のフォールバック： MCP ツールが利用できず、heygen バイナリが正常に実行できる（heygen --version が 0 で終了する）場合は、CLI を使用してください。認証には、HEYGEN_API_KEY 環境変数または heygen auth login（認証情報を ~/.heygen/credentials に保存）を使用します。CLI が見つからない場合、--version でエラーになる場合、または認証が設定されていない場合は、何も言わずにスキップしてください。MCP を再試行してはいけません。

どちらも利用できない場合： MCP が利用できず、CLI も動作しない場合に限り、ユーザーに一度だけ次のように伝えてください。「このスキルを使うには、HeyGen MCP サーバーに接続するか、HeyGen CLI をインストールしてください：curl -fsSL https://static.heygen.ai/cli/install.sh | bash を実行し、その後 heygen auth login を実行してください。」

API： v3 のみを使用してください。v1 または v2 のエンドポイントを呼び出してはいけません。

ドキュメントを先に確認するルール： 詳細が不明なエンドポイントを呼び出す前に、次のいずれかを行ってください。

• インデックス： GET https://developers.heygen.com/llms.txt — サイトマップ全体
• 任意のページ： URL の末尾に .md を追加すると、整形された Markdown を取得できます
• または heygen <noun> <verb> --help を実行してください
• 仕様を読み、それからリクエストを作成してください。フィールド名を推測してはいけません。

アバターファイルの規約

各アバターにつき、ワークスペースのルートに AVATAR-<NAME>.md ファイルを1つ用意します。

AVATAR-EVE.md      ← agent      (named, canonical)
AVATAR-KEN.md      ← user       (named, canonical)
AVATAR-CLEO.md     ← character  (named, canonical)

このスキルでは、名前付きファイルに加えて、コンシューマースキル（heygen-video など）が、リクエストに特定の名前が含まれていない場合に汎用的な検索を行えるよう、役割ベースのシンボリックリンクも2つ管理します（「自分の動画を作って」→ エージェントのエイリアスを読み込む、「私の動画を作って」→ ユーザーのエイリアスを読み込む）。

AVATAR-AGENT.md → AVATAR-<CURRENT-AGENT-NAME>.md   (symlink)
AVATAR-USER.md  → AVATAR-<CURRENT-USER-NAME>.md    (symlink)

名前付きファイルが唯一の情報源であり、エイリアスはポインターとして機能し、食い違うことはありません。ワークフローのフェーズ5でこれらを管理します。名前付きキャラクターには役割エイリアスを作成しません。名前だけで参照します。

フォーマット：

# Avatar: <Name>

## Appearance
- Age: <natural language>
- Gender: <natural language>
- Ethnicity: <natural language>
- Hair: <natural language>
- Build: <natural language>
- Features: <natural language>
- Style: <natural language>
- Reference: <optional workspace-relative path or URL>

## Voice
- Tone: <natural language>
- Accent: <natural language>
- Energy: <natural language>
- Think: <one-line analogy>

## HeyGen
- Group ID: <character identity anchor — THE stable reference, never changes>
- Voice ID: <matched or designed voice>
- Voice Name: <human-readable>
- Voice Designed: <true if custom-designed, false if picked from catalog>
- Voice Seed: <seed value used, if designed>
- Looks: landscape=<look_id>, portrait=<look_id>, square=<look_id>
- Last Synced: <ISO timestamp>

⚠️ look_ids are ephemeral — always resolve fresh from group_id at runtime via `heygen avatar looks list --group-id <id>` (or MCP `list_avatar_looks`). Never hardcode look_id as the primary avatar reference.

上部のセクション（Appearance、Voice）は、どのプラットフォームでも使える自然言語です。 HeyGen セクションは、API ID を含むランタイム設定です。スキルはこれを読み取って API を呼び出します。

スキルの告知

毎回の実行開始時に、次のように表示します。

🎭 使用中：heygen-avatar — [name] のアバターを作成しています

ワークフロー

事前に質問をまとめて行わないでください。 順にフェーズを進めます。各フェーズでは、一度に質問を最大1つだけ行い、必要な場合に限って質問します。

フェーズ 0 — 誰のアバターを作成しますか？

デフォルトでエージェントを対象とするルールについては、上記の「Start Here」ブロックを参照してください。表現が明確な場合に限り、「ユーザー」または「名前付きキャラクター」に振り分けます。

振り分けの手掛かり（優先度順）：

1. ユーザー（明示されている場合のみ）— 「create my avatar」「make me an avatar」「I want my face in a video」「a digital twin of me」「based on my photo」などです。ユーザー自身を指す所有格の代名詞、またはユーザーの写真への明示的な言及が必要です。名前が明らかでない場合は、名前を尋ねます。
2. 名前付きキャラクター（明示されている場合のみ）— 「create an avatar called Cleo」「design a character named X」「build a presenter named Y」などです。指定された名前を使います。
3. エージェント（デフォルト）— その他すべてです。「create your avatar」「bring yourself to life」「set up an avatar」「let's make an avatar」「create an avatar」「design a presenter」「I want you to appear in videos」など、または曖昧な表現が該当します。名前を確認するために IDENTITY.md を読みます。

判断に迷ったら、エージェントをデフォルトにします。 曖昧なリクエストに対して、ユーザーの名前、外見、声を尋ねないでください。それは最初にすべきことではありません。IDENTITY.md と SOUL.md を読んでも意図が曖昧な場合は、振り分けるための短い確認質問を1つ尋ねます（「念のため確認ですが、このアバターはあなた用ですか、それとも私用ですか？」のように自然な表現にします）。

次に、ワークスペースのルートにある AVATAR-<NAME>.md を確認します。

• AVATAR ファイルが存在し、HeyGen セクションに情報が入力されている → 「アバターはすでに設定されています。新しい外見を追加しますか、更新しますか、それとも最初から作り直しますか？」と尋ねます。回答を待ちます。
• AVATAR ファイルは存在するが、HeyGen セクションが空 → フェーズ 2 に進みます。
• AVATAR ファイルが存在しない → フェーズ 1 に進みます。

役割エイリアスの古さを確認します。 先に進む前に、この対象の役割エイリアスが正しい名前付きファイルを指しているかも確認します。

• エージェントが対象の場合：AVATAR-AGENT.md を読み込み（シンボリックリンクをたどり）、AVATAR-<CURRENT-AGENT-NAME>.md と比較します。異なる場合（たとえば、前回の実行後にエージェントの ID が変わったため、AVATAR-AGENT.md → AVATAR-OLD-NAME.md となっている場合）、ほかに変更がなくてもフェーズ 5 でリンクを更新します。名前付きファイルが正規のファイルですが、エイリアスは過去のものではなく、現在の ID と一致している必要があります。
• ユーザーが対象の場合：AVATAR-USER.md について同じ確認を行います。
• 名前付きキャラクターの場合：確認するエイリアスはありません。

任意の既存アバターの確認（ユーザーが HeyGen アカウントにすでにアバターを持っている可能性がある場合に、ユーザーの経路でのみ有用です）。フェーズ 0 の対象がユーザーで、AVATAR-<USER>.md が存在しない場合は、まず HeyGen のアバターを一覧表示します。

MCP: list_avatar_groups(ownership=private) CLI: heygen avatar list --ownership private

一覧が空でなければ、選択肢を提示し、どれを使うか、または新しく作成するかを尋ねます。空の場合はフェーズ 1 に進みます。アバターは AVATAR-*.md に記録されており、HeyGen のカタログにはないため、エージェントと名前付きキャラクターの対象ではこの確認を完全に省略します。

フェーズ 1 — アイデンティティの抽出

順序が重要です。まずファイルを確認し、その後に質問します。プロンプトによる作成がデフォルトの方法で、写真は任意のアップグレードです。

エージェントの場合（フェーズ 0 の対象 = エージェント）：

1. ワークスペースのルートから SOUL.md、IDENTITY.md、既存の AVATAR-<NAME>.md を読み込みます。
2. SOUL.md または IDENTITY.md が見つかった場合 → 外見と声の特徴を静かに抽出します。ユーザーに「外見を説明してください」と尋ねてはいけません。エージェント自身が対象であり、そのアイデンティティはこれらのファイルに記されています。ファイルに性格や価値観のみが記載され、身体的な特徴がない場合は、特徴をでっち上げてはいけません。 不足している外見の特徴だけを、会話の中で自然にユーザーに尋ねます（一度に 1、2 項目）。
3. どちらのファイルも見つからない場合（例：ワークスペースのアイデンティティがない Claude Code 環境）→ エージェントの外見と声について、会話の中で自然にユーザーに尋ねます。
4. デフォルトでは、フェーズ 2 のタイプ A（プロンプト）による作成に直接進みます。ユーザーが自発的に写真を提供するか、写真のようなリアルさを明示的に求めない限り、写真を求めてはいけません。エージェントでは、ほとんどの場合プロンプトによる作成を使用します。

ユーザー／名前付きキャラクターの場合（フェーズ 0 の対象 = ユーザーまたは名前付きキャラクター）：

• 会話形式でオンボーディングします。外見と声について自然に尋ねます。フォームのようにまとめて質問せず、一度に 1、2 項目ずつ尋ねます。user_language でやり取りします。
• ユーザーの場合のみ： オンボーディングの Q&A の後、以下の参照写真の確認を行います。
• 名前付きキャラクターの場合： 確認は省略し、タイプ A（プロンプト）による作成に直接進みます。

AVATAR-<NAME>.md を作成し、「Appearance」と「Voice」のセクションに情報を入力します。フェーズ 2 が成功するまでは、「HeyGen」セクションを空欄にしておきます。

参照写真の確認（ユーザーの場合のみ）

フェーズ 0 の対象がユーザー（実在の人物のデジタルツイン）の場合、またはユーザーが写真のようなリアルさを明示的に求めた場合にのみ、この手順を実行します。

• まず、AVATAR ファイルの Appearance → Reference フィールドを確認します。写真がすでに保存されている場合は、確認を省略してそれを使用します。
• それ以外の場合は、1 文で尋ねます。「顔写真はありますか？動画であなたの顔の一貫性を高められます。説明をもとに生成することもできます。『スキップ』とお伝えください。」

分岐：

• 写真を提供 → MCP の upload_asset または heygen asset create --file <path> でアップロードし、フェーズ 2 でタイプ B（写真）による作成を行います。
• スキップ → フェーズ 2 でタイプ A（プロンプト）による作成を行います。

エージェントと名前付きキャラクターの場合は、この手順全体を省略し、タイプ A（プロンプト）による作成に直接進みます。

フェーズ 2 — アバターの作成

📖 作成 API の全仕様（写真／プロンプト／デジタルツイン）、ファイル入力形式、ID フィールドから列挙値へのマッピング、レスポンス形式 → references/avatar-creation.md

作成モードは 2 つです。

モード 1 — 新しいキャラクター（avatar_group_id を省略）： 独自のグループを持つ、まったく新しいキャラクターを作成します。

モード 2 — 新しい外見（avatar_group_id を指定）： 既存のキャラクターにバリエーションを追加します。AVATAR ファイルから Group ID を読み取ってください。

作成タイプは 2 つです。

タイプ A — プロンプトから作成（AI が外見を生成）：

MCP： create_prompt_avatar(name=<name>, prompt=<appearance>, avatar_group_id=<optional>) CLI： heygen avatar create -d '{"type":"prompt","name":"...","prompt":"...","avatar_group_id":"..."}'（インライン JSON、ファイルパス、または標準入力を示す - を指定できます）

プロンプトは 1000 文字までです。スタイル、特徴、表情、照明などを含め、具体的に記述してください。API 仕様には 200 と記載されていますが、実際に適用される上限は 1000 文字です。

タイプ B — 参照画像から作成：

MCP： create_photo_avatar(name=<name>, file=<file_object>, avatar_group_id=<optional>) CLI： heygen avatar create -d '{"type":"photo","name":"...","file":{"type":"url","url":"..."},"avatar_group_id":"..."}'

タイプ B のファイルオプション：

• { "type": "url", "url": "https://..." } — 公開画像 URL
• { "type": "asset_id", "asset_id": "<id>" } — heygen asset create --file <path> で作成したアセット
• { "type": "base64", "media_type": "image/png", "data": "<base64>" } — インライン指定

📖 URL、asset_id、base64 の使い分け、アップロードのルーティング、エッジケース → references/asset-routing.md

レスポンス： .data.avatar_item.id（ルック ID）と .data.avatar_item.group_id（キャラクターの ID）が返されます。

プロンプトでは、ID フィールドを HeyGen の列挙値にマッピングしてください。

• 年齢：Young Adult | Early Middle Age | Late Middle Age | Senior | Unspecified
• 性別：Man | Woman | Unspecified
• 民族：White | Black | Asian American | East Asian | South East Asian | South Asian | Middle Eastern | Pacific | Hispanic | Unspecified
• スタイル：Realistic | Pixar | Cinematic | Vintage | Noir | Cyberpunk | Unspecified
• 向き：square | horizontal | vertical
• ポーズ：half_body | close_up | full_body

作成前に、プロンプトをユーザーに提示してください。

外見：「[prompt]」 **設定：**Young Adult | Woman | East Asian | Realistic この内容でよいですか？（はい／調整／まったく別の内容）

⛔ 停止してください。ユーザーの承認または調整を待ってください。ユーザーが確認するまで、アバター作成 API を呼び出してはいけません。

フェーズ 3 — 音声

方法は 2 つあります。デザイン（希望を説明して、条件に合う音声を取得）またはカタログを閲覧（カタログを手動で絞り込み）です。

音声をデザインする（希望を説明する）か、カタログを閲覧するかを尋ねてください。user_language でやり取りしてください。

AVATAR ファイルに性格特性を記載した Voice セクションがある場合は、デフォルトでデザインを選択してください。

パス A — 音声デザイン（推奨）

AVATAR ファイルの Voice セクションを使って、セマンティック検索で一致する音声を見つけます。HeyGen の音声ライブラリ全体が検索対象です。新しい音声は生成されず、クォータも消費しません。

言語の一致： 音声デザインのプロンプトには、user_language のターゲット言語を指定してください。日本語の場合の例：「落ち着いた、温かみのある女性の声。プロフェッショナルで親しみやすい。日本語話者。」これにより、セマンティック検索で適切な言語の音声が返されます。

MCP： design_voice(prompt=<voice description>, seed=0) CLI： heygen voice create --prompt "..." --seed 0（--gender、--locale も指定できます）

シードごとに3つの音声候補が返されます。すべての候補をインライン音声プレビュー付きで提示します：

• 各 preview_audio_url を一時パスにダウンロードします（一般的なダウンロード方法であればどれでも使用できます。HeyGen の認証は不要です。公開 S3 URL です）
• 音声添付ファイルとして送信します：message(action:send, media:"<path>", caption:"Option <n>: <voice_name> — <gender>, <language>")。Telegram／Discord でインライン再生されます
• すべてのプレビューを送信した後、選択ボタンを提示します

⛔ 停止してください。ユーザーがボタンまたはテキストで音声を選ぶまで待ちます。ユーザーが明示的に選択するまで、自分で音声を選んだり、フェーズ 4 に進んだりしないでください。

どれも合わない場合：

「どれもしっくりきませんか？別の候補（同じ説明で異なるバリエーション）を試すことも、説明を調整することもできます。」

seed を増やして再度呼び出します。シードを変えると、同じプロンプトでもまったく異なる音声候補が返されます。

• ユーザーが選択した後、/tmp ファイルを削除します

パス B — 音声ブラウズ（フォールバック）

HeyGen の既存の音声ライブラリを参照します：

MCP： list_voices(type=private) の後に list_voices(type=public, language=<lang>, gender=<gender>) CLI： heygen voice list --type private ／ heygen voice list --type public --language <lang> --gender <gender>

1. AVATAR ファイルの Voice セクションを読みます
2. 性別と言語で絞り込みます
3. パーソナリティの一致度に基づいて上位3件の候補を選びます
4. インライン音声プレビュー付きで提示します（パス A と同じダウンロード・送信方法）
5. ⛔ 停止してください。ユーザーが選ぶまで待ちます。自動で選択しないでください。

フェーズ 4 — AVATAR ファイルに保存

AVATAR-<NAME>.md の HeyGen セクションを、標準形式に合わせて更新します：

## HeyGen
- Group ID: <.data.avatar_item.group_id — THE stable reference, never changes>
- Voice ID: <chosen voice_id>
- Voice Name: <voice name>
- Voice Designed: <true if custom-designed, false if picked from catalog>
- Voice Seed: <seed value used, if designed>
- Looks: <orientation>=<.data.avatar_item.id> (e.g., landscape=<look_id>, portrait=<look_id>)
- Last Synced: <ISO timestamp>

⚠️ look_ids are ephemeral — always resolve fresh from group_id at runtime via `heygen avatar looks list --group-id <id>` (or MCP `list_avatar_looks`). Never hardcode look_id as the primary avatar reference.

アバターが保存されたことと、heygen-video などの他のスキルが自動的に反映することを確認します。user_language で伝えてください。

フェーズ 5 — ロールエイリアスを維持する

名前付きの AVATAR-<NAME>.md を書き込んだ後、同じ場所にロールベースのシンボリックリンクを作成または更新し、他のスキルがエージェント／ユーザーの名前を先に解決せずに汎用的な参照を行えるようにします。

フェーズ 0 の対象に基づいて、次のようにします。

• エージェントが対象 → AVATAR-AGENT.md から AVATAR-<NAME>.md へのシンボリックリンクを作成します
• ユーザーが対象 → AVATAR-USER.md から AVATAR-<NAME>.md へのシンボリックリンクを作成します
• 名前付きキャラクター → ロールエイリアスは作成しません。名前付きキャラクターは名前のみで参照します（例：AVATAR-CLEO.md）。エージェントでもユーザーでもありません。

実装（fs-fallback を使用し、ワークスペースのルートから実行）：

ワークスペースのルートへの cd は必須です。ln -s の相対パスは、SOUL.md のある場所ではなく、エージェントの現在の作業ディレクトリを基準に解決されるためです。|| echo 節は、シンボリックリンクを拒否するファイルシステム（開発者モードが無効な Windows や、一部のクラウドマウントストレージなど）でも、フェーズ 5 を中断せずに処理できるようにします。

# Agent
cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-AGENT.md \
  || echo "role alias skipped: fs doesn't support symlinks"

# User
cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-USER.md \
  || echo "role alias skipped: fs doesn't support symlinks"

ワークスペースの移動やコピー後もエイリアスが機能するように、リンク先には相対パス（ファイル名のみ。パスの接頭辞は付けません）を使用します。

内部では ln -sf はリンク解除後にシンボリックリンクを作成するため、厳密にはアトミックではありません。シングルユーザーのワークスペースでは問題ありません。同じエイリアスに複数のエージェントが同時に書き込むようになった場合は、処理の混在を想定し、その時点で明示的なロックを追加してください。

コピーではなくシンボリックリンクを使う理由： 重複ファイル間で内容が食い違う問題をなくします（名前付きファイルとエイリアスの内容が異なることはありません）。ただし、古い情報が残る問題は解消しません。IDENTITY.md でエージェント名が変更されても、heygen-avatar を再実行しなければ、AVATAR-AGENT.md は以前の名前付きファイルを指し続けます。次回の実行時にフェーズ 0 の不一致検出とエイリアス再設定で対処します。それまでは、エイリアスは古いものの有効なリンク先を指しており、リンク切れではありません。

マルチエージェントのワークスペースに関する注意： ワークスペースごとにロールエイリアスは 1 つのため、最後に書き込んだものが有効になります。2 つのエージェントが同じワークスペースを共有し、どちらも heygen-avatar を実行した場合、AVATAR-AGENT.md から参照できるのは直近の実行のアイデンティティのみです。両方の名前付きファイルは引き続き存在します。この制限は許容します。複数エージェントが共有するワークスペースは、v1 の対象外です。

フェーズ 6 — テスト（任意）

ユーザーがアバターの動作を確認したい場合：

MCP： create_video_agent(avatar_id=<avatar_id>, voice_id=<voice_id>, prompt=<greeting>) CLI： heygen video-agent create --avatar-id <id> --voice-id <id> --prompt "..." --wait

user_language に基づく動画の言語で、自然な挨拶を生成します。例：英語「こんにちは、私は [name] です。はじめまして！」、日本語「[name]です。はじめまして！」、スペイン語「こんにちは、私は [name] です。お会いできてうれしいです！」、韓国語「안녕하세요, [name]입니다. 만나서 반갑습니다!」

フィードバックを報告する（CLI モード）

アバターと音声を保存した後、または作業中に問題が発生した場合は、タスクごとに 1 回、次を実行します。

heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"

• --rating：5 = 問題なく動作 · 3 = 問題はあったが動作 · 1 = 失敗／使用不能。
• --comment：バグ、古いドキュメント、未実装のフラグ、または分かりにくい動作と、それを引き起こしたコマンドや手順を記入します。

匿名で、API キーは不要です。分析がオプトアウトされている場合（HEYGEN_NO_ANALYTICS または heygen config set analytics false）は何も行いません。これは CLI チームにとって主要なフィードバック経路です。何も報告せずに完了した実行からは、チームは何も把握できません。CLI モードのみ： MCP または OpenClaw プラグインモードではスキップしてください（これらはフィードバックコマンドのない MCP／プラグインのインターフェースを経由します）。

反復の流れ

ユーザーが調整を希望する場合：

• 「プロンプトを調整して」 → 既存の group_id を使ってモード 2 を実行します（キャラクターは維持し、新しい見た目を追加します）。「完全にやり直す」と言われた場合のみモード 1 を実行します。
• 「新しい見た目を追加して」／「別の服装にして」 → 既存の group_id を使ってモード 2 を実行します。AVATAR ファイルの Look に追加します。
• 「別の音声を試して」 → フェーズ 3 に戻ります。
• 「完全にやり直して」 → 新しいキャラクターでモード 1 を実行します。HeyGen セクションを上書きします。

モード 2（同じグループに新しい見た目を追加）をデフォルトにします。 ユーザーが別のキャラクターのアイデンティティを明確に希望した場合のみ、新しいグループを作成します。これによりアカウントが整理され、複数のスキルで見た目を再利用できます。

反復ごとに AVATAR ファイルを更新します。このファイルは常に信頼できる唯一の情報源です。

UX ルール

チェックポイントでは対話し、それ以外では静かにします。 アバターの承認と音声の選択時には停止して待ちます。チェックポイントの間は、理由を説明したり次の手順を案内したりせず、静かに作業します。音声の選択後は、保存と確認を1つのメッセージで行います。

動画プロデューサーとの連携

heygen-video は、group_id と voice_id を取得するために AVATAR ファイルを読み取ります。解決の 優先順位：

1. 名前を指定したリクエスト（「Eve と一緒に動画を作って」）→ AVATAR-EVE.md を読み取ります。
2. エージェント自身への言及（「自分の動画を作って」「動画で近況を知らせて」）→ AVATAR-AGENT.md を読み取ります（現在のエージェントの名前付きファイルへのシンボリックリンク）。
3. ユーザー自身への言及（「私の動画を作って」「私の動画で近況を知らせて」）→ AVATAR-USER.md を読み取ります（現在のユーザーの名前付きファイルへのシンボリックリンク）。
4. AVATAR ファイルまたはシンボリックリンクがない場合 → ストックアバターを使用するか、ユーザーに尋ねます。

エイリアスの参照先は読み取り時に OS によって解決されるため、利用するスキルは単に cat AVATAR-AGENT.md を実行すれば、現在のエージェントのアバターを取得できます。

エラー処理

• SOUL.md／IDENTITY.md がない → 対話形式でオンボーディングを行い、回答をもとに AVATAR ファイルを書き込みます
• API の呼び出しに失敗 → 1回再試行し、それでも失敗する場合は API キーを確認するようユーザーに尋ねます
• 音声のマッチング精度が低い → 利用可能な音声をすべて表示し、ユーザーが選べるようにします
• アセットのアップロードに失敗 → 参照画像を省略し、プロンプトのみでの作成を試します
• 既存のアバターファイルに古い HeyGen ID が含まれている → 再生成するか、そのまま使うかを提案します

📖 既知の問題、再試行パターン、再生できない音声プレビュー、エラーからアクションへの対応表 → references/troubleshooting.md