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).

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

Three backends available, configured via ADMIN_SECRETS_BACKEND in ~/.admin/.env:

Backend	Storage	Best For
`infisical`	Infisical Cloud	Multi-device, audit trail
`vault` (default)	`$ADMIN_ROOT/vault.age`	Single device, offline
`env`	`$ADMIN_ROOT/.env`	Legacy

Fallback chain: infisical → vault → env. If the primary backend is unavailable, scripts automatically try the next.

CLI (Bash): secrets KEYNAME | secrets --list | secrets --status | secrets --backend infisical --list

CLI (PowerShell): secrets.ps1 KEY | secrets.ps1 -List | secrets.ps1 -Status | secrets.ps1 -Backend infisical -List

Migration: secrets --migrate-to-infisical pushes vault contents to Infisical Cloud.

Guides: references/vault-guide.md (age vault), references/infisical.md (Infisical Cloud)

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: Infisical Cloud (primary) → age 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    capabilities, history           (speaker convention)
        ↓
  Infisical Cloud (primary) → vault.age (fallback) → .env (legacy)

Satellite .env (~/.admin/.env): Per-device bootstrap. Points to ADMIN_ROOT, configures secrets backend.
Root .env ($ADMIN_ROOT/.env): Manifest (all keys visible, secrets in vault/Infisical).
Profile JSON ($ADMIN_ROOT/profiles/{DEVICE}.json): Full device config. Optionally synced via GitHub repo.
Secrets: Infisical Cloud (primary) → $ADMIN_ROOT/vault.age (fallback) → .env (legacy).

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)

Detect environment (Windows/WSL/Linux/macOS)
Load profile via profile gate
Check if tool already installed (profile.tools)
Use preferred package manager
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