admin

管理者 - ローカルマシンコンパニオン（アルファ版）

スクリプトパスの解決：Claude Code がこのファイルを読み込むとき、完全なパスが提供されます。以下の scripts/ への参照はすべて、このファイルがあるディレクトリからの相対パスです。このファイルのパスから SKILL_DIR を導出し、スクリプトの実行時に先頭に付加してください （例：/path/to/skills/admin/SKILL.md から読み込まれた場合は、/path/to/skills/admin/scripts/test-admin-profile.sh を実行します）。

---

プロファイルゲート — 必須の最初のステップ

どの操作を行う前にも、プロファイルを確認してください。プロファイルがない場合、設定も、ログの保存先も、状態もありません。

Bash（WSL/Linux/macOS）：

scripts/test-admin-profile.sh

PowerShell（Windows）：

pwsh -NoProfile -File "scripts/Test-AdminProfile.ps1"

JSON を返します：{"exists":true|false,"path":"...","device":"...","platform":"..."}

exists: false の場合は、処理を中止し、続行する前に TUI セットアップの聞き取りを実行してください。 詳細：references/profile-gate.md（検出、TUI による聞き取り、作成コマンド、トラブルシューティング）。

フォールバック：スクリプトが失敗した場合

Bash と PowerShell の両方のテストスクリプトが失敗した場合（例：シェルを利用できない、アクセスが拒否された、プラグインのキャッシュにスクリプトがない）、Claude のネイティブツールを使って直接確認してください。

1. サテライトの .env を確認 — ~/.admin/.env を読み込み、ADMIN_ROOT と ADMIN_DEVICE を取得します
2. プロファイル JSON を確認 — $ADMIN_ROOT/profiles/$ADMIN_DEVICE.json を読み込みます
3. 両方のファイルが存在する場合は、読み取った値を使って通常どおり処理を進めます
4. どちらも存在しない場合は、TUI セットアップの聞き取りを実行します（references/profile-gate.md を参照）

---

重要：シークレットと .env

• 稼働中の .env ファイルや認証情報を、スキルフォルダー内に絶対に保存しないでください。
• .env.template ファイルは、スキル内の assets/ にのみ配置してください。
• 稼働中のシークレットは ~/.admin/.env に保存し、そこから参照してください。

シークレット管理（v4.0 — 3 プロジェクト分割）

シークレットは、信頼境界ごとに3 つの Infisical プロジェクトに分けて管理し、フォルダー階層を設けています。

プロジェクト	信頼境界	内容
admin-operator	オペレーター	プロバイダーキー、LLM トークン、Cloudflare、Google の認証情報
admin-runtime	ランタイム（スコープ制限あり）	エージェントのボットトークン、デプロイ用パスワード
customer-*	顧客（分離）	顧客ごとの OpenClaw 設定

4 層モデル：age キー → ボールト（ブートストラップ）→ Infisical Cloud（3 プロジェクト）→ 生成されたランタイムファイル

URI ベースのアクセス（v4.0 の新機能）：

resolve-secret-ref.sh "infisical://admin-operator/prod/providers/hetzner/HCLOUD_TOKEN"
secrets --project admin-operator --path /providers/hetzner HCLOUD_TOKEN

レガシー CLI（フォールバック経由で引き続き動作）：

secrets HCLOUD_TOKEN          # Falls back through: generated/.env → Infisical → vault → .env

ランタイムのレンダリング：render-runtime.sh はプロファイルからすべての secretRefs／fileRefs を解決し、Infisical への直接アクセスを必要としないスクリプト向けに $ADMIN_ROOT/generated/.env を書き込みます。

ガイド：references/secrets-architecture.md（全体モデル）、references/infisical.md（セットアップ）、references/vault-guide.md（フォールバック）

アーキテクチャ

エコシステムマップ

admin (core)
  ├── 9 satellite skills: devops, oci, hetzner, contabo, digital-ocean, vultr, linode, coolify, kasm
  ├── 7 agents: profile-validator, docs-agent, verify-agent, tool-installer, ops-bot, server-provisioner, deployment-coordinator
  ├── Profile system: ~/.admin/.env (satellite) → $ADMIN_ROOT/profiles/*.json (+ GitHub sync)
  └── Secrets: 3 Infisical projects (operator/runtime/customer) → vault (fallback) → .env (legacy)

データフロー

Satellite .env (bootstrap)  →  profile.json (device config)  →  Agent decisions
        ↓                              ↓                              ↓
  ADMIN_ROOT, DEVICE,          tools, servers, prefs,          Session logs
  PLATFORM, SECRETS_BACKEND    secretRefs, fileRefs            (~/.admin/logs/)
        ↓                              ↓
  generated/.env (pre-rendered) → Infisical (3 projects) → vault.age → .env

• サテライト .env（~/.admin/.env）：デバイスごとのブートストラップです。ADMIN_ROOT を指定し、シークレットのバックエンドを設定します。
• ルート .env（$ADMIN_ROOT/.env）：ブートストラップ専用です（ADMIN_ROOT、ADMIN_DEVICE、ADMIN_PLATFORM、ADMIN_SECRETS_BACKEND）。
• プロファイル JSON（$ADMIN_ROOT/profiles/{DEVICE}.json）：secretRefs（URI ポインター）と fileRefs を含む、デバイスの完全な設定です。
• プロジェクト設定（$ADMIN_ROOT/config/infisical-projects.json）：プロジェクトのスラッグから ID へのマッピングです。
• 生成済みファイル（$ADMIN_ROOT/generated/.env、compat.env）：Infisical への直接アクセスを必要としないスクリプト向けに、事前に解決されたシークレットです。

エージェント一覧

エージェント	モデル	役割	ツール
profile-validator	haiku	JSON の検証、読み取り専用のヘルスチェック	Read、Bash、Glob
docs-agent	haiku	ファイル I/O によるドキュメントの更新	Read、Write、Glob、Grep
verify-agent	sonnet	システムのヘルスチェック、Write は使用不可	Read、Bash、Glob、Grep
tool-installer	sonnet	プロファイル設定に基づくソフトウェアのインストール	Read、Write、Bash、AskUserQuestion
ops-bot	sonnet	複数手順の操作（移行、インポート、一括設定）	Read、Write、Edit、Bash、Glob、Grep、AskUserQuestion
server-provisioner	sonnet	各プロバイダーでのクラウド VM のプロビジョニング	Read、Write、Bash、AskUserQuestion
deployment-coordinator	sonnet	エンドツーエンドのアプリデプロイ（Coolify、KASM）	Read、Write、Bash、AskUserQuestion

すべてのエージェントは、最初のステップとしてプロファイルゲートを実行します。連携パターンについては、references/agent-teams.md を参照してください。

サテライトの依存関係グラフ

admin (core) ─── required by all satellites
  │
  ├── devops ─── required by provider + app skills
  │     │
  │     ├── oci, hetzner, contabo, digital-ocean, vultr, linode
  │     │        (provision servers)
  │     │              │
  │     └── coolify, kasm
  │           (deploy apps TO provisioned servers)
  │
  └── Profile system provides: server inventory, SSH keys, credentials (via vault)

• admin：コアプロファイル、ロギング、ツールのインストールを担当します。すべての機能で必要です。
• devops：サーバーインベントリ、SSH、デプロイの調整を担当します。すべてのインフラストラクチャで必要です。
• プロバイダースキル（oci、hetzner など）：VM をプロビジョニングします。相互に独立しています。
• アプリスキル（coolify、kasm）：サーバーにデプロイします。プロバイダースキルでプロビジョニングされたサーバーが必要です。

タスクの適格性確認（必須）

• タスクにリモートサーバー／VPS／クラウドが関係する場合は、作業を中止し、devopsに引き継ぎます。
• タスクがローカルマシンの管理であれば、続行します。
• 判断がつかない場合は、作業を進める前に確認の質問をします。

タスクの振り分け

タスク	参照先
ツール／パッケージのインストール	references/{platform}.md
Windows の管理	references/windows.md
WSL の管理	references/wsl.md
macOS/Linux の管理	references/unix.md
MCP サーバーの管理	references/mcp.md
スキルレジストリ	references/skills-registry.md
シークレット／Infisical の設定	references/infisical.md
Vault（age 暗号化）	references/vault-guide.md
プロファイルの同期（GitHub）	references/remote-profile.md
リモートサーバー／クラウド	→ devops スキルを使用
devadmin のオンボーディング／移行	references/devadmin-onboarding.md（/adopt-devadmin）
スキルのバグのエスカレーション	references/escalation-policy.md

プロファイルに応じた調整（必ず設定を確認）

• Python：preferences.python.manager（uv/pip/conda/poetry）
• Node：preferences.node.manager（npm/pnpm/yarn/bun）
• パッケージ：preferences.packages.manager（scoop/winget/choco/brew/apt）

設定を確認せずに、インストールコマンドを提案してはいけません。

パッケージのインストールワークフロー（すべてのプラットフォーム）

1. 環境を検出します（Windows/WSL/Linux/macOS）
2. プロファイルゲートを通じてプロファイルを読み込みます
3. ツールがすでにインストールされているか確認します（profile.tools）
4. 優先するパッケージマネージャーを使用します
5. 操作を記録します

ロギング（必須）

共有ヘルパーを使用して、すべての操作を記録します。

Bash — パラメーター：MESSAGE LEVEL（INFO|WARN|ERROR|OK）：

source scripts/log-admin-event.sh
log_admin_event "Installed ripgrep" "OK"

PowerShell — パラメーター：-Message -Level（INFO|WARN|ERROR|OK）：

pwsh -NoProfile -File "scripts/Log-AdminEvent.ps1" -Message "Installed ripgrep" -Level OK

注：-Tool、-Action、-Status、-Details パラメーターはありません。説明的な文字列を -Message に指定してください。

スクリプト／参照資料

• コアスクリプト：scripts/（プロファイル、ロギング、問題、AGENTS.md）
• MCP スクリプト：scripts/mcp-*
• スキルレジストリのスクリプト：scripts/skills-*
• 参照資料：references/*.md

---

クイックリファレンス

• クロスプラットフォームのガイダンス：references/cross-platform.md
• シェルの検出：references/shell-detection.md
• デバイスプロファイル：references/device-profiles.md
• PowerShell のヒント：references/powershell-commands.md
• Infisical のシークレット：references/infisical.md
• リモートプロファイルの同期：references/remote-profile.md
• devadmin のオンボーディング／移行：references/devadmin-onboarding.md（/adopt-devadmin を実行）