gtm-agent

GTM Agent

トリガー

組織向けの GTM Agent のデプロイ、接続、確認、アップグレードに関する依頼、または何かを作成する前に、それが可能かどうか、何が必要かを尋ねられた場合に、このスキルを適用します。

スコープ

1つのデプロイとは、エージェントテンプレート eliasstravik/gtm-agent のプライベートコピーをリポジトリ gtm-agent-<slug> として作成し、Vercel プロジェクト gtm-agent-<slug> としてデプロイすること、Slack コネクター slack/gtm-agent-<slug> を組織の Slack にインストールすること、ワークスペースリポジトリ gtm-<slug> を用意すること、そしてワークフローが有効な場合は、gtm-workflow の共有セットアップ --deploy が稼働させるワークフロープロジェクト gtm-<slug>（プロジェクト、Neon、共有プロジェクト、シークレット、workflows/ の最初のプッシュ）をこのエージェントに接続することを指します。このエージェントへの接続は、エージェントのセットアップが最後のステップとして実行します。scripts/ のスクリプトは GitHub と Vercel の CLI を使用します。セットアップで作成されるものは references/setup.md に記載されています。接続名は、Vercel Secret Note またはローカルラベルに基づき、接続の命名規則に従います。このセットアップでは、エージェントは引き続き任意です。ワークスペースの内容は、ほかの gtm スキルに属します。

入力

依頼、組織のワークスペースのスラッグ（契約のスラッグ規則に従います。~/.gtm/<slug>/ がすでに存在する場合は、その値を使用します）、Vercel チームのスラッグ（vercel teams ls。複数ある場合は確認します）、GitHub のオーナー（依頼で組織が指定されていない限り、サインイン中のユーザー）、任意の Slack チャンネル ID（C0…。チャンネルの「概要」タブの下部にあり、ワークフロー通知に使用します）、references/setup.md。

役割

ユーザーは、このコンピューターで GitHub と Vercel の CLI にサインインしており、必要に応じて Slack のインストールを直接、または認証済みのブラウザーエージェントを通じて承認します。Vercel の Neon インテグレーションを使ってワークフロープロジェクトに Neon データベースを追加し（Production のみ、プレビューのブランチ機能は無効）、チームで初めて利用するときは Neon のマーケットプレイス規約に同意します。また、ボットをチャンネルに招待し、Slack で最初のメッセージを送ります。エージェントはスクリプトを実行し、ユーザーが行う必要のある操作を正確に伝え、結果を報告します。

手順

会話で最初に使われる gtm スキルは、updates に記載のとおり、新しいリリースがないか一度だけ確認します。interaction の6つのルールに従って会話し、the dialogues を再現します。作業を始める前に、このコンピューターで実行できることを確認します。gh auth status と vercel whoami の両方が成功し、node --version が22以上である必要があります。そうでない場合、またはこれがホスト型エージェント自体である場合（PATH に vercel がない、または GTM_AGENT_HOSTED が 1）、何も実行せず、不足しているものを一文で伝え、両方の CLI にログイン済みのコンピューターでチームメイトが /gtm-agent を実行するよう伝えます。

作業	実行内容
準備状況	ユーザーがセットアップできるか、必要なもの、または費用だけを尋ねている場合は、何も作成しません。上記の読み取り専用チェックと vercel teams ls を実行してから、準備できているもの、不足しているもの、セットアップで作成されるもの、必要となるユーザーの操作（references/setup.md を参照）、および Vercel チームが Pro である必要があることを伝えます。Deploy を提案します。
デプロイ	vercel teams ls で複数のチームが表示された場合にのみ Vercel チームを尋ねます。ユーザーがワークフロー通知に言及した場合にのみチャンネル ID を尋ねます。実行内容を一文で伝え、所要時間は約5分であることを伝えます。このスキルのフォルダーから node scripts/setup.mjs --slug <slug> --team <team> [--github-owner <owner>] [--channel <id>] を実行し、その出力を逐次表示します。Slack のアドレスが表示されたら、そのページで行う3つの操作（ワークスペースを選択する、Slack configuration に従って選択した Slack プロファイルを設定する、Allow を選択する）とともに伝え、待機します。スクリプトは自動的に続行されます。終了コード2はユーザーが行う操作を1つ示します（きめ細かな GitHub トークン、Slack のインストール、新しいリポジトリに対する Vercel の GitHub アプリのアクセス、またはチームが初めて Neon を追加するときの Neon の利用規約への同意）。その操作を伝えて待機し、同じコマンドを再実行します。終了コード0の場合は、スクリプトが出力した Slack の2行を伝えて終了します。終了コード1の場合は、失敗した行の内容を平易な言葉で報告し、Doctor を提案します。
Doctor	node scripts/doctor.mjs --slug <slug> --team <team> [--github-owner <owner>] [--agent-project <name>] [--workflow-project <name>] [--slack-connector <uid>] を実行します。失敗した行をビジネス上の意味と修正方法とともに報告します。ワークフロープロジェクトの修正はすべて、--agent-project を指定して gtm-workflow のセットアップを --deploy で実行することです。これにより不足しているものが修復されます。--fix を指定すると、エージェントプロジェクトのプレビューデプロイが無効になります。Slack の変更では、configure-slack.mjs --team <team> --connector <uid> --apply を実行してから、Slack configuration に従ってプロバイダーマニフェストを同期し、再インストールします。新しい --slack-manifest <file.json> を Doctor に渡すと、プロバイダーの設定、インストールの最新状況、実際のトークン権限を確認します。
アップグレード	エージェントのチェックアウト（~/.gtm/.agents/<slug>/、またはユーザーが指定したリポジトリ）で、git fetch template && git merge template/main を実行します。マージ時には下流のカスタマイズを保持し、許可されたアップグレードの範囲内で通常の競合を解決します。意図する動作が曖昧な場合にのみ確認し、git push を実行します。プッシュによってデプロイされます。その後 Doctor を実行します。ワークフローのランタイムが古い場合は、その旨を伝えて gtm-workflow の Upgrade に引き継ぎます。Doctor の「Agent runs the latest GTM Skills release」という行は、アップグレードが必要なタイミングを示します。ホスト型エージェントも Slack で知らせます（updates）。

名前は slug によって固定されています。gtm-<slug>（ワークスペースリポジトリ）、gtm-agent-<slug>（エージェントリポジトリとプロジェクト）、gtm-<slug>（リポジトリと同じ名前のワークフロープロジェクト）、gtm-<slug>-share（公開共有と Webhook リレーのプロジェクト）、slack/gtm-agent-<slug>（コネクター）、Neon データベース gtm-<slug>（ワークフロープロジェクトにのみ接続）。このスキルを使う前に手動でデプロイしたものは、その名前が維持されます。上書き値として渡してください。

出力

Slack で応答するライブエージェントです。ワークスペースのリポジトリと連携し、断られない限り、ライブのワークフロープロジェクトにも連携します。医師のレポートと、Slack に送る 2 行：アプリを招待し、次に @gtm-agent-<slug> set up our GTM workspace を送信します。

例外

シークレットが会話を通過することはありません。スクリプトがシークレットを生成し、vercel env add で配置します。エージェントのホストは、ワークスペースのリポジトリに対する Git リクエストにのみ GTM_GITHUB_TOKEN を追加します。このトークンは、そのリポジトリだけに制限されたファイングレイン PAT（Contents の読み取りと書き込み）です。セットアップでは CLI 自体のログインを使用せず、終了コード 2 で停止してトークンの作成方法を案内します。再実行時はユーザー自身のターミナルの GTM_GITHUB_TOKEN からトークンを取得し、ファインマイニングされていないトークン（github_pat_…）は受け付けません。Vercel Hobby アカウントではチームを作成できません。Pro チームが必要であることを伝えて停止してください。Vercel GitHub アプリをインストールしていない GitHub 組織では、vercel git connect が失敗します。インストール先（Vercel → Settings → Git）を案内し、再実行してください。Vercel の設定を更新しても Slack 側には反映されないことがあります。Slack configuration に従ってください。成功を報告する前に、Doctor が両側の設定とインストール済みトークンを検証する必要があります。このスキルと併せて gtm-workspace と gtm-workflow がインストールされている必要があります。どちらかがない場合は、npx skills add eliasstravik/gtm-skills -s <name> -y でインストールするよう伝えてください（このスキルがグローバルスキルディレクトリにある場合は、-g を追加します）。その後、再試行してください。

保護されたワークフロービューアー

ワークフロープロジェクトは、すべてのデプロイで Vercel Authentication によって保護されます。エージェントは、プロジェクトに用意された唯一の自動化バイパス（アプリ側からは VERCEL_AUTOMATION_BYPASS_SECRET として認識されます）を使ってアクセスします。gtm-workflow のセットアップは、このバイパスをエージェント上の GTM_WORKFLOW_BYPASS_SECRET に保存します。バイパスがモデルから見えるエクスポートやユーザー向けリンクに含まれることはありません。ワークフロープロジェクトにはバイパスを必ず 1 つだけ保持します（Doctor は余分なバイパスを検出します）。エージェント側に保存されたものが、エージェント専用ルートで受け付けられるバイパスです。置き換えるには、エージェント上の GTM_WORKFLOW_BYPASS_SECRET を削除し、そのセットアップを再実行してください。Webhook の送信元は、共有プロジェクトのリレー（https://gtm-<slug>-share.vercel.app/api/intake/<workflow>）に POST します。リレーは OIDC ID を使って署名付きイベントを転送します。送信元にバイパスを渡してはいけません。workflow viewer を参照してください。

QC

• Connections は既存のプライベートワークフロープロジェクトにあります。デプロイ後、ログイン済みブラウザーからアクセスできることを確認してください。設定だけでは準備完了とはいえません。ネイティブアカウントへのログイン、プロバイダーの同意、Slack 固有の操作には人間による対応が必要な場合があります。
• シークレットの値が会話や返信に含まれていないこと。
• デプロイ完了とする前に、Doctor が「All good.」で終わっていること。失敗した行はすべて、修正方法とともに報告されていること。ライブのスモークテストでは、メンション、プライベートチャンネル、DM、グループ DM でのメンション、ワークフローへの返信、ファイルのダウンロード／アップロード、承認を確認します。承認済みのテスト用会話を使用してください。
• 最後の返信には Slack に送る 2 行だけを記載し、コミット、ビルド、チェックについては触れないこと。

参考資料

スクリプトが作成するもの、すべての変数、手作業で行う場合の手順については setup.md を参照してください。interactions には対話例があります。gtm-workspace の資料：interaction、contract。gtm-workflow の資料：deploy.md。