admin

Admin - Local Machine Companion (Alpha)

Script path resolution: When Claude Code loads this file, it provides the full path. All scripts/ references below are relative to this file's directory. Derive SKILL_DIR from this file's path and prepend it when running scripts (e.g., if loaded from /path/to/skills/admin/SKILL.md, run /path/to/skills/admin/scripts/test-admin-profile.sh).

---

Profile Gate — Mandatory First Step

Check for a profile before any operation. No profile means no preferences, no logging path, no state.

Bash (WSL/Linux/macOS):

scripts/test-admin-profile.sh

PowerShell (Windows):

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

Returns JSON: {"exists":true|false,"path":"...","device":"...","platform":"..."}

If exists: false — stop and run the TUI setup interview before proceeding. Full details: references/profile-gate.md (discovery, TUI interview, create commands, troubleshooting).

Fallback: When Scripts Fail

If both bash and PowerShell test scripts fail (e.g., shell not available, permission denied, script missing from plugin cache), use native Claude tools to check directly:

1. Check satellite .env — Read ~/.admin/.env to get ADMIN_ROOT and ADMIN_DEVICE
2. Check profile JSON — Read $ADMIN_ROOT/profiles/$ADMIN_DEVICE.json
3. If both exist, proceed normally using the values read from these files
4. If neither exists, run the TUI setup interview (see references/profile-gate.md)

---

CRITICAL: Secrets and .env

• NEVER store live .env files or credentials inside any skill folder.
• .env.template files belong only in assets/ within a skill.
• Store live secrets in ~/.admin/.env and reference from there.

Secrets Management (v4.0 — 3-Project Split)

Secrets are organized across 3 Infisical projects by trust boundary, with folder hierarchies:

Project	Trust Boundary	Contents
admin-operator	Operator	Provider keys, LLM tokens, Cloudflare, Google creds
admin-runtime	Runtime (scoped)	Agent bot tokens, deployment passwords
customer-*	Customer (isolated)	Per-customer OpenClaw config

4-layer model: age key → vault (bootstrap) → Infisical Cloud (3 projects) → generated runtime files

URI-based access (new in v4.0):

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

Legacy CLI (still works via fallback):

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

Runtime rendering: render-runtime.sh resolves all secretRefs/fileRefs from the profile and writes $ADMIN_ROOT/generated/.env for scripts that don't need live Infisical access.

Guides: references/secrets-architecture.md (full model), references/infisical.md (setup), references/vault-guide.md (fallback)

Architecture

Ecosystem Map

admin (core)
  ├── 9 satellite skills: devops, oci, hetzner, contabo, digital-ocean, vultr, linode, coolify, kasm
  ├── 6 agents: profile-validator, docs-agent, verify-agent, tool-installer, mcp-bot, ops-bot
  ├── Profile system: ~/.admin/.env (satellite) → $ADMIN_ROOT/profiles/*.json (+ GitHub sync)
  ├── Secrets: 3 Infisical projects (operator/runtime/customer) → vault (fallback) → .env (legacy)
  └── SimpleMem: Long-term memory across sessions (graceful degradation)

Data Flow

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

• Satellite .env (~/.admin/.env): Per-device bootstrap. Points to ADMIN_ROOT, configures secrets backend.
• Root .env ($ADMIN_ROOT/.env): Bootstrap only (ADMIN_ROOT, ADMIN_DEVICE, ADMIN_PLATFORM, ADMIN_SECRETS_BACKEND).
• Profile JSON ($ADMIN_ROOT/profiles/{DEVICE}.json): Full device config with secretRefs (URI pointers) and fileRefs.
• Projects config ($ADMIN_ROOT/config/infisical-projects.json): Project slug → ID mapping.
• Generated ($ADMIN_ROOT/generated/.env, compat.env): Pre-resolved secrets for scripts that don't need live Infisical access.

Agent Roster

Agent	Model	Role	Tools
profile-validator	haiku	JSON validation, read-only health check	Read, Bash, Glob
docs-agent	haiku	File I/O documentation updates	Read, Write, Glob, Grep
verify-agent	sonnet	System health checks, no Write	Read, Bash, Glob, Grep
tool-installer	sonnet	Install software per profile prefs	Read, Write, Bash, AskUserQuestion
mcp-bot	sonnet	MCP server diagnostics and config	Read, Write, Bash, Glob, Grep
ops-bot	sonnet	Multi-step operations (migration, import, bulk config)	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion

All agents use SimpleMem graceful degradation and profile gate as first step. Details: references/agent-teams.md, references/memory-integration.md

Satellite Dependency Graph

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: Core profile, logging, tool installation. Required by everything.
• devops: Server inventory, SSH, deployment coordination. Required by all infrastructure.
• Provider skills (oci, hetzner, etc.): Provision VMs. Independent of each other.
• App skills (coolify, kasm): Deploy TO servers. Require a provisioned server from a provider skill.

Task Qualification (MANDATORY)

• If the task involves remote servers/VPS/cloud, stop and hand off to devops.
• If the task is local machine administration, continue.
• If ambiguous, ask a clarifying question before proceeding.

Task Routing

Task	Reference
Install tool/package	references/{platform}.md
Windows administration	references/windows.md
WSL administration	references/wsl.md
macOS/Linux admin	references/unix.md
MCP server management	references/mcp.md
Skill registry	references/skills-registry.md
Memory integration	references/memory-integration.md
Secrets / Infisical setup	references/infisical.md
Vault (age encryption)	references/vault-guide.md
Profile sync (GitHub)	references/remote-profile.md
Remote servers/cloud	→ Use devops skill

Profile-Aware Adaptation (Always Check Preferences)

• Python: preferences.python.manager (uv/pip/conda/poetry)
• Node: preferences.node.manager (npm/pnpm/yarn/bun)
• Packages: preferences.packages.manager (scoop/winget/choco/brew/apt)

Never suggest install commands without checking preferences first.

Package Installation Workflow (All Platforms)

1. Detect environment (Windows/WSL/Linux/macOS)
2. Load profile via profile gate
3. Check if tool already installed (profile.tools)
4. Use preferred package manager
5. Log the operation

Logging (MANDATORY)

Log every operation with the shared helpers.

Bash — params: MESSAGE LEVEL (INFO|WARN|ERROR|OK):

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

PowerShell — params: -Message -Level (INFO|WARN|ERROR|OK):

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

Note: There are no -Tool, -Action, -Status, or -Details parameters. Use -Message with a descriptive string.

Scripts / References

• Core scripts: scripts/ (profile, logging, issues, AGENTS.md)
• MCP scripts: scripts/mcp-*
• Skills registry scripts: scripts/skills-*
• References: references/*.md

---

Quick Pointers

• Cross-platform guidance: references/cross-platform.md
• Shell detection: references/shell-detection.md
• Device profiles: references/device-profiles.md
• PowerShell tips: references/powershell-commands.md
• Infisical secrets: references/infisical.md
• Remote profile sync: references/remote-profile.md