Admin - Context-Aware DevOps Companion

Purpose: Read your device profile, adapt instructions to your setup, route to specialist skills.

Core Value

When a GitHub repo says pip install package, this skill knows you prefer uv and suggests uv pip install package instead.

---

⚠️ STEP 0: Detect Environment (MANDATORY FIRST)

Before ANY operation, run this detection to find the profile:

# Detect environment and set ADMIN_ROOT
if grep -qi microsoft /proc/version 2>/dev/null; then
    # WSL - profile is on Windows side
    WIN_USER=$(cmd.exe /c "echo %USERNAME%" 2>/dev/null | tr -d '\r')
    ADMIN_ROOT="/mnt/c/Users/$WIN_USER/.admin"
    ENV_TYPE="wsl"
elif [[ "$OS" == "Windows_NT" || -n "$MSYSTEM" ]]; then
    # Git Bash on Windows
    ADMIN_ROOT="$HOME/.admin"
    ENV_TYPE="windows-gitbash"
elif [[ "$(uname -s)" == "Darwin" ]]; then
    # macOS
    ADMIN_ROOT="$HOME/.admin"
    ENV_TYPE="macos"
else
    # Native Linux
    ADMIN_ROOT="$HOME/.admin"
    ENV_TYPE="linux"
fi

HOSTNAME=$(hostname)
PROFILE_PATH="$ADMIN_ROOT/profiles/$HOSTNAME.json"

echo "Environment: $ENV_TYPE"
echo "Admin Root:  $ADMIN_ROOT"
echo "Profile:     $PROFILE_PATH"
echo "Exists:      $(test -f "$PROFILE_PATH" && echo 'YES' || echo 'NO')"

Critical Path Rules

Running From	Profile Location	Why
WSL	/mnt/c/Users/{WIN_USER}/.admin/profiles/	Profile lives on Windows, WSL accesses via /mnt/c
Windows Git Bash	$HOME/.admin/profiles/	Same as Windows native
Windows PowerShell	$HOME\.admin\profiles\	Windows native
Native Linux	~/.admin/profiles/	Linux home
macOS	~/.admin/profiles/	macOS home

Common Mistake

❌ WRONG: Assume ~/.admin always works

# This FAILS in WSL because ~ is /home/wsladmin, not Windows
ls ~/.admin/profiles/  # Empty or doesn't exist

✅ RIGHT: Detect environment first, then find profile

# In WSL, profile is on Windows side
ls /mnt/c/Users/Owner/.admin/profiles/  # Found!

---

Quick Start: After Detection

Bash (WSL/Linux/macOS)

# After running detection above
source /path/to/admin/scripts/load-profile.sh
load_admin_profile "$PROFILE_PATH"
show_admin_summary

PowerShell (Windows)

. scripts/Load-Profile.ps1
Load-AdminProfile -Export
Show-AdminSummary

---

The Key Innovation: Preferences

"preferences": {
  "python": { "manager": "uv", "reason": "Fast, modern, replaces pip+venv" },
  "node": { "manager": "npm", "reason": "Default, bun for speed" },
  "packages": { "manager": "scoop", "reason": "Portable installs" }
}

Always check preferences before suggesting commands.

---

Adaptation Examples

User Wants	README Says	Profile Shows	You Suggest
Install Python pkg	pip install x	preferences.python.manager: "uv"	uv pip install x
Install Node pkg	npm install	preferences.node.manager: "pnpm"	pnpm install
Install CLI tool	brew install x	preferences.packages.manager: "scoop"	scoop install x

---

Profile Sections Quick Reference

Section	What It Contains	When To Use
device	OS, hostname, hardware	Platform detection
paths	Critical locations	Finding configs, skills, keys
tools	Installed tools + paths	Check before install
preferences	User choices	Adapt commands
servers	Managed servers	SSH, deployments
deployments	.env.local references	Load provider configs
capabilities	Quick flags	Route decisions
issues	Known problems	Avoid repeating fixes
mcp	MCP server configs	MCP troubleshooting
wsl	WSL config (Windows)	Cross-platform

---

Routing Rules

Task Type	Route To	Requires
Server provisioning	admin-devops	-
OCI infrastructure	admin-infra-oci	OCI CLI configured
Hetzner infrastructure	admin-infra-hetzner	Hetzner token
Other clouds	admin-infra-{provider}	Provider credentials
Coolify installation	admin-app-coolify	Server access
KASM installation	admin-app-kasm	Server access
Windows system admin	admin-windows	Windows platform
WSL administration	admin-wsl	WSL present
Linux/macOS admin	admin-unix	Non-Windows
MCP servers	admin-mcp	-

---

Tool Installation Workflow

1. Detect environment (Step 0 above)
2. Load profile: load_admin_profile "$PROFILE_PATH"
3. Check if installed: jq '.tools.{name}.present' "$PROFILE_PATH"
4. If not installed:
   • Check preferred manager: jq '.preferences.packages.manager' "$PROFILE_PATH"
   • Construct install command for that manager
5. After install: Update profile

---

Server Operations Workflow

1. List servers: jq '.servers[]' "$PROFILE_PATH"
2. Get SSH details:

   SERVER=$(jq '.servers[] | select(.id == "cool-two")' "$PROFILE_PATH")
   

3. Handle path conversion (WSL needs to convert Windows paths):

   KEY_PATH=$(echo "$SERVER" | jq -r '.keyPath')
   # Convert C:/Users/... to /mnt/c/Users/...
   if [[ "$KEY_PATH" == *":"* ]]; then
       DRIVE=$(echo "$KEY_PATH" | cut -c1 | tr '[:upper:]' '[:lower:]')
       REST=$(echo "$KEY_PATH" | cut -c3- | sed 's|\\|/|g')
       KEY_PATH="/mnt/$DRIVE$REST"
   fi
   

---

First-Run Setup

If profile doesn't exist:

Windows (PowerShell):

.\scripts\Initialize-AdminProfile.ps1

WSL/Linux - Profile should be created from Windows side first, then accessed from WSL via /mnt/c/...

---

Capability Checks

# Load profile first, then check
HAS_DOCKER=$(jq -r '.capabilities.hasDocker' "$PROFILE_PATH")
HAS_WSL=$(jq -r '.capabilities.hasWsl' "$PROFILE_PATH")

if [[ "$HAS_DOCKER" == "true" ]]; then
    docker info
fi

---

References

• references/device-profiles.md - Profile management details
• references/routing-guide.md - Detailed routing logic
• references/first-run-setup.md - Initial setup flow
• references/cross-platform.md - Windows ↔ WSL coordination

Scripts

Script	Purpose
Load-Profile.ps1	PowerShell profile loader
load-profile.sh	Bash profile loader
Initialize-AdminProfile.ps1	Create new profile (Windows)

Related Skills

Skill	Purpose
admin-devops	Server inventory & provisioning
admin-infra-*	Cloud provider provisioning
admin-app-*	Application deployment
admin-windows	Windows administration
admin-wsl	WSL administration
admin-unix	Linux/macOS administration
admin-mcp	MCP server management