doc-snapshot-agent

使用するタイミング

Markdown ドキュメントに実際の画像が必要なときに、このスキルを読み込みます。対象には、公開中のウェブページのスクリーンショット、AI 生成の編集用イラスト、または画像の配置だけを修正する、処理済みファイルの再実行が含まれます。

ユーザーから次の依頼があった場合に使用します。

• Markdown 記事に画像を追加する
• 画像マーカー付きのケースファイルを処理する
• ドキュメント用のスクリーンショットを撮影する
• 記事用のビジュアルを生成してドキュメントに挿入する
• 処理済みドキュメントを再実行する、または画像の配置を修正する

テキストのみの編集、校正、翻訳には使用しないでください。こうした作業ではブラウザー自動化や画像生成の利点がなく、直接対応するのが適切です。

アーキテクチャ

このスキルには、エントリーポイントが 1 つ（このファイル）と、詳細を補う 4 つの関連リファレンスがあります。隠しメモリーフォルダーを作成せず、ブラウザーの状態を永続化せず、対象ワークフローに必要な範囲を超えてデータを送信することもありません。

入力ケース、出力画像、イラスト付き Markdown、キャッシュへのすべてのパスは、実行開始時にユーザーが指定する 1 つの {project-root} 以下に解決されます。ブラウザー操作は Playwright MCP サーバー経由に限定されます。生成画像には、OpenRouter を呼び出す同梱の Python スクリプトを使用します。

クイックスタート

1. Playwright MCP ツールを確認する — mcp__playwright__browser_navigate およびその他の mcp__playwright__* ツールが利用可能であることを確認します。利用できない場合は、references/mcp-setup.md に記載されたインストール用スニペットをユーザーに送って停止します。
2. プロジェクトルートを確認する — 1 回だけ尋ねます。ユーザーに希望がない場合は /tmp/doc-snapshot-agent を既定値にします。
3. 既存の成果物を確認する — ディスク上にあるものは再利用します（「段階的な実行」を参照）。
4. ケースファイルを解析する — 見出し形式、HTML コメント形式、Image Summary テーブルの各マーカーを統合します。
5. 撮影、生成、配置、README の書き込みを行う — 「ワークフロー」セクションに従います。

クイックリファレンス

トピック	ファイル
クライアントごとの Playwright MCP のインストール、権限の付与、ランタイムのセットアップ	references/mcp-setup.md
ナビゲーション、スナップショット、ログイン、撮影、検証 — ブラウザー操作の全体フローとツールの使用パターン	references/browser-capture.md
サイト固有のナビゲーション知識の構築と維持	references/site-explorer.md
生成画像用のプロンプト作成とスクリプトの使用方法	references/image-generation.md
画像生成 CLI	scripts/generate_image.py

アプローチの選択

状況	最適な方法	理由
記事にすでに output/{article-id}/raw/ 内のスクリーンショットがあり、ユーザーが Markdown の再構築のみを希望している	撮影をスキップし、ステップ 5（イラスト付き Markdown）を再実行する	ブラウザー操作は時間がかかりますが、Markdown の再生成は簡単です
マーカーの種類が screenshot で、ページに公開状態でアクセスできる	Playwright MCP で移動 → スナップショット → 撮影	信頼性が高く、内容を確認でき、JavaScript による描画にも対応します
マーカーの種類が screenshot で、ページへのアクセスに認証が必要	PLAYWRIGHT_CRED_* 環境変数を使用して Playwright MCP を実行する	プロンプトやトランスクリプトにシークレットが含まれないようにできます
マーカーの種類が generated（編集用、ヒーロー、概念イラスト）	OpenRouter 経由で scripts/generate_image.py を実行する	スクリーンショットでは概念的な画像を生成できません
マーカーが誤った段落に配置された	ケースファイルを再解析し、意味に基づいて配置し直す	撮影し直しても配置上の問題は解決しません
実行環境に必要な MCP ツールがない	停止し、references/mcp-setup.md をユーザーに案内する	MCP がないとワークフローを進められません

ワークフロー

ステップ 0：Playwright MCP を確認する

初回だけでなく、毎回の実行開始時にこの確認を行ってください。

1. 名前が mcp__playwright__ で始まるツールを検出します。必須ツールは browser_navigate、browser_snapshot、browser_take_screenshot です。
2. これらが見つからない場合は処理を中止し、references/mcp-setup.md にある該当するインストール用スニペット（Claude Code、Codex、VS Code/Cursor/Kiro、Claude Desktop、またはスタンドアロン）をユーザーに提示します。Claude Code と Codex には permissions.allow: ["mcp__playwright__*"] の注記も含めてください。
3. ユーザーがインストールしてクライアントを再起動した後は、実行を最初からやり直すのではなく、ここから再開します。

Playwright ライブラリの直接呼び出しや、mcp__playwright__ のプレフィックスがないブラウザツールで代用しないでください。プレフィックスがない場合、その呼び出しは MCP サーバーを経由しません。

ステップ 0.5：プロジェクトのルートを確認する

一度だけ、次のように尋ねます。

今回の実行では、どのディレクトリをプロジェクトのルートとして使用しますか？

• ユーザーがパスを指定した場合は、それを {project-root} として使用します。
• ユーザーが「指定なし」と答えた場合、回答を省略した場合、または返答がない場合は、/tmp/doc-snapshot-agent をデフォルトとして使用します。
• ディレクトリが存在しない場合は作成します。

以降のすべてのパス（cases/、output/、.cache/、scripts/、references/）は、{project-root}/ の下に解決されます。

{project-root}/ 内の推奨レイアウト：

{project-root}/
├── cases/
│   └── {article-id}.md
├── output/
│   ├── {article-id}/
│   │   ├── raw/
│   │   │   ├── A1_example.png
│   │   │   └── A2_example.png
│   │   ├── A1_example.png
│   │   ├── A2_example.png
│   │   └── README.md
│   └── markdowns/
│       └── {article-id}.md
└── .cache/
    └── screenshots/
        └── {article-id}/

規則：

• cases/ にはソース Markdown を格納します。
• output/{article-id}/raw/ には元のブラウザーのスクリーンショットを格納します。ここにあるファイルは上書きしないでください。
• output/{article-id}/ には、最終 Markdown が参照する後処理済みのアセットを格納します。
• output/markdowns/ には、画像を含む最終 Markdown を格納します。
• .cache/screenshots/ には、再利用可能なスクリーンショットのキャッシュエントリを格納します。

ユーザーが異なるレイアウトを指定した場合は、その指示に従ってください。

ステップ 1：ケースファイルを解析する

次の 3 つのソースから画像要件を統合します。

1. 見出しベースのインラインスクリーンショットマーカー
2. インライン `` マーカー
3. Image Summary テーブル

各画像について、タイプ（screenshot または generated）、ファイル名、存在する場合はマーカー ID、説明または目的、存在する場合はソース URL、存在する場合は後処理の指示、存在する場合は正確なインライン位置、意味に基づく配置がまだ必要かどうかを記録します。また、記事で参照されている対象ウェブサイトも特定します。

ステップ 2：環境を準備する

• 出力ディレクトリを作成する
• スクリーンショットキャッシュを確認し、再利用可能なエントリを探す
• 環境変数から認証情報を読み込む（パターン：PLAYWRIGHT_CRED_{SERVICE}_{FIELD}）
• Playwright MCP ツールが存在することを再確認する
• Chromium ランタイムがない場合は、npx playwright install chromium を実行する（references/mcp-setup.md を参照）
• 対象のフローでログイン、サインアップ、招待、または認証が必要で、必要な情報がまだ提供されていない場合は、アカウントに関わる操作を行う前に一時停止してユーザーに尋ねる

ステップ 2.5：対象サイトを把握する

スクリーンショットの失敗は、キャプチャコマンドの誤りより、誤ったページを開いていることが原因である場合が多くあります。キャプチャの前に、次の手順を実行します。

1. $IMAGE_AGENT_SITE_KNOWLEDGE_DIR/ と $IMAGE_AGENT_SITE_LEARNING_DIR/ に既存のサイト情報があるか確認します。
2. ドメインから安定した site-key を導出します（memclaw.me → memclaw、app.felo.ai → felo）。
3. {site-key}.md が存在し、情報が新しい場合は、ブラウジングの前に読み込みます。
4. 情報がない、または古い場合は、構造化されたサイト探索を実行します。references/site-explorer.md を参照し、調査結果を再利用できるように保存します。
5. 各スクリーンショットの説明を、特定のページまたは UI の状態に対応付けます。対象 URL またはクリック経路、表示が必要な要素、必要なスクロール、タブ切り替え、展開操作を記録します。
6. ブラウジング中に記録しておく価値のある情報が見つかった場合は、サイト情報ファイルに追記します。

Step 3: ブラウザーのスクリーンショットを撮影する

一連のナビゲーション → スナップショット → 操作 → 待機 → 撮影 → 確認の流れと具体的なツールの使用パターンについては、references/browser-capture.md を参照してください。

一般的な流れ：

• 対象のウェブサイトを開く
• 必要に応じてログインする（認証情報は環境変数から取得）
• 正しいページまたは UI の状態に移動する
• 重要なコンテンツが読み込まれるまで待つ
• 指定されたレイアウトに合わせてビューポートのサイズを変更する
• スクリーンショットを {project-root}/output/{article-id}/raw/ に保存する

命名規則：

• マーカー ID がある場合は、{marker-id}_{filename} として保存する（例：A1_workspace-dashboard.png）
• それ以外の場合は元のファイル名を使用する

撮影後は毎回、画像ファイルを開いて説明と一致していることを確認してください。DOM の確認は、保存した PNG を目視する代わりにはなりません。

Step 4: スクリーンショットを後処理する

Processing: の指示がある場合は適用します（切り抜き、サイズ変更、アスペクト比の調整）。raw/ から最終出力ディレクトリにコピーしてください。raw/ 内のファイルを直接編集してはいけません。

• raw/ には変更していない元画像を保存します。
• output/{article-id}/ には Markdown が参照するアセットを保存します。

Step 5: 画像付き Markdown を生成する

5.1 インラインマーカーをその場で置き換える

見出しマーカー：

### 📷 Screenshot: A1 (workspace-dashboard.png)
Use: Show the authenticated workspace homepage
Processing: Full-width screenshot

置き換え後：

![Authenticated workspace homepage](../{article-id}/A1_workspace-dashboard.png)

HTML コメントマーカー：

置き換え後：

![Workspace dashboard showing Architecture Decisions](../{article-id}/architecture-decisions.png)

5.2 インラインマーカーのない画像を意味に沿った場所に配置する

Image Summary テーブルにのみ記載された画像については、次の手順に従います。

• 説明を注意深く読む
• 重要な概念を抽出する
• 文書を段落ごとに検索する
• 最も直接的に同じ概念を扱っている段落を見つける
• その段落の直後に画像を挿入する。セクションの末尾や記事の末尾には挿入しない

例：Share panel showing team members and invite controls の説明に当てはまる画像は、一般的なオンボーディングセクションの末尾ではなく、チームメンバーの招待について述べている段落の近くに配置します。

5.3 生成画像を扱う

generated マーカーについては、references/image-generation.md に従い、同梱スクリプトを呼び出します。

python {project-root}/scripts/generate_image.py "{description}" -o "{project-root}/output/{article-id}/{filename}"

テキストの多い画像には、より高性能なモデルを使用します。

python {project-root}/scripts/generate_image.py "{description}" -o "{project-root}/output/{article-id}/{filename}" -m google/gemini-3-pro-image-preview

生成に成功した場合は、通常の Markdown 画像参照を挿入します。失敗した場合は警告ブロックを挿入し、README に失敗を記録します。

> Warning: AI image generation failed for {filename}

生成プロンプトのガイドライン：被写体を明確に含め、記事から視覚スタイルが読み取れる場合はそれを指定し、技術記事向けかチュートリアル向けかを明記します。また、画像内に表示する必要があるテキストがあれば、明示的に指定します。

5.4 Image Summary テーブルを削除する

Image Summary ブロックはワークフローのメタデータです。最終的な画像付き Markdown から削除してください。

Step 6: README の一覧を作成する

{project-root}/output/{article-id}/README.md を作成します。

# {article-id} Illustration Output

Article: {title}
Completed: {timestamp}

## Image Inventory

| Filename | Marker | Description | Size | Processing |
|----------|--------|-------------|------|------------|
| A1_example.png | A1 | Workspace dashboard | 1200x800 | resized |

## Notes

- Credentials source: environment variables
- Additional comments

## Remaining Work

- [ ] Any missing screenshot or failed generated image

記事 ID、再利用したものと新たに生成したもの、出力 Markdown のパス、画像の出力ディレクトリ、失敗または不足している画像を含む簡潔な実行概要を返してください。

マーカーフォーマット

このスキルは 3 種類のマーカーフォーマットに対応しています。1 つの文書で複数の形式を併用できます。

A. 見出しベースのスクリーンショットマーカー

### 📷 Screenshot: {marker-id} ({filename})
Use: {why this screenshot exists}
Processing: {post-processing instruction}
Difference: {optional distinction from similar screenshots}

フィールド：marker-id は A1、B3-1、D3 のような一意の ID です。filename はマーカープレフィックスを含まないベースファイル名です。Use はスクリーンショットで伝える内容を説明します。Processing は切り抜きやサイズ変更の指示です。Difference は似たスクリーンショットを区別するための説明です。

B. HTML コメントマーカー

スクリーンショット：

生成画像：

C. Image Summary テーブル

文書の末尾に、必要な画像をすべて列挙するサマリーテーブルがある場合があります。

## Image Summary

| # | Type | Description | Filename |
|---|------|-------------|----------|
| 1 | generated | Description... | `hero.png` |
| 2 | screenshot | Description... | `dashboard.png` |

重要：

• サマリーテーブルは完全な一覧です
• 本文にインラインマーカーとして記載されている画像もあります
• サマリーテーブルにのみ記載されている画像もあり、Step 5.2 で意味に沿った場所に配置する必要があります

段階的な実行

ワークフローが最初から始まるとは限りません。まず状態を確認し、適切なステップから続けてください。

既存の成果物を確認する

指定された記事 ID について、以下を確認します。

• {project-root}/output/{article-id}/raw/*.png
• {project-root}/output/{article-id}/*.png
• {project-root}/output/{article-id}/README.md
• {project-root}/output/markdowns/{article-id}.md
• {project-root}/.cache/screenshots/{article-id}/

判断ルール

• 新規記事 — 何も存在しない場合 → ワークフロー全体を実行します。
• スクリーンショットはあるが、Markdown がない — キャプチャを省略し、Markdown と README を再構築します。
• Markdown があり、ユーザーが修正を依頼している — ケースファイルを再解析し、再キャプチャせずに配置を再構築します。
• スクリーンショットが一部欠けている — 不足分のみをキャプチャしてから、続行します。
• ユーザーが特定の画像の再キャプチャを依頼している — 該当する画像のみを再生成してから、Markdown を再構築します。
• ユーザーが最初からやり直すよう依頼している — キャッシュを無視し、すべてを再構築します。

基本原則：まず差分作業を選び、できる限りスクリーンショットを再利用します。Markdown の再生成は手軽で、ブラウザー操作にはコストがかかるものとして扱い、省略する作業と再実行する作業をユーザーに伝えます。

キャッシュポリシー

シンプルなファイルベースのキャッシュです。

• ディレクトリ：{project-root}/.cache/screenshots/{article-id}/
• キャッシュキー：スクリーンショットのファイル名
• 一致するキャッシュファイルがあり、ユーザーが更新を依頼していない場合は再利用します
• ユーザーが明示的に再キャプチャまたは更新を依頼した場合は、キャッシュ項目を無視します

基本ルール

1. MCP を使うか、何もしない

ブラウザー操作はすべて mcp__playwright__* ツール経由で行います。これらのツールがない場合は停止し、インストールするようユーザーに依頼します（references/mcp-setup.md を参照）。Playwright を直接使ったり、汎用ブラウザーツールに切り替えたりしてはいけません。これらは、このスキルが依存する契約を迂回するためです。

2. クリックの前にスナップショットを取得し、状態の変化後に再取得する

クリックでは、記憶ではなく最新のアクセシビリティスナップショットにある参照を使う必要があります。ページ遷移、モーダル表示、タブ切り替え、アコーディオン展開の後は、次の操作の前にスナップショットを再取得します。

3. 操作の種類を意図的に選ぶ

通常は左クリックを使います。ページの意味、サイトに関する知識、または画面上の明確な手掛かりから「開く」「名前を変更する」「詳細に移動する」など、ダブルクリックが必要だと判断できる場合に限り、ダブルクリックを使います。コンテキストメニューが明確に必要な場合に限り、右クリックを使います。左クリックに失敗した際の再試行としてダブルクリックを使ったり、「どうなるか見る」ためだけに右クリックしたりしてはいけません。ダブルクリックまたは右クリックの後は、画面上の状態変化を待ち、次の操作の前にスナップショットを再取得します。

4. raw/ は一度だけ書き込む

元のスクリーンショットは output/{article-id}/raw/ に保存し、変更せずに保管します。切り抜き、サイズ変更、その他の処理はすべて親ディレクトリの output/{article-id}/ に対して行います。raw/ 内のファイルを上書きしてはいけません。

5. 再キャプチャより再利用を優先する

ブラウザー操作はコストのかかる工程です。既存のスクリーンショットとキャッシュ項目を再利用することを基本とし、ユーザーが依頼した場合、画像がない場合、または検証で不備が確認された場合に限り、再キャプチャします。

6. 認証情報は環境変数で管理する

PLAYWRIGHT_CRED_{SERVICE}_{FIELD} 環境変数から読み込みます。ハードコードしたり、秘密情報をユーザーにそのまま返したりしてはいけません。必須の環境変数がない場合は、その正確な名前を伝えます。

7. ゲートのある手順では一時停止して確認する

ページにサインアップ、登録、招待、メール認証、2FA、またはオンボーディングのゲートがあり、必要なユーザー固有の情報がまだ提供されていない場合は、停止してユーザーに確認します。明示的なユーザーの入力なしに、アカウントを作成したり、招待を承諾したり、プロフィール情報を作り上げたりしてはいけません。ユーザーから回答があったら、最初からやり直すのではなく、中断した手順から続行します。

8. 実際の画像を検証する

DOM スナップショットだけでは不十分です。キャプチャのたびに、保存した PNG を開き、説明された内容が表示されていること、モーダルや読み込み中のスケルトンに遮られていないこと、記事と同じ言語であることを確認します。画像が条件を満たさない場合は、README で取り繕わず、撮り直します。

9. セクション末尾へのまとめて配置ではなく、内容に沿って配置する

サマリーテーブルにある画像については、段落の内容を読み、同じ概念について説明している段落の近くに画像を挿入します。残った画像を記事の末尾や大まかなセクションの末尾に追加しないでください。

注意点

• 「高速だから」という理由で、MCP 非対応のブラウザーツールに置き換えること — 再現性と MCP スナップショットのフローが損なわれます
• 最新のスナップショットではなく記憶を頼りにクリックすること — 1 回はうまくいっても、その後は不安定になります
• 1 回クリックしても反応がなかったとき、一般的な再試行としてダブルクリックすること — 通常は誤った状態を開くか、実際の問題を見えにくくします
• 明確な目的がないまま、またはコンテキストメニューが表示されるのを待たずに右クリックすること — ページが曖昧な状態になることがよくあります
• 読み込みインジケーターが消える前にスクリーンショットを撮ること — スケルトンがキャプチャされます
• モーダルやタブを開いた後、スナップショットを再取得し忘れること — 次のクリックで古い ref が対象になります
• トリミングした画像だけを保存し、raw/ のオリジナルを失うこと — 復旧には再キャプチャが必要です
• アンカーのない画像を意味に沿って配置せず、すべて記事の末尾に追加すること
• 認証情報をハードコードしたり、プロンプトやトランスクリプトに書き出したりすること
• 毎回の実行を新たな開始と見なし、ディスク上にすでにある画像を再キャプチャすること
• DOM のアサーションがあればスクリーンショットも正しいと思い込むこと — 必ず PNG を確認してください
• 言語別の記事に、サイトの異なる言語バージョンをキャプチャすること

外部エンドポイント

エンドポイント	送信されるデータ	目的
ユーザーが指定したウェブサイト	タスクに必要なブラウザーリクエスト、フォーム入力、Cookie、操作	スクリーンショットのキャプチャと認証が必要なナビゲーション
https://openrouter.ai/api/v1/chat/completions	画像生成プロンプトのテキストと、リクエストされたモデル ID	scripts/generate_image.py による生成画像マーカーの作成
https://registry.npmjs.org	オプションのインストール中に取得するパッケージのメタデータと tarball	@playwright/mcp と Chromium ランタイムのインストール

これ以外のデータは外部に送信されません。

セキュリティとプライバシー

お使いのマシンから送信されるデータ：

• ユーザーがキャプチャを依頼したウェブサイトへのリクエスト
• 画像生成時に OpenRouter に送信されるプロンプトのテキスト
• Playwright MCP または Chromium ランタイムのインストール時に発生する、オプションの npm トラフィック

ローカルに保持されるデータ：

• ソースの Markdown、生成されたスクリーンショット、生成画像、画像付き Markdown、実行 README
• {project-root}/.cache/ 配下のスクリーンショットキャッシュ
• 環境変数（認証情報と API キー） — このスキルはこれらを読み取りますが、ファイルやトランスクリプトには書き込みません

このスキルは、以下を行いません：

• 隠しメモリファイルや永続的なプロファイルフォルダーを作成すること
• デフォルトでブラウザーのセッション状態を実行間で保持すること
• スクリーンショット、生成画像、ソース Markdown をどこかにアップロードすること
• ユーザーに代わってアカウントを作成したり、招待を承諾したり、確認手続きを完了したりすること
• 認証情報、API キー、個人データをハードコードしたり、書き出したりすること

信頼性

このスキルを実行すると、ブラウザーのトラフィックはキャプチャ対象として指定したウェブサイトに送信され、生成プロンプトは OpenRouter に送信されます。また、オプションのパッケージのダウンロードには npm が使用されます。信頼できるサイトと画像生成プロバイダーに対してのみ実行してください。破壊的、金銭、医療、本番環境に関わるフローでは、ステージング環境を優先し、続行する前にユーザーに確認してください。

フィードバック

問題の報告と改善案：https://github.com/Felo-Inc/felo-skills/issues