create-agent-site-skill

サイト固有のブラウザースキルを作成する

動作するブラウザーワークフローを、再利用可能なスキル内で単独実行できるタスクとして記録します。検証済みの既存ワークフローを再利用し、不足している手順はユーザーの許可範囲内でライブブラウザーを使って確認します。

ブラウザー操作方法を選ぶ

既定では kernel browsers playwright execute と kernel browsers computer を使用します。インストール、認証、コマンド構文については kernel-cli を読み込みます。

呼び出し元が別のハーネスを指定した場合は、そのコマンドを使用し、生成するスキルにその依存関係を記録します。

• agent-browser: kernel-agent-browser を読み込み、以下で作成するブラウザーを再利用して、CDP 接続のワークフローに従います。
• browser-harness: 呼び出し元のエージェントが BU_CDP_WS／BU_NAME モデルを使用する場合は、kernel-browser-harness を読み込みます。
• その他のハーネス: KERNEL ブラウザーの cdp_ws_url を選択したハーネスに渡します。

以下のコマンド例を選択した操作方法に合わせて変更し、セッションと認証情報に関する要件は維持します。

ワークフローを確認する

1. ブラウザーを準備する

プロファイルとボールトは、サイトとユーザーの両方に紐づけます。形式は <site-name>-<user-id> です。ユーザー ID は実行時の入力またはセッションコンテキストから取得し、共有スキルにハードコードしないでください。プロファイルには認証済み Cookie とストレージも含まれます。

ログインが必要なサイトでは、プロファイルとボールトを一度作成し、以後は再利用します。どちらもブラウザーと同じ KERNEL プロジェクト内に置きます。リソースが存在しないことを確認できた場合にのみ、作成コマンドを実行します。

PROFILE_NAME="<site-name>-<user-id>"
VAULT_NAME="<site-name>-<user-id>"

# First-time setup only:
kernel profiles create --name "$PROFILE_NAME"
kernel vaults create --name "$VAULT_NAME"

# Each run:
SESSION=$(kernel browsers create --profile-name "$PROFILE_NAME" --save-changes --stealth --vault "$VAULT_NAME" --timeout 600 -o json | jq -r '.session_id')

• ヘッドフルセッションを使用します（既定）。コンピューター操作とライブビューにはヘッドフルセッションが必要です。
• --stealth を設定し、作成時にボールトを接続します。どちらも後から追加できません。ログインが不要なサイトでは、ボールトの設定と --vault を省略します。
• セッション終了時に Cookie とストレージを保存するため、--save-changes を指定したままにします。CLI の既定値である 60 秒ではなく、--timeout 600 を指定して、確認に十分な時間を確保します。

2. ログインを確立する

保存済みプロファイルがすでに認証済みかどうかを確認します。ログインが必要な場合は、ボールト経由で認証情報を使用します。生の認証情報を要求したり、スキルや AGENTS.md に保存したりしないでください。

認証情報のスキーマを定義する前に、ログインフローを確認します。認証情報のフィールド、型、必須／機密フラグ、ログイン段階、フィールドとセレクターの対応を記録し、追加の段階が明らかになったら内容を更新します。

kernel browsers playwright execute "$SESSION" 'await page.goto("<login-url>")'
kernel browsers computer screenshot "$SESSION" --to /tmp/login.png

ユーザーの既存の認証情報アイテムと、そのフィールド名を再利用します。存在しない場合は、値を含めずに、確認したスキーマに基づいて定義します。以下のユーザー名／パスワードの例を適宜変更してください。

kernel vaults credentials create "$VAULT_NAME" <site-name>-login --spec-file - <<'JSON'
{
  "description": "<Site Name>",
  "fields": {
    "username": {"type": "text", "required": true, "sensitive": false},
    "password": {"type": "password", "required": true, "sensitive": true}
  }
}
JSON

返された非公開コレクション URL は、ユーザーに直接共有します。エージェントが操作するブラウザーでは決して開かないでください。--wait 60 は上限付きの単一の確認であり、再試行ではありません。アイテムが保留中の間は状態を確認し、終端状態に達したら停止します。

STATUS="pending"
while [ "$STATUS" = "pending" ]; do
  ITEM=$(kernel vaults items get "$VAULT_NAME" <site-name>-login --wait 60 -o json)
  STATUS=$(jq -r '.state.status' <<<"$ITEM")
done

$STATUS が ready の場合は、入力操作を実行できます。フィールド名とセレクターを指定して入力し、確認したフォームに合わせてフィールドと手順を調整します。それ以外の終端状態になった場合は、続行せずに停止して、問題を解決してください。

kernel vaults items invoke "$VAULT_NAME" <site-name>-login fill --spec-file - <<JSON
{
  "browser_id": "$SESSION",
  "page_url": "<login-url>",
  "fields": [
    {"field": "username", "selector": "input[name='username']"},
    {"field": "password", "selector": "input[name='password']"}
  ]
}
JSON

入力済みの認証情報の値を読み取ったり、表示、スクリーンショット撮影、返却したりしないでください。入力でエラーが発生した場合、タイムアウトした場合、または completed 以外の状態が返された場合は、送信せずに停止して、問題を解決してください。fill は送信を行わないため、安全に再試行できます。ページを確認してからのみ再試行し、自動ループでは決して再試行しないでください。

入力が完了したら送信し、期待されるログイン後の状態を確認します。

kernel browsers playwright execute "$SESSION" -o json '
  await Promise.all([
    page.waitForURL("<logged-in-url-pattern>", { timeout: 5000 }),
    page.getByRole("button", { name: "Sign in" }).click()
  ]);
  return page.url();
'

既存のセッションにステルス設定がなく、ボット検出によってログインがブロックされる場合は、そのセッションを削除し、ステルスを有効にして再作成します。それでもログインがブロックされる場合は、kernel browsers view "$SESSION" -o json で browser_live_view_url を取得し、ユーザーに手動でログインするよう依頼して、ログイン後の状態を確認します。

3. 各タスクを調査して検証する

共有セットアップと必要なログイン前提条件を設け、リクエストされた各タスクを個別に実行できる状態にしてください。

1. タスクの開始状態に移動し、ページを確認します。
2. 選択したコントロールでタスクを実行し、操作後に実際に状態が変化したことを確認します。
3. 入力値、開始状態、直接アクセスする URL、順序付きコマンド、待機条件、成功の確認方法、観察された失敗や回避策を記録します。
4. 不確実な手順を個別にテストしてから、スキルに記載するものと同じコマンドでシーケンス全体を検証します。テストはユーザーの許可範囲内にとどめ、検証できない点があれば明記します。

KERNEL のデフォルトのコントロールを使用する場合：

• ロール、ラベル、テキストのロケーターを優先し、サイトのセマンティクスだけでは不十分な場合は CSS または XPath を使用します。
• 検証結果には return を使用し、解析する場合は -o json を使用します。各 playwright execute の呼び出しでは新しいスクリプトコンテキストが作成されますが、ブラウザーのページは維持されます。
• 完了を示す URL、表示状態、レスポンス、値を待機します。5000 ms など、短いタイムアウトを明示的に設定します。固定時間の待機は最後の手段としてのみ使用してください。デフォルトの成功条件として networkidle を使用しないでください。
• クロスオリジンフレームを含む iframe の操作には page.frameLocator(...) を使用します。

コンピューター操作へのフォールバック

Playwright で手順を 2～3 回試しても完了できない場合（エラーやタイムアウトが発生する場合、または成功と報告されてもページの状態が変わらない場合）は、その手順にコンピューター操作を使用します。すでに成功している可能性がある操作を再試行する前に、結果を確認してください。

kernel browsers computer screenshot "$SESSION" --to /tmp/state.png
kernel browsers computer drag-mouse "$SESSION" --point 100,200 --point 250,200 --point 400,200 --button left
kernel browsers computer click-mouse "$SESSION" --x 250 --y 60
kernel browsers computer type "$SESSION" --text "some text"
kernel browsers computer press-key "$SESSION" --key Return

スクリーンショットから座標を読み取り、ビューポートサイズとあわせて記録します。ポインターセンサーが動きを認識できるよう、ドラッグの中間経由点も含めてください。各ジェスチャーは DOM 操作またはコンピューター操作のいずれか一方だけで完結させます。適切な場合は、その後 Playwright に戻ります。

4. スキルを作成する

主要な自動化ドメインをフォルダー名として使用します：<skills-directory>/<domain>/SKILL.md。対象エージェントの指示から、登録済みのスキルディレクトリを特定します。

検証済みのコマンドとサイト固有の調査結果を使って、以下のテンプレートを調整します。選択したコントロール、セットアップ、必要なログイン、クリーンアップを含めてください。汎用的な CLI のドキュメントは、リンク先の依存スキルに記載してください。

発見した認証情報のスキーマ、フィールドとセレクターの対応、ログイン手順、待機条件、成功の確認方法を共有スキルに保存します。サイト固有のプレースホルダーは検証済みの詳細に置き換えますが、ユーザー ID、ボールトやアイテムの参照、プロファイルの参照、アカウント固有の URL 部分は、実行時の入力として保持するか、現在のユーザーのコンテキストから解決してください。調査に使用したユーザーの値をハードコードしないでください。

---
name: <descriptive-name>
description: <What the skill does and when to use it.>
---

# <Site Name>

## Setup

<Required tools and skill dependencies, runtime inputs, and tested session setup.>

## Login

<How to check existing authentication; tested vault-backed login and manual fallback if needed.>

## <Task Name>

<Required inputs and starting state.>

```bash
# Tested commands, including necessary waits and verification.
```

<Expected outcome and any task-specific recovery instructions. Repeat for each independent task.>

## Cleanup

<Commands to close the selected harness and delete the Kernel session.>

## Notes

<Observed quirks and workarounds; coordinate/viewport requirements where applicable.>

5. クリーンアップする

接続中のハーネスをすべて閉じ、調査用に作成したブラウザーセッションを削除します。削除すると、プロファイルの永続化が確定します：

kernel browsers delete "$SESSION"