| name | admin-windows |
| description | Windows system administration with PowerShell 7.x. Profile-aware - reads your preferences
for package managers (scoop vs winget), paths, and installed tools.
Use when: Windows-specific admin tasks, PowerShell automation, PATH configuration,
package installation, bash-to-PowerShell translation.
|
| license | MIT |
| source | plugin |
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
# 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:
pwsh -NoProfile -File "$HOME\.claude\skills\admin\scripts\Setup-Interview.ps1"
DO NOT proceed with ANY task until profile exists.
Step 3: Load Profile
. "$HOME\.claude\skills\admin\scripts\Load-Profile.ps1"
Load-AdminProfile -Export
Step 4: Check Preferences Before Commands
# 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
$PSVersionTable.PSVersion
# Should show 7.x (NOT 5.1)
If PowerShell 7 is not installed:
winget install Microsoft.PowerShell
2) Load Profile (Already Required by Gate)
. ..\admin\scripts\Load-Profile.ps1
Load-AdminProfile -Export
3) Verify Environment
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
$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:
$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)
$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
# Instead of searching, use profile
$gitPath = $AdminProfile.tools.git.path
# Returns: "C:/Program Files/Git/mingw64/bin/git.exe"
Add to PATH (Permanent)
$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
# 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
[Environment]::SetEnvironmentVariable("MY_VAR", "value", "User")
Check Tool Status
Before installing, check profile:
$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
# 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
. "$HOME\.claude\skills\admin\scripts\New-AdminIssue.ps1"
New-AdminIssue -Title "7zip installation failed" -Category install -Tags @("winget","7zip")
After Installation
Update profile:
$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
# 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
# Edit
notepad $PROFILE
# Recommended: Source admin profile loader
. "$HOME\.admin\scripts\Load-Profile.ps1"
Load-AdminProfile -Export -Quiet
Capabilities Check
Before operations, verify capabilities:
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 tablereferences/package-managers.md - winget/scoop/npm/choco workflowsreferences/path-configuration.md - PATH safety and persistencereferences/environment-variables.md - Session vs permanent variablesreferences/known-issues.md - Common pitfalls and preventionreferences/OPERATIONS.md - Troubleshooting and diagnostics
