steel-skill-creator

Steel Skill Creator

繰り返し行うウェブタスクをエージェントスキルに変換します。ユーザーがタスクと入力例一式を提示します。実際の Steel ブラウザーでタスクを最初から最後まで2回実行し（1回目は入力例、2回目は変更した入力を使用）、Steel CLI で両方のトレースを取得し、パラメーター化された SKILL.md を作成してインストールし、3つ目の入力セットで検証します。

ユーザーにセッション ID を指定してもらう必要はありません。2つのセッションは自分で生成します。

このスキルの基盤となる原則

Steel のエージェントトレースは、すでに SKILL.md の80％を占めています。品質順に優先された安定したセレクター（testId → id → aria → name → CSS）、クリックしたすべての要素の accessibleNames、ページの境界、待機ポイントを示すアイドル状態の間隔、URL クエリ文字列やフォーム入力としてインラインで記録されたパラメーター値が含まれています。主な作業は、2つのトレースを並べて読み、まだ記録されていない部分を書くことです。つまり、目的、パラメーター名、成功条件、本番環境で再生するための適切な Steel セッション設定（ステルス、プロキシ、認証情報、プロファイル）です。

トレースを両方とも自分で生成するのは、同じフローを異なる入力で実行した2つの結果を比較できれば、パラメーターを確実に抽出できるためです。対応する位置で異なる値はパラメーターであり、同じ値は不変の値です。1つのトレースだけでは推測せずに判断できませんし、ユーザーに2回記録してもらうと作業が倍になります。代わりに自分で行うほうがよいでしょう。

あらゆるエッジケースをプログラムで処理しようとしないでください。何を確認すべきかは references/ ディレクトリに記載されています。あとはコードを読んでコードを書く作業です。

前提条件

• steel CLI がインストールされ、ブラウザー操作に使える状態で認証されています。
• steel-browser スキルを利用できます。2回の記録セッションを実行する際は、同じ基本操作（steel browser start、navigate、snapshot、click、fill、wait など）を使用します。
• タスクの説明が、実行できる程度に明確です。説明が曖昧すぎる場合（「ブラウジングを自動化して」など）は、ほかの作業を始める前に詳細を確認してください。

ワークフロー

ステップ 1 — タスクの説明と入力例を集める

ユーザーから次の3つを確認します。

1. スキル名 — kebab-case の識別子（例：flight-price-probe、weekly-traffic-report）。ユーザーが指定していない場合は、フローの内容に基づいて候補を提案し、確認を取ります。
2. 1行の目的 — このスキルの用途をユーザー自身の言葉で記述したもの（「指定した日付範囲で2つの空港間の最安直行便を探す」など）。生成するスキルの説明の基礎になります。
3. 入力例一式 — フロー全体を実行できる具体的な値です。「フライトを検索」ではなく、「SPU → FCO、出発日 2026-06-13、帰着日 2026-06-18」のようにします。追加で確認せずにタスクを実行できるだけの具体性が必要です。

不足している情報や曖昧な点があれば、簡潔に一度だけ確認してください。ユーザーに長々と質問しないでください。

ステップ 2 — 記録前に安全性を確認する

タスクを一度でも実行する前に、副作用がないか考えてください。

• 読み取り専用のフロー（スクレイピング、検索、レポートの閲覧、価格照会）→ 入力を変えて2回実行しても安全です。進めてください。
• 副作用のあるフロー（予約、支払い、メッセージの送信、メールや請求を発生させるフォーム送信、アカウント作成、コンテンツの投稿）→ 停止して確認してください。 任意の入力で2回実行すると、金銭的負担や迷惑メールの送信、実際の成果物の作成につながる可能性があります。次の3つの選択肢を提示してください。
  1. 両方の実行にサンドボックス／テスト用アカウントや入力を使う。
  2. 1回だけ記録し、パラメーター化の精度が下がることを受け入れる（生成されたスキルでは、差分の証拠ではなくヒューリスティックに基づいて一部のパラメーターを推定する必要があるため）。説明には「single-trace draft」と明記する。
  3. ここで自動化を中止し、実行可能なスキルではなく通常の英文ドキュメントとして手順を説明する。

副作用のあるフローを、ユーザーに知らせずに2回実行してはいけません。スキルよりもユーザーの信頼が大切です。

ステップ 3 — タスクを自分で実行してトレース #1 を記録する

steel-browser のプリミティブを使って、ステップ 1 の入力例でタスクを最初から最後まで実行します。セッションを開始し（references/steel-primitives.md に従って適切に設定します）、移動、クリック、待機、抽出を行います。ユーザーのために /steel-browser を実行するときと、まったく同じパターンを使ってください。

途中でスクリーンショットとスナップショットを撮影し、各ステップが正常に動作したことを確認します。ステップが失敗した場合は、通常の Steel セッションと同じようにデバッグし、壊れた状態のまま先に進めないでください。

タスクが成功状態に達したら（データの抽出、フォームの送信、確認ページの表示など）、セッションを停止します。セッション ID を保存してください。ステップ 5 で必要になります。

ステップ 4 — 入力を変更して再生し、トレース #2 を記録する

変更後の入力を選びます。ステップ 1 の各入力値に対し、同じフローを実行できる妥当な代替値を選んでください。

• 日付 → 同じ月または隣接する月の別の日付。
• 検索語 → 意味が異なるものの、形式として正しい値（別の空港、別の商品カテゴリ、別の人物名）。
• ID → 別の正常な ID。

入力は異なるが、意図は同じを目指してください。同じ概念的な経路をたどるトレースにすることで、差分からパラメーターだけを切り分けられます。

変更後の入力を使い、新しい Steel セッションでタスクをもう一度実行します。同じ設定、同じ開始 URL、同じ論理的な操作手順を使ってください。

トレース #2 がトレース #1 から逸脱した場合 — トレース #1 では表示されなかったログイン画面に遭遇した、CAPTCHA が表示された、構造の異なるページに到達したなどの場合 — 停止して調査します。references/steel-primitives.md を参照し、Steel セッションオプション（ステルス、プロキシ、CAPTCHA の解決）を追加すべきか、ユーザーにエスカレーションすべきかを判断してください。逸脱を見過ごさないでください。

2 つ目のセッション ID を保存します。

ステップ 5 — 2 つのトレースを取得する

node scripts/fetch_trace.mjs <session-id-1>
node scripts/fetch_trace.mjs <session-id-2>

このスクリプトは steel --json sessions traces <session-id> を呼び出し、正規化されたトレース JSON を一時ファイルに書き込み、そのパスを出力します。トレースには accessibleName、セレクター、ページ URL、値フィールド、タイムスタンプを含むイベントがあります。確認する内容については references/trace-anatomy.md を参照してください。

ステップ 6 — 生成されたスキルを作成する

これでトレースが 2 つ揃いました。両方を並べて読みます。対応する位置で異なる部分がパラメーター、共通する部分が不変条件です。

次のリファレンスを順番に確認してください。

• references/trace-anatomy.md — 各イベントの読み方と、2 つのトレースを対応づける方法。
• references/steel-primitives.md — 認証情報、プロファイル、ステルス、プロキシ、CAPTCHA の決定ツリーです。生成されるスキルが Steel セッションをどのように作成するかを決めます。
• references/skill-template.md — 記入するためのひな形です。

生成されるスキルは実行時に steel-browser スキルに依存し、CLI コマンドをインラインに埋め込みません。生成されるすべてのスキルには、テンプレートに正確な文言が記載された ## Prerequisites セクションを含め、steel CLI と steel-browser スキルをインストールする curl -fsS https://setup.steel.dev | sh をユーザーに案内する必要があります。本文の手順では意図を平易な文章で説明し、要素名はイタリック体にします。実行側が steel-browser のプリミティブを使って、それを snapshot → click → fill → wait のシーケンスに変換します。

生成されるスキルで使うセレクターの優先順位は次のとおりです。

1. 要素のテキストまたは accessibleName（最も堅牢で、ほとんどの DOM の書き換えに耐えます）。
2. 存在する場合は data-testid。
3. 存在し、意図的に付けられたように見える場合は id。
4. aria-label または name。
5. 最後の手段として CSS セレクターを使います。ただし、ほかに手段がない場合を除き、:nth-of-type の連鎖は使いません。

利用可能なセレクターを示す根拠として target.selector を使いますが、アクセシブル名が十分に具体的な場合は、読みやすいセマンティックな手順を優先してください。たとえば、生のセレクターを示すのではなく、「Direct only チェックボックスをクリックする」と記述します。

パラメーターには、名前ではなく意味に基づいて名前を付けます。param_2 ではなく depart_date にします。後で生成されたスキルを使うモデルは、これらの名前を初めて見るため、明確さが重要です。

ゴールは命令形で記述します（「{origin} → {destination} の区間を {depart} から {return} の間で検索し、直行往復の最安値を見つける」）。成功条件は、何をクリックするかではなく、何が返されるかに基づいて記述します。

ステップ 7 — スキルをインストールする

node scripts/install_skill.mjs <skill-name> --skill-md <path-to-generated-SKILL.md>

スクリプトは ~/.claude/skills/<skill-name>/ に書き込み、最終パスを知らせます。生成されるスキルはデフォルトでシステム全体にインストールされるため、ユーザーはどのプロジェクトからでも呼び出せます。

ステップ 8 — 新しいスキルを実行して検証する

ステップ 1（入力例）とステップ 4（変更した入力）のどちらとも異なる、3 組目の入力を選びます。新しい Steel セッションで、インストールしたばかりのスキルをその入力に対して呼び出します。結果のセッション ID を記録し、トレース #3 を取得します。

ステップ 9 — 忠実度を評価する

references/llm-judge-rubric.md を読みます。3 つのトレース、生成されたスキルのソース、および収集した入力と出力を使って、評価を下してください。

• トレース #3 は、トレース #1 と #2 と同じ種類の成功シグナルに到達しましたか？
• 3 組目の入力は、URL とフォームの値に正しく置き換えられましたか？
• Cookie バナーやモーダルなどの追加手順には対処できましたか、それとも動作を妨げましたか？
• 手順が省略されていましたか？ 省略されていた場合、影響はありましたか？

構造的な差分は取らないでください。判断を下します。

評価が良好な場合：スキルがインストールされたこととインストール先をユーザーに伝え、具体的な入力を使った呼び出し例を 1 つ示します。

評価が混在している場合：診断内容を平易な英語でユーザーに示し、修正を提案します。通常、修正点は次のいずれかです。待機ポイントの位置が適切でない、セレクターが具体的すぎる、1 つに分けるべきパラメーターがある、または見落とされた Steel セッションオプションがある。

判断ポイント：ユーザーに確認する場合と、そのまま進める場合

次の場合は、ユーザーに確認してください。

• タスクの説明が曖昧で、入力内容を自分で決める必要がある場合（ステップ 1）。
• タスクに、副作用があり、安全に 2 回実行できない処理が含まれる場合（ステップ 2）。
• 初回の実行で、Steel の認証情報が設定されていないサイトのログインフローが表示された場合。認証情報をボールトに保存する前に、ユーザーの同意が必要です。
• ステップ 4 の再実行で、ユーザーが有料の Steel プランを利用していないサイトで CAPTCHA が表示された場合、またはユーザーが許可していない地域を必要とするジオブロックが発生した場合。
• 2 つのトレースから、それが意図的なパラメーターだったのか、偶発的なノイズだったのか判断できない場合（例：ユーザーが意図的に 437px の位置までスクロールしたのか、それとも偶然だったのか）。

次の場合は、確認せずに進めてください。

• セレクターの選択 — 優先順位リストに基づいて判断してください。
• パラメーター名 — 名前を提案してください。必要であれば、ユーザーは後で変更できます。
• 待機ポイントの配置 — アイドル時間とページ遷移は、信頼できる判断材料です。
• ステップ 4 で変更する入力の選択 — 妥当なものを選んで先に進んでください。
• 生成されたスキルでステルス／プロキシ／CAPTCHA を有効にするかどうか — 判断ツリーは references/steel-primitives.md に明確に記載されています。

避けること

• トレース JSON を正規表現で検索してパラメーターを探さないでください。 トレースを読み、内容を判断してください。2 つのトレースの差分確認は、文字列比較ではなく、内容を考察して行う作業です。
• 生成するスキルにトレース ID、セッション ID、タイムスタンプを含めないでください。 これらは今回のコンパイルで生じた情報であり、再利用可能なスキルには不要です。
• 100 行もの SKILL.md を書かないでください。 生成するスキルは簡潔にし、本文は 40～80 行にしてください。Steel のトレースがソースコードであり、SKILL.md はその要約です。
• どちらのトレースにもない手順を作らないでください。 どちらの記録にも「Cookie バナーを閉じる」手順がなければ、生成するスキルにも含めないでください。後で本番環境にバナーが表示された場合は、検証工程で検出されます。
• ユーザーの同意なしに、副作用のあるフローを 2 回実行しないでください。 これは繰り返し強調しておきます。

出力

実行に成功すると、ユーザーは次を利用できます。

• ~/.claude/skills/<skill-name>/ に作成された新しいスキル。
• コピーして貼り付けられる実行例。
• 注意事項の簡潔な説明（例：「foo.com 用に Steel の認証情報を設定する必要があります。初回利用前に steel credentials create --origin https://foo.com を 1 回実行してください」）。
• 検証工程による忠実度の判定を 1 行で示したもの。