# Admin

> Local machine administration for Windows, WSL, macOS, Linux. Install tools, check if software is installed, manage packages, configure dev environments. Works with winget, scoop, brew, apt, npm, pip, uv. Profile-aware: adapts to your preferences. Use when: install 7zip, is git installed, clone repo, check if node installed, add to PATH, configure MCP servers, manage dev tools, set up environment. NOT for: VPS, cloud servers, remote infrastructure → use admin-devops skill.

- Skill: `evolv3ai/admin` (Agent Skill, multi-file: 69 files)
- Install (CLI): `npx skillmds@latest add evolv3ai/admin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evolv3ai/admin/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: evolv3ai (https://skillmd.com/u/evolv3ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/evolv3ai/admin

---


# Admin - Local Machine Companion (Alpha)

---

## 🛑 PROFILE GATE — MANDATORY FIRST STEP

**HALT. You MUST check for a profile before ANY operation. This is non-negotiable.**

### Step 1: Test Profile Exists

**PowerShell (Windows):**
```powershell
pwsh -NoProfile -File "$HOME\.claude\skills\admin\scripts\Test-AdminProfile.ps1"
```

**Bash (WSL/Linux/macOS):**
```bash
~/.claude/skills/admin/scripts/test-admin-profile.sh
```

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

### Step 2: If `exists: false` → HALT AND RUN SETUP

**DO NOT CONTINUE with the user's task. You must create a profile first.**

Use the TUI interview below to gather preferences, then call the setup script.

---

## 🎤 TUI Setup Interview (Agent-Driven)

When profile does not exist, ask these questions using your TUI capabilities (e.g., `AskUserQuestion`).

### Q1: Storage Location (Required)

Ask: **"Will you use Admin on a single device or multiple devices?"**

| Option | Description |
|--------|-------------|
| Single device (Recommended) | Local storage at `~/.admin`. Simple, no sync needed. |
| Multiple devices | Cloud-synced folder (Dropbox, OneDrive, NAS). Profiles shared across machines. |

If "Multiple devices" selected, follow up: **"Enter the path to your cloud-synced folder"**
- Examples: `C:\Users\You\Dropbox\.admin`, `~/Dropbox/.admin`, `N:\Shared\.admin`

### Q2: Tool Preferences (Optional)

Ask: **"Set tool preferences now, or use defaults?"**

If yes, ask each:
- **Package manager:** winget (default) / scoop / choco / brew / apt
- **Python manager:** uv (default) / pip / conda / poetry
- **Node manager:** npm (default) / pnpm / yarn / bun
- **Default shell:** pwsh (default) / powershell / bash / zsh

### Q3: Inventory Scan (Optional)

Ask: **"Run a quick inventory scan to detect installed tools?"**
- Yes: Scans for git, node, python, docker, ssh, etc. and records versions
- No: Creates minimal profile, tools detected on first use

---

## 🔧 Create Profile (After Interview)

Pass the user's answers to the setup script.

**PowerShell:**
```powershell
pwsh -NoProfile -File "$HOME\.claude\skills\admin\scripts\New-AdminProfile.ps1" `
  -AdminRoot "C:/Users/You/.admin" `
  -PkgMgr "winget" `
  -PyMgr "uv" `
  -NodeMgr "npm" `
  -ShellDefault "pwsh" `
  -RunInventory
```

**Bash:**
```bash
~/.claude/skills/admin/scripts/new-admin-profile.sh \
  --admin-root "$HOME/.admin" \
  --pkg-mgr "brew" \
  --py-mgr "uv" \
  --node-mgr "npm" \
  --shell-default "zsh" \
  --run-inventory
```

Add `-MultiDevice` (PowerShell) or `--multi-device` (Bash) if user selected multi-device setup.

### After Profile Created

1. Verify: Re-run `Test-AdminProfile.ps1` or `test-admin-profile.sh` → should return `exists: true`
2. Load profile: See `references/profile-gate.md` for load commands
3. **Now** proceed with the user's original task

---

## CRITICAL: Secrets and .env

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

## Task Qualification (MANDATORY)
- If the task involves **remote servers/VPS/cloud**, stop and hand off to **admin-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 |
| **Remote servers/cloud** | **→ Use admin-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:

- PowerShell: `scripts/Log-AdminEvent.ps1`
- Bash: `scripts/log-admin-event.sh`

Example (bash):
```bash
source ~/.claude/skills/admin/scripts/log-admin-event.sh
log_admin_event "Installed ripgrep" "OK"
```

## 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`