Windows Administration

CRITICAL MUST: 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 (or another non-skill location you control) and reference them from there.

Requires: Windows platform, PowerShell 7.x

⚠️ Profile Gate (MANDATORY - DO THIS FIRST)

STOP. Before ANY operation, you MUST check for the profile. This is not optional.

Step 1: Check Profile Exists

powershell

# Use the helper script - it handles path resolution correctly
pwsh -NoProfile -File "$HOME\.claude\skills\admin\scripts\Test-AdminProfile.ps1"

Returns JSON: {"exists":true,"path":"...","device":"CASATEN",...}

Step 2: If Profile Missing → Run Setup

If exists is false:

powershell

pwsh -NoProfile -File "$HOME\.claude\skills\admin\scripts\Setup-Interview.ps1"

DO NOT proceed with ANY task until profile exists.

Step 3: Load Profile

powershell

. "$HOME\.claude\skills\admin\scripts\Load-Profile.ps1"
Load-AdminProfile -Export

Step 4: Check Preferences Before Commands

powershell

# User wants to install a package
$preferredManager = $AdminProfile.preferences.packages.manager
# Returns: "scoop" or "winget" or "chocolatey"

Quick Start (5 Minutes)

1) Verify PowerShell 7.x

powershell

$PSVersionTable.PSVersion
# Should show 7.x (NOT 5.1)

If PowerShell 7 is not installed:

powershell

winget install Microsoft.PowerShell

2) Load Profile (Already Required by Gate)

powershell

. ..\admin\scripts\Load-Profile.ps1
Load-AdminProfile -Export

3) Verify Environment

powershell

Show-AdminSummary

Critical Rules

Always Do

•Use PowerShell 7.x (pwsh.exe), not Windows PowerShell 5.1 (powershell.exe)
•Use PowerShell cmdlets, not bash/Linux commands
•Use full paths with Test-Path before file operations
•Set PATH in Windows Registry for persistence (not just session)
•Use ${env:VARIABLE} syntax for environment variables

Never Do

•Use bash commands (cat, ls, grep, echo, export)
•Use relative paths without verification
•Modify system PATH without backup
•Run scripts without execution policy check
•Create duplicate config files (update the existing one)

Package Installation (Profile-Aware)

Check Preference First

powershell

$pkgMgr = $AdminProfile.preferences.packages.manager

switch ($pkgMgr) {
    "scoop"   { scoop install $package }
    "winget"  { winget install $package }
    "choco"   { choco install $package -y }
    default   { winget install $package }
}

Quick Reference by Manager

Manager	Install	Update	List
scoop	`scoop install x`	`scoop update x`	`scoop list`
winget	`winget install x`	`winget upgrade x`	`winget list`
choco	`choco install x -y`	`choco upgrade x`	`choco list`

Python Commands (Profile-Aware)

Check profile first:

powershell

$pyMgr = $AdminProfile.preferences.python.manager
# Returns: "uv", "pip", "conda", "poetry"

Profile Says	Instead of `pip install x`	Use
`uv`	❌	`uv pip install x`
`pip`	✅	`pip install x`
`conda`	❌	`conda install x`
`poetry`	❌	`poetry add x`

Node Commands (Profile-Aware)

powershell

$nodeMgr = $AdminProfile.preferences.node.manager
# Returns: "npm", "pnpm", "yarn", "bun"

Profile Says	Instead of `npm install`	Use
`npm`	✅	`npm install`
`pnpm`	❌	`pnpm install`
`yarn`	❌	`yarn`
`bun`	❌	`bun install`

Bash to PowerShell Translation

Bash	PowerShell	Notes
`cat file`	`Get-Content file`	Or `gc`
`cat file \| head -20`	`Get-Content file -Head 20`
`cat file \| tail -20`	`Get-Content file -Tail 20`
`ls -la`	`Get-ChildItem -Force`
`grep "x" file`	`Select-String "x" file`	Or `sls`
`echo "x"`	`Write-Output "x"`
`echo "x" > file`	`Set-Content file -Value "x"`
`echo "x" >> file`	`Add-Content file -Value "x"`
`export VAR=x`	`$env:VAR = "x"`	Session only
`export VAR=x` (perm)	`[Environment]::SetEnvironmentVariable("VAR", "x", "User")`
`test -f file`	`Test-Path file -PathType Leaf`
`test -d dir`	`Test-Path dir -PathType Container`
`mkdir -p dir`	`New-Item -ItemType Directory -Path dir -Force`
`rm -rf dir`	`Remove-Item dir -Recurse -Force`
`which cmd`	`Get-Command cmd`
`curl URL`	`Invoke-WebRequest URL`
`jq`	`ConvertFrom-Json` / `ConvertTo-Json`

PATH Operations

Check Tool Path from Profile

powershell

# Instead of searching, use profile
$gitPath = $AdminProfile.tools.git.path
# Returns: "C:/Program Files/Git/mingw64/bin/git.exe"

Add to PATH (Permanent)

powershell

$newPath = "C:/new/path"
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
if ($currentPath -notlike "*$newPath*") {
    [Environment]::SetEnvironmentVariable('PATH', "$newPath;$currentPath", 'User')
}
# Refresh session
$env:PATH = [Environment]::GetEnvironmentVariable('PATH', 'User') + ";" + [Environment]::GetEnvironmentVariable('PATH', 'Machine')

Environment Variables

From Profile

powershell

# Key paths are in profile
$AdminProfile.paths.sshKeys      # C:/Users/Owner/.ssh
$AdminProfile.paths.npmGlobal    # C:/Users/Owner/AppData/Roaming/npm
$AdminProfile.paths.projects     # D:/

Set Permanent Variable

powershell

[Environment]::SetEnvironmentVariable("MY_VAR", "value", "User")

Check Tool Status

Before installing, check profile:

powershell

$tool = Get-AdminTool "docker"
if ($tool.present -and $tool.installStatus -eq "working") {
    Write-Host "Docker already installed: $($tool.version)"
} else {
    # Install using preferred manager
    $mgr = $AdminProfile.preferences.packages.manager
    # ... install logic
}

After ANY Operation (MANDATORY)

Always log the operation and update the profile.

Log the Event

powershell

# Source the logging helper
. "$HOME\.claude\skills\admin\scripts\Log-AdminEvent.ps1"

# Log success
Log-AdminEvent -Message "Installed 7zip via winget" -Level OK

# Log failure (also creates an issue file)
Log-AdminEvent -Message "Failed to install 7zip: access denied" -Level ERROR

On Failure: Create Issue

powershell

. "$HOME\.claude\skills\admin\scripts\New-AdminIssue.ps1"
New-AdminIssue -Title "7zip installation failed" -Category install -Tags @("winget","7zip")

After Installation

Update profile:

powershell

$AdminProfile.tools["newtool"] = @{
    present = $true
    version = "1.0.0"
    installedVia = $AdminProfile.preferences.packages.manager
    path = (Get-Command newtool).Source
    installStatus = "working"
    lastChecked = (Get-Date).ToString("o")
}

# Add to history
$AdminProfile.history += @{
    date = (Get-Date).ToString("o")
    action = "install"
    tool = "newtool"
    method = $AdminProfile.preferences.packages.manager
    status = "success"
}

# Save
$AdminProfile | ConvertTo-Json -Depth 10 | Set-Content $AdminProfile.paths.deviceProfile

Execution Policy

powershell

# Check
Get-ExecutionPolicy -List

# Set for current user (recommended)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Bypass for single script
powershell -ExecutionPolicy Bypass -File script.ps1

PowerShell Profile

Location: $AdminProfile.preferences.shell.profilePath

powershell

# Edit
notepad $PROFILE

# Recommended: Source admin profile loader
. "$HOME\.admin\scripts\Load-Profile.ps1"
Load-AdminProfile -Export -Quiet

Capabilities Check

Before operations, verify capabilities:

powershell

if (-not (Test-AdminCapability "canRunPowershell")) {
    Write-Error "PowerShell not available"
    return
}

if (Test-AdminCapability "hasDocker") {
    # Docker operations safe
}

Scope Boundaries

Task Type	Route To
WSL administration	`admin-wsl`
MCP servers	`admin-mcp`
Linux/macOS admin	`admin-unix`
Cross-platform routing	`admin`

Related Skills

Task	Route To
WSL operations	`admin-wsl`
MCP servers	`admin-mcp`
Server provisioning	`admin-devops`
Profile management	`admin`

References

•references/bash-to-powershell.md - Full command translation table
•references/package-managers.md - winget/scoop/npm/choco workflows
•references/path-configuration.md - PATH safety and persistence
•references/environment-variables.md - Session vs permanent variables
•references/known-issues.md - Common pitfalls and prevention
•references/OPERATIONS.md - Troubleshooting and diagnostics