Skip to content

Agent Skills

Windows MCP Server ships two Agent Skills, bundled in the plugin. Agent Skills give the AI concise, task-focused guidance on how to use the tools well: when to prefer semantic UI Automation over screenshots, how to handle DPI and multi-monitor layouts, how to work with browsers and Windows security boundaries, and how to drive the same tools from the command line.

Both skills are installed automatically with the plugin for GitHub Copilot CLI and Claude Code.

windows-automation

Semantic-first guidance for driving Windows apps through the MCP server. Full definition at plugin/skills/windows-automation/SKILL.md.

Context

This plugin bundles the Windows MCP Server for Windows-only desktop automation. The server is strongest when you let Windows expose semantic UI information instead of guessing from screenshots.

Preferred workflow

  1. Use window_management to find or activate the target window.
  2. Use ui_find, ui_read, ui_click, and ui_type for normal controls.
  3. Use ui_read_table to extract a grid, table, or details-view list into structured rows + headers in one call instead of scraping cells with repeated ui_read.
  4. Use file_save for Save / Save As flows and file_open for Open flows instead of sending raw keyboard shortcuts.
  5. Use clipboard (get/set/clear) for fast bulk text IO — pair it with copy/paste hotkeys.
  6. Use ui_batch to run a multi-step sequence in one call, and ui_macro to save that sequence by name and replay it later.
  7. Only fall back to screenshot_control, mouse_control, or keyboard_control when the UI Automation tree is missing or the target is a custom canvas.

Patterns

Semantic-first automation

  • Prefer element names, control types, automation IDs, and window handles over screen coordinates.
  • Re-check the UI tree after dialogs, page changes, or tab switches.
  • Treat screenshots as discovery or fallback tools, not the primary control surface.

Screenshot fallback

  • Use screenshot_control when the app is a game, canvas, OpenGL surface, or other custom-drawn UI.
  • If you need coordinates, get them from the annotated screenshot output first.
  • Expect coordinate-based automation to be more fragile across DPI, layout, and monitor changes.

Multi-monitor and DPI

  • Use monitor-aware tools instead of assuming the primary display.
  • Negative coordinates are normal on virtual desktops with monitors positioned left or above the primary display.
  • Keep work window-relative when possible to avoid DPI and layout drift.

Browsers and signed-in sessions

  • Treat Edge and Chrome page content like any other semantic UI surface: start with window_management, then use ui_find, ui_click, ui_type, and ui_read against visible text or ARIA labels.
  • To read the readable content of a web page, call ui_read with format: "article": it returns the main article text only (navigation chrome, breadcrumbs, and "in this article" rails removed, inline link URLs stripped, headings/lists as markdown) — far more token-efficient than the raw document dump. Reading the live signed-in window this way also works for authenticated/internal pages an HTTP fetch cannot reach.
  • For authenticated or SSO-only sites, reuse an existing signed-in browser window/session first before launching the URL again.
  • Do not interpret a Chromium launcher helper exiting immediately as a failed launch until you check whether the existing browser session already opened or focused the target page.
  • Keep browser chrome (address bar, tabs, profile menus, extension flyouts) as best-effort; page content is the strong path.

Windows security boundaries

  • UAC prompts and elevated windows are on a secure boundary. Non-elevated automation cannot interact with them.
  • If a tool reports an elevation mismatch, re-run the MCP server at the same privilege level as the target app.

Anti-patterns

  • Do not start with screenshot clicks when a normal desktop app exposes accessible controls.
  • Do not save files with raw Ctrl+S if a Save As dialog might appear.
  • Do not assume coordinates are stable across machines, themes, or display scaling.

windows-cli

Guidance for the token-efficient wincli command line — the twin entry point that mirrors the MCP tools as shell commands (identical JSON output), ideal for coding agents with terminal access. Full definition at plugin/skills/windows-cli/SKILL.md.

Context

wincli is the command-line twin of the Windows MCP server. Every command calls the exact same underlying tool, so behavior and JSON output are identical to the MCP tools - only the entry point differs. Prefer wincli when you already have a shell: one small command vocabulary costs far fewer tokens than loading every MCP tool schema, and each call is stateless (window handles are OS-global, so there is no server session to keep alive).

Discovery (do this first)

  • wincli --help - the command map and a common workflow.
  • wincli tools - every command with its options.
  • wincli tools --json - machine-readable tool manifest (names, descriptions, JSON input schemas); the same surface the MCP server exposes via tools/list. Parse this to construct calls precisely.
  • wincli guidance - the full semantic-automation guide (same text the MCP host receives).

Preferred workflow

  1. wincli window find --title <part> (or wincli app --path <exe>) to get a window handle.
  2. wincli ui snapshot --window <handle> to see the accessible element tree.
  3. wincli ui find|click|type|select|read --window <handle> ... for normal controls.
  4. wincli ui read-table --window <handle> --automation-id <grid> to pull a grid/table/details-list into structured rows + headers in one call. For a web page, add --format article to wincli ui read to get clean main-content text (nav/breadcrumb chrome and inline link URLs stripped, headings/lists as markdown).
  5. wincli file-save --window <handle> --path <file> for Save / Save As - never raw Ctrl+S. Use wincli file-open --window <handle> --path <file> for Open flows.
  6. wincli clipboard get|set|clear for fast bulk text IO; wincli macro save|run|list|get|delete to persist a ui batch sequence and replay it by name.
  7. Fall back to wincli screenshot, wincli mouse, or wincli keyboard only for custom-drawn UI.

Patterns

Semantic-first automation

  • Target elements by --name, --name-contains, --control-type, or --automation-id, not coordinates.
  • Add --with-snapshot to ui click/ui type/ui select to get the updated tree back in the same call (perceive + act fused - avoids a second round trip).
  • Use ui batch --window <h> --steps '<json>' to run an ordered sequence (e.g. [{"action":"type","automationId":"UsernameInput","text":"me"},{"action":"click","name":"Submit"}]) in a single invocation.

Waiting

  • Use ui wait --window <h> --name <x> (or --mode disappear) instead of sleeping, so automation stays fast and deterministic after dialogs, navigation, or tab switches.

Macros (record & replay)

  • Save a proven ui batch sequence once: wincli macro save --name login --steps '<json>'.
  • Replay it against any window: wincli macro run --name login --window <h>.
  • Manage saved macros with wincli macro list|get --name <x>|delete --name <x>.

Clipboard

  • wincli clipboard set --text "<value>" then paste with wincli keyboard press --key v --modifiers ctrl.
  • Copy in the app (wincli keyboard press --key c --modifiers ctrl) then wincli clipboard get to read it.

Exit codes (script on these)

  • 0 success, 1 tool error (inspect the JSON error field), 2 usage error (bad arguments).

Output

  • stdout is the tool's JSON payload - parse it directly. Diagnostic detail is available on any command via --include-diagnostics.

Anti-patterns

  • Do not start with mouse/screenshot clicks when the app exposes accessible controls.
  • Do not save files with raw keyboard press --key s --modifiers ctrl when a Save As dialog may appear; use file-save.
  • Do not assume coordinates are stable across machines, themes, or display scaling.
  • Do not keep re-launching an app to "retry" - reuse the existing window handle.