# Microsoft Powertoys

> Comprehensive operational skill specification for Anthropic Claude to automate, script, troubleshoot, and optimize Microsoft PowerToys, FancyZones, PowerToys Run, Keyboard Manager, Awake, and settings.json automation.

- Skill: `alivirgo/microsoft-powertoys` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add alivirgo/microsoft-powertoys`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alivirgo/microsoft-powertoys/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alivirgo (https://skillmd.com/u/alivirgo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alivirgo/microsoft-powertoys

---


# Microsoft PowerToys System Utilities AI Skill Guide (Claude)

## Overview & Engine Architecture
Microsoft PowerToys is a suite of system utilities developed by Microsoft in C++ and C# / WinUI 3 to tune and streamline the Windows desktop experience. The architecture comprises a central **Runner Daemon (`PowerToys.exe`)** orchestrating independent submodule executables: **FancyZones (`PowerToys.FancyZones.exe`)** for multi-zone window grid snapping, **PowerToys Run (`PowerToys.PowerLauncher.exe`)** for modular desktop search, **Keyboard Manager (`PowerToys.KeyboardManagerEngine.exe`)** for low-level key remapping, **Awake (`PowerToys.Awake.exe`)** for execution state power overrides, and **Text Extractor (`PowerToys.TextExtractor.exe`)** for Windows Media OCR. Claude operates as a Principal Windows Systems Architect and PowerToys Operations Specialist, specializing in **programmatic `settings.json` configuration**, **FancyZones layout automation**, **UIPI privilege level orchestration**, and **submodule crash diagnostics**.

### PowerToys Modular System Architecture & Process Stack

```
┌─────────────────────────────────────────────────────────────┐
│                 Microsoft PowerToys Stack                   │
│                                                             │
│  Central Runner & WinUI 3 Dashboard                         │
│  ├── `PowerToys.exe` Central Controller & Tray Host         │
│  ├── WinUI 3 Settings Dashboard (`PowerToys.Settings.exe`)  │
│  └── Central Config Store (`%LOCALAPPDATA%\Microsoft\PT\`) │
│                                                             │
│  Submodule Process Ecosystem                                │
│  ├── FancyZones (`PowerToys.FancyZones.exe` Win32 Hooks)    │
│  ├── PowerLauncher (`PowerToys.PowerLauncher.exe` WPF / C#) │
│  ├── KeyboardManager (`PowerToys.KeyboardManagerEngine.exe`)│
│  ├── Awake (`PowerToys.Awake.exe` `SetThreadExecutionState`)│
│  └── TextExtractor (`Windows.Media.Ocr` Screen Scraper)     │
└─────────────────────────────────────────────────────────────┘
```

---

## Operational Capabilities & Agent Directives

1. **Programmatic `settings.json` Manipulation**: Author PowerShell and Python scripts to automate enabling/disabling PowerToys modules, updating hotkey bindings, and deploying standardized enterprise configurations.
2. **FancyZones Multi-Monitor Grid Scripting**: Programmatically generate custom `zones-settings.json` templates defining column widths, row splits, and canvas padding.
3. **UIPI & Administrator Elevation Management**: Resolve window snapping failures on Task Manager, Registry Editor, and elevated terminals by configuring PowerToys to run with highest elevation.
4. **Awake Headless Execution Scripting**: Execute `PowerToys.Awake.exe` via CLI parameters (`--mode=indefinite --display-on=true`) during long-running builds.

---

## Production PowerShell Automation: PowerToys Module Configurator & Daemon Manager

Save this script as `Configure-PowerToys.ps1`:

```powershell
<#
.SYNOPSIS
    Microsoft PowerToys Programmatic Configuration & Daemon Manager
    Enables/disables specific modules and applies custom hotkeys via JSON settings manipulation.
#>

$PowerToysSettingsDir = "$env:LOCALAPPDATA\Microsoft\PowerToys"
$GlobalSettingsFile = "$PowerToysSettingsDir\settings.json"

function Set-PowerToysModuleState {
    param (
        [string]$ModuleName,
        [bool]$Enabled
    )

    if (-not (Test-Path $GlobalSettingsFile)) {
        Write-Error "PowerToys settings file not found at: $GlobalSettingsFile"
        return
    }

    Write-Host "--- [CONFIGURING POWERTOYS MODULE: $ModuleName] ---"

    # 1. Read and Parse Global settings.json
    $jsonContent = Get-Content -Path $GlobalSettingsFile -Raw | ConvertFrom-Json

    # 2. Update Module State in 'enabled' Dictionary
    if ($jsonContent.enabled.PSObject.Properties[$ModuleName]) {
        $jsonContent.enabled.$ModuleName = $Enabled
        Write-Host "• Updated '$ModuleName' Enabled State -> $Enabled"
    } else {
        Write-Warning "Module '$ModuleName' not found in settings.json. Adding property..."
        $jsonContent.enabled | Add-Member -NotePropertyName $ModuleName -NotePropertyValue $Enabled -Force
    }

    # 3. Save Back to Disk
    $jsonContent | ConvertTo-Json -Depth 10 | Set-Content -Path $GlobalSettingsFile -Encoding UTF8
    Write-Host "✅ Settings saved successfully to $GlobalSettingsFile"

    # 4. Gracefully Restart PowerToys Runner to Apply Changes
    Write-Host "Restarting PowerToys background runner..."
    Stop-Process -Name "PowerToys" -Force -ErrorAction SilentlyContinue
    Start-Sleep -Seconds 1
    Start-Process -FilePath "$env:LOCALAPPDATA\PowerToys\PowerToys.exe" -ErrorAction SilentlyContinue
    Write-Host "✅ PowerToys restarted."
}

# Example Executions:
# Set-PowerToysModuleState -ModuleName "FancyZones" -Enabled $true
# Set-PowerToysModuleState -ModuleName "Awake" -Enabled $true
# Set-PowerToysModuleState -ModuleName "ColorPicker" -Enabled $false
```

---

## Technical Troubleshooting Matrix

| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **FancyZones Fails to Snap Elevated Windows** | PowerToys running with standard user privileges blocked by UIPI (User Interface Privilege Isolation). | In PowerToys Settings $\rightarrow$ General, toggle **Always run as administrator** to On. |
| **PowerToys Run (Alt + Space) Hangs or Crashes** | A corrupted Wox/Community plugin or unindexed path causing an unhandled deadlock in WPF. | In Settings $\rightarrow$ PowerToys Run $\rightarrow$ Plugins, disable suspect third-party plugins or clear `%LOCALAPPDATA%\Microsoft\PowerToys\PowerToys Run\`. |
| **Keyboard Manager Remappings Stop Working** | `PowerToys.KeyboardManagerEngine.exe` low-level hook dropped following Windows sleep/wake cycle. | In Task Manager, terminate `PowerToys.KeyboardManagerEngine.exe`; the runner will automatically respawn it. |
| **Text Extractor Displays "OCR Failed"** | Required Windows OCR Language Pack not installed for current locale. | In Windows Settings $\rightarrow$ Time & language $\rightarrow$ Language $\rightarrow$ Install **OCR Component** for active language. |

---

## Command Line Syntax & Awake Execution

```bash
# 1. Keep System Awake Indefinitely with Screen ON via CLI
"%LOCALAPPDATA%\PowerToys\PowerToys.Awake.exe" --mode=indefinite --display-on=true

# 2. Keep System Awake for 2 Hours (7200 seconds)
"%LOCALAPPDATA%\PowerToys\PowerToys.Awake.exe" --mode=timed --time-limit=7200

# 3. Launch PowerToys Settings Window
"%LOCALAPPDATA%\PowerToys\PowerToys.Settings.exe"
```

### Essential File Locations
- **Settings Store**: `%LOCALAPPDATA%\Microsoft\PowerToys\settings.json`
- **FancyZones Config**: `%LOCALAPPDATA%\Microsoft\PowerToys\FancyZones\zones-settings.json`
- **Binary Directory**: `C:\Program Files\PowerToys\` or `%LOCALAPPDATA%\PowerToys\`

---

## Agent Operational Directive
> **MANDATORY**: When configuring PowerToys to manage windows across administrative tools (e.g. Task Manager, CMD, Services), always enable "Always run as administrator" in General settings to prevent UIPI hook rejection.