agent-spawner

完全な Claude エージェントをスキャフォールドします — ペルソナ、マネージド / ローカルランタイム、検証済みチャネルアダプタ、IDE設定、オートスタートユニット、デプロイ可能なzipファイル、およびオプショナルなSSH/SCPデプロイステップをリモートLinuxホストへ実行します。

主要対象OS：Linux。 Windows も生成されます（スキャフォールダーはタスクスケジューラXMLを出力）ですが、デフォルト、ドキュメント、デプロイパスはLinuxを想定しています。

このスキルが生成するもの

ユーザーからの単一のコマンド（「comms という名前のオペレーション用エージェントを作成、ハイブリッド型、Telegram + Slackチャネル」など）が与えられると、このスキルは以下を含むエージェントフォルダを生成します：

<agent-name>/
├── persona.json                 # spec card (name, voice, system prompt, tools)
├── managed/
│   └── definition.json          # POST body for Managed Agents API
├── local/
│   ├── agent.py                 # Agent SDK runtime
│   └── bridge.py                # HMAC-verified caller into the managed agent (hybrid only)
├── channels/
│   ├── telegram.py              # bot with chat-ID allowlist + PIN lock
│   ├── slack.py                 # (if requested)
│   └── discord_bot.py           # (if requested)
├── ide/
│   ├── jetbrains-external-tool.xml
│   ├── jetbrains-run-config.xml
│   └── vscode-tasks.json
├── autostart/
│   ├── systemd-user.service     # ~/.config/systemd/user/  (primary)
│   └── windows-task.xml         # schtasks /Create /XML … (secondary)
├── .env.example                 # all secrets, none committed
├── README.md                    # human-readable setup
└── <agent-name>.zip             # everything above, ready to ship

ワークフロー

1. 仕様を引き出す

ユーザーが指定していない場合は、以下を1つの短いバッチメッセージで確認します：

• エージェント名 — snake_case形式（例：comms、ops、intake）
• 製品 / 名前空間 — フォルダグループ化とPythonパッケージ名に使用する自由形式の文字列（例：myapp、acme、side-project）
• タイプ — managed（クラウド、カスタマーファシング）、local（開発マシンまたはサーバーで実行）、または hybrid（ローカルエージェントがマネージドピアに委譲）
• チャネル — telegram、slack、discord、または none（バックエンドのみ）
• システムプロンプト / ロール — 1～2文
• MCPサーバー — オプショナル、HTTPS MCPのURLリスト（マネージドエージェントはHTTPが必須、STDIOはサポートされていません — references/managed-vs-local.md 参照）

ハイブリッドの場合は、以下も確認します：ローカルエージェントが委譲先とするマネージドエージェントはどれですか？（名前とマネージドエージェントのセッションエンドポイントのベースURL）

2. 関連するリファレンスを読む

ファイルを生成する前に、適用するものを読みます：

• references/architecture.md — レイヤー化されたエージェントスタック。セッションごと1回読みます。
• references/managed-vs-local.md — 各々をいつ選ぶか、HMACブリッジプロトコル、managed-agents-2026-04-01 ベータヘッダ、MCPの制約。managed または hybrid エージェントの場合に読みます。
• references/channels.md — 4段階のセキュリティモデル（allowlist → PIN → exfil guard → audit）、チャネルごとの注意点。チャネルを持つエージェントの場合に読みます。
• references/ide-integration.md — JetBrains External Tools形式、VSCode タスクスキーマ。IDE設定を生成するときに読みます。
• references/deploy.md — SCP/SSHデプロイスクリプトの動作、SSHキー検出、リモートホスト上で検証すべき内容。

3. スキャフォールダーを実行する

python scripts/scaffold_agent.py \
  --name <name> \
  --product <namespace> \
  --type <managed|local|hybrid> \
  --channels <comma-separated or 'none'> \
  --system-prompt "<one or two sentences>" \
  --mcp-servers "<comma-separated URLs or empty>" \
  --delegate-to <managed-agent-name> \   # hybrid only
  --delegate-url <https://...> \         # hybrid only
  --output-dir <absolute path>

デフォルトの --output-dir：Linux上では ~/code/<product>/agents/<name>。Windowsでもスキャフォールダーはフォワードスラッシュを受け入れて正規化します。ユーザーがClaude Codeセッション内で明確なリポジトリルートがある場合は、作業ディレクトリから推測します。

スキャフォールダーは templates/ のテンプレートを埋めて、ブリッジ用のHMACシークレットを生成し、すべての必要なキーで .env.example を書き込み、READMEを作成します。

4. 検証と説明

スキャフォール後、ユーザーに作成された内容のツリーを表示し、以下を指摘します：

1. .env に記入するシークレット — 名前で列挙（例：ANTHROPIC_API_KEY、TELEGRAM_BOT_TOKEN、TELEGRAM_ALLOWED_CHAT_IDS、BRIDGE_HMAC_SECRET）。
2. 検証ハンドシェイク — ハイブリッドエージェントの場合、HMACシークレットが両端で一致する必要があることを指摘します。
3. 起動方法 — IDE内（XML設定をインポート）またはコマンドラインで python local/agent.py / systemd-userを使用します。

5. zipをパッケージ化する

python scripts/package_agent.py <output-dir>

.env、.venv、キャッシュディレクトリを除くすべてをバンドルします。エージェントフォルダ内に <agent-name>.zip を生成します。

6. （オプショナル）リモートLinuxホストへデプロイする

scripts/deploy.sh <ip-or-host> <agent-dir> [--user ubuntu] [--key ~/.ssh/id_ed25519]

このスクリプトは：

1. SSHキーを検出 — ユーザーが指定した --key、ssh-agent にロードされているキー、または ~/.ssh/id_ed25519 / id_ecdsa / id_rsa を順番に試します。
2. 接続をテスト — 各候補に対して ssh -o BatchMode=yes <user>@<host> true を実行、1つが成功するまで試します。すべて失敗した場合は、リストを報告して ssh-copy-id を提案します。
3. zipをコピー — scp でパッケージ化された <agent-name>.zip をリモートホストの ~/agents/ にコピーします（scp が利用できない場合はSSH-tar にフォールバック）。
4. オプショナルな --setup — unzip、uv でvenvを作成、依存関係をインストール。エージェントは起動しません。
5. オプショナルな --enable-systemd — systemd-user ユニットをインストールして有効化。

このスキルは VPSのプロビジョニング、クラウドアカウントの作成、またはDNS管理は 行いません。既にSSHアクセス権を持つ既存のLinuxホストにのみデプロイします。references/deploy.md を参照。

デフォルト

ユーザーが指定しない場合は、以下を前提とします：

• OS — Linux（systemd-user autostart、~/code/<product>/agents/<name> レイアウト）。クロスプラットフォーム対応はコスト無いため、Windows Task Scheduler XMLも生成します。
• Python — 3.11以上、依存関係管理に uv を使用（requirements.txt ではなく pyproject.toml）。
• MCPトランスポート — HTTP/SSE、STDIOは使用しない（マネージドエージェント必須、ローカルも同じにするとハイブリッドが容易）。
• Telegram をデフォルトチャネルに（ユーザーが「チャネル yes」と言っても選択しない場合）— 最小限のセットアップ手間。

このスキルが明確に 行わない こと

• インフラをプロビジョニングしない。 VPS作成なし、クラウドAPI呼び出しなし、DNS管理なし。既にコントロール下にあるホストへSSH経由でデプロイするのみです。
• JetBrains プラグインを発明しない。 本当の統合は、今日、External Tools + Run Configurations 経由です。
• 音声 / war-room レイヤーを有効にしない。 スコープ外。
• 生成されたファイルにシークレットを保存しない。 すべての機密情報は .env に入り、自動的にgitignoreされます。

反論するべきとき

• マネージドエージェント + STDIO MCP → 制約を説明。（a）MCPサーバーを公開ホストする、または（b）エージェントをローカルにする、という選択肢を提示します。
• 空の allowlist を持つチャネル → 拒否。セキュリティモデルのリング1は交渉不可です。
• 動作するSSHキーなしで未知のホストへデプロイ → 停止、どのキーが試されたかを報告し、再試行前に ssh-copy-id <user>@<host> を提案。パスワードは黙って促さない。