---
name: desktop-tool-builder
description: "Build or rework small Windows desktop tools (PowerShell + WinForms, with a screen-recording tool as the reference implementation): merging desktop shortcuts, global hotkeys, a resident agent and control panel, tray icon, file naming and save directory, overlay indicators that stay out of captures, launch at startup, and repeatable verification. Use to create such a tool or to fix a dead hotkey, a panel that cannot be clicked, a floating layer that blocks operations, or indicator elements that end up recorded in the video. Not for general video editing, subtitle production or platform publishing."
---

> Original skill · commissioned by the user · English edition, 2026-11-12

# Practical small-tool development skill (Windows desktop tools)

## 0. One-line principle

The value of a small tool is not in the capability call but in **few entry points, a clear state, and not interfering with what the user is doing**. 80% of rework comes from these three things, not from the business logic.

The screen-recording tool is the reference implementation of this skeleton: swap in screen capture, colour picking, OCR or file tidying and the skeleton does not change — only the "capability layer" does (ffmpeg pipeline, region selector, output format).

## 1. Decide the task type first

| Task | Read first |
|---|---|
| Build from scratch / major architecture change | [references/architecture.md](references/architecture.md), then follow the full workflow in section 3 |
| Fix one concrete failure (hotkey, click, occlusion, recorded into the video) | The matching entry in [references/pitfalls.md](references/pitfalls.md), then verify per section 7 |
| Handover / retrospective / writing the build log | [references/build-log.md](references/build-log.md) |

## 2. Recommended architecture (single Windows machine)

- **One resident agent** `agent.ps1`: registers global hotkeys, runs capabilities (record/screenshot/…), draws the indicator layer, owns the tray, writes state files
- **One panel** `menu.ps1`: main action, result actions (copy/open), settings; hides itself while executing
- **Thin command scripts** `toggle.ps1` / `copy.ps1`: only write a `run\cmd.*` command file and wait for the agent's response; they never run the capability themselves
- **Shared module** `common.ps1`: config read/write, hotkey parsing, naming rules — used by several places, so do not write one per script
- **Message pump**: the agent uses a `DoEvents` loop, not `Application.Run(hidden form)`, and never lets a clickable floating layer go through `ShowDialog`
- Config in `config.json`; runtime state in `run\*` (`state.json` / `last.json` / `hotkeys.json` / `cmd.*`)
- **Entry points may be merged, but the hotkey must be held by the resident process**, together with launch at startup

## 3. Workflow (in order, trimmable to scale)

| Stage | Action | Artefact / acceptance gate |
|---|---|---|
| S0 Scope | Confirm: capability range, hotkey, output location, tray or not, single/multi monitor, overlay or not | One requirement list; if you cannot write the acceptance condition yet, ask first |
| S1 Inventory | Read the existing `.lnk` targets, scripts, dependency programs, existing output directories | You can state "which key you press now, which script runs, where the file lands" |
| S2 Fix the contract | Output naming rule (with placeholders), config fields, run state files, where hotkeys are stored | The rule sorts correctly and has no illegal characters; the state-file fields are fixed |
| S3 Minimal loop | Trigger → execute → write to disk → result can be taken away (copy/open) | One run: correct output, clipboard/directory usable |
| S4 Interaction layer | Panel (main action / stop / result buttons / settings), selection or input layer where needed | Every entry point goes through the same command channel |
| S5 Indicator and non-interference | State indicator (e.g. blinking red dot), scope hint (e.g. recording border), panel hidden during execution | The indicator is visible on screen and never enters the user's output |
| S6 Stability | Single instance, cleanup on abnormal exit, logging, config hot reload, launch at startup | After killing the child process the state falls back and no half-written dead file remains |
| S7 Verification | Run the matrix in [references/verification.md](references/verification.md) | Deliver only when everything passes |
| S8 Delivery | Desktop entry + output-directory shortcut + `README.md` + build log + rollback path | The user can double-click and use it, with no command line |

## 4. Hard constraints (all of them are pitfalls already hit)

- **Do not hang hotkeys on the `.lnk`**: after merging into one entry it cannot hold two hotkeys; let the agent register them with `RegisterHotKey` instead. Launch at startup follows the user's request (once turned off, the panel must be opened first so the agent starts).
- **Do not pass `-WindowStyle Hidden` to `Start-Process`** to launch a script that will pop up a form: STARTUPINFO turns its first WinForms window into a hidden window. Hide the console only through `pwsh`'s own parameters.
- **A floating layer carrying clickable buttons must not use `ShowDialog`**: modality disables the other windows on the same thread, so the buttons are "visible but unclickable". Use non-modal + a `DoEvents` message pump.
- **A full-screen mask must cut holes for the buttons**: otherwise the buttons are dimmed and the mask also eats the clicks; cut the holes to the buttons' rounded shape, or the four corners show white.
- **Overlay indicators must be excluded from capture**: the red dot and the border both need `SetWindowDisplayAffinity(hwnd, WDA_EXCLUDEFROMCAPTURE=0x11)`, or they get recorded.
- **Output naming rule**: `<prefix>_{date}_{time}_{scope}_{size}_{dur}.mkv`; append a `_recording` suffix while in progress, rename at the end to fill in the duration; on a name clash add `_2`, `_3`.
- **Hide the panel before executing**: hide the panel the moment it is triggered, then come back and bring it to the front when done; do not wait on a state poll.

## 5. Reference implementation (screen-recording tool)

`<TOOLS_DIR>\screen-recorder`: `agent.ps1` / `menu.ps1` / `common.ps1` / `toggle.ps1` / `copy.ps1` / `select-region.ps1` / `hotkeys.ps1` / `install.ps1` / `make-icon.ps1` / `assets\icon.ico` / `config.json` / `README.md`.
The data contract, naming tokens, hotkey lifecycle, region selection and panel design, and keeping the overlay out of frame are detailed in [references/architecture.md](references/architecture.md).

To swap in another capability: keep the agent / panel / command channel / indicator layer / verification skeleton, and replace the capability scripts and the output contract in section 5.

## 6. Reference files

- [references/architecture.md](references/architecture.md): process responsibilities, data contract, recording pipeline, region selection and panel design, out-of-frame techniques
- [references/pitfalls.md](references/pitfalls.md): symptom → cause → fix (16 pitfalls measured in practice)
- [references/verification.md](references/verification.md): copy-paste verification commands and pass thresholds
- [references/build-log.md](references/build-log.md): the requirement and decision timeline of the screen-recording tool from idea to finished product