skillshare-windows-utm — Claude Code skill: install and usage
skillshare-windows-utm is a Claude Code skill that tests skillshare in a local UTM Windows guest, building pinned commits in a devcontainer and checking symlinks, junctions, and copy fallbacks.
MIT ★ 3,269 updated 2026-10-29
npx skills add runkids/skillshare --skill skillshare-windows-utm -a claude-codeWhat skillshare-windows-utm does
Linux test suites do not show genuine Windows link mechanics. This skill automates a Windows virtual machine in UTM using scripts/windows/utm.sh. It builds ss.exe and UI packages inside a devcontainer from a specific git commit, then pushes artifacts to the guest.
Running commands via utmctl exec executes under the SYSTEM account, which always permits symlinks. To test standard desktop behavior and copy fallback mechanisms, the skill launches interactive tasks through utm.sh task with both full and basic tokens (--basic). Automated runs stay contained inside C:\Users\Public\sstest\.
Interactive scheduled tasks fail immediately if no user is actively logged into the UTM guest interface.
What it helps with
- verify Windows file symlinks and directory junctions in UTM
- test copy fallback mechanics without symlink privileges
- build guest-targeted binaries from pinned commits in a devcontainer
- deploy an isolated manual verification environment on Windows
Example prompts for the agent
- Run automated Windows UTM verification for commit HEAD
- Prepare a manual test environment in UTM for git ref main
- Probe the UTM Windows guest and test basic token permissions
How to install skillshare-windows-utm
1Skills CLI (Vercel)
npx skills add runkids/skillshare --skill skillshare-windows-utm -a claude-code2Manually: put the files in place
~/.claude/skills/skillshare-windows-utm/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/skillshare-windows-utm/
1Skills CLI (Vercel)
npx skills add runkids/skillshare --skill skillshare-windows-utm -a codex2Manually: put the files in place
.agents/skills/skillshare-windows-utm/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add runkids/skillshare --skill skillshare-windows-utm -a cursor2Manually: put the files in place
.cursor/skills/skillshare-windows-utm/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install runkids/skillshare .skillshare/skills/skillshare-windows-utm2Manually: put the files in place
.github/skills/skillshare-windows-utm/SKILL.md1Skills CLI (Vercel)
npx skills add runkids/skillshare --skill skillshare-windows-utm -a gemini-cli2Platform CLI
gemini skills install https://github.com/runkids/skillshare --path .skillshare/skills/skillshare-windows-utmManually: put the files in place
.devin/skills/skillshare-windows-utm/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about skillshare-windows-utm
How do I install skillshare-windows-utm in Claude Code?
Run npx skills add runkids/skillshare --skill skillshare-windows-utm -a claude-code.
What does skillshare-windows-utm do?
It coordinates local UTM virtual machine testing for skillshare, validating symlink behavior, junctions, and path handling under real Windows permission models.
Why does it avoid using utmctl exec directly for tests?
Direct utmctl exec calls run as SYSTEM, which retains permission to make symlinks regardless of policy. Testing normal accounts and copy fallbacks requires interactive tasks via utm.sh task --basic.
Source text
SKILL.md · MIT
---
name: skillshare-windows-utm
description: >-
Verify skillshare on a real Windows guest running in local UTM: build a pinned
commit in the devcontainer, push it into the VM, and either run the Windows E2E
runbook with full and basic-user tokens or hand the maintainer a one-line
hands-on setup. Use this whenever a change touches Windows links, junctions,
file symlinks, Developer Mode, copy fallback, Windows paths, or the dashboard on
Windows, or when the user asks to test or accept something on Windows / UTM.
argument-hint: "[auto | manual] [git-ref]"
metadata:
targets: [claude, universal]
---
Linux tests cannot show Windows link behavior. This skill drives the local UTM guest with
`scripts/windows/utm.sh`. Before acting, run `python3 scripts/ai-context.py testing` and follow its
"Windows Verification" section; it is the source of truth for the rules below.
## Rules
- Build in the devcontainer from a **pinned commit** (`utm.sh build <ref>`), never from the working
tree: other work may be editing it. Report the commit hash with every result.
- The host only drives the VM (`utmctl`). Never run `ss`, `go` or `pnpm` on the host.
- `utmctl exec` runs as SYSTEM, which can always create symlinks. Product behavior must run as the
desktop user through `utm.sh task` (Interactive scheduled task). Use `--basic` for the basic-user
token (`runas /trustlevel:0x20000`), which has no symlink right. Never switch to S4U: its token
differs from a real user's.
- Isolate automated runs under `C:\Users\Public\sstest\`. Clean up with `utm.sh clean`, which uses
`rmdir` (it does not follow junctions).
- Report which token (full or basic) and architecture each result came from.
## 1. Preflight
```sh
scripts/windows/utm.sh probe
```
| Output | Meaning and action |
|---|---|
| `stopped` | `utmctl start Windows`, then probe again after boot. |
| `OSStatus -1712` | macOS Automation permission for the terminal app is missing; ask the user to allow it. |
| `OSStatus -2700` / guest agent error | Guest still booting or agent not up. Wait, then retry. |
| `desktopUser=` empty | Nobody is logged in; Interactive tasks will not start. **Ask the user to log in** in the UTM window. Restarting the VM logs the user out. |
| `arch=ARM64` / `AMD64` | Use it as the build arch (`arm64` / `amd64`). |
| `devMode=1` | Developer Mode is on; the basic token may still create symlinks. Say so in the report. |
## 2. Build and push
```sh
scripts/windows/utm.sh build <ref> <arm64|amd64> # ss.exe, ss-ui-dist.zip, ss-version.txt in $OUT
```
The UI zip is unpacked into `%APPDATA%\skillshare\ui\<version>` so `ss ui` never downloads it.
`utmctl file push` needs an existing guest folder; create one with `utm.sh ps` first, or push to
`C:\Users\Public\`.
## 3a. Automated acceptance (`auto`)
1. Create `C:\Users\Public\sstest\` (via `utm.sh ps`), push `ss.exe` and
`scripts/windows/e2e-file-links.ps1` into it.
2. Run the runbook script once per token:
```sh
scripts/windows/utm.sh task sstest-full 'C:\Users\Public\sstest\e2e-file-links.ps1' -- \
-Exe C:\Users\Public\sstest\ss.exe -Root C:\Users\Public\sstest\run-full -Out C:\Users\Public\sstest\out-full.txt -Extended
scripts/windows/utm.sh task sstest-basic 'C:\Users\Public\sstest\e2e-file-links.ps1' --basic -- \
-Exe C:\Users\Public\sstest\ss.exe -Root C:\Users\Public\sstest\run-basic -Out C:\Users\Public\sstest\out-basic.txt -Extended
```
3. Poll `utm.sh pull 'C:\Users\Public\sstest\out-full.txt'` until the last line is `DONE`
(`pull` exits 0 even when the file is missing).
4. For scenarios the script does not cover, write a small `.ps1`, push it, and run it with
`utm.sh task`. Check reparse tags with `fsutil reparsepoint query` (`0xa0000003` junction,
`0xa000000c` symlink) and read the file back.
5. `utm.sh clean`, then report per token: pass/fail, commit, arch, exact failing output.
## 3b. Hands-on test for the maintainer (`manual`)
```sh
scripts/windows/utm.sh push-manual
```
Give the user exactly one line to run in a **normal (non-admin) PowerShell** on the guest. A normal
shell tests the copy fallback that users without Developer Mode get; an admin shell can create
symlinks:
```powershell
powershell -ExecutionPolicy Bypass -File C:\Users\Public\ss-setup.ps1
```
It works in an isolated home, `C:\Users\Public\sstest\manual` (it overrides `USERPROFILE`, `HOME`,
`APPDATA`, `LOCALAPPDATA`), so the real profile is never touched. It installs `ss.exe` and the UI,
creates sample `.claude\CLAUDE.md` and `.codex\AGENTS.md` there, runs `init`, and opens the
dashboard. Tell the user which files to inspect under that folder, then list 4–6 things to try for
the change under test, each with what they should see. Cleanup removes only that folder:
```powershell
powershell -ExecutionPolicy Bypass -File C:\Users\Public\ss-setup.ps1 -Clean
```
Keep the instructions short. Do not paste multi-line setup blocks for the user to type.
## On a Windows host (no UTM)
The same scripts run natively; only the transport changes.
1. Build with the devcontainer (Docker Desktop) as in step 2, or run the `docker exec` part of
`utm.sh build` directly, then copy `ss.exe`, `ss-ui-dist.zip` and `ss-version.txt` into one folder.
2. Hands-on: `powershell -ExecutionPolicy Bypass -File scripts\windows\manual-setup.ps1 -Dir <that folder>`.
It stays isolated under `-Root`, so it is safe on a real profile.
3. Automated: run `scripts\windows\e2e-file-links.ps1` directly (it isolates under `-Root` too). For the
basic-user token, launch it through `runas /trustlevel:0x20000 "powershell ..."` from a normal shell.
4. A developer machine often has Developer Mode on, which lets even the basic token create
symlinks. Check `whoami /priv` and state it in the report; the no-symlink fallback needs it off.
## Gotchas
- Call `~/Applications/UTM.app/Contents/MacOS/utmctl` directly; the Homebrew symlink reports
"Application not found". `utm.sh` does this.
- zsh `echo` eats backslashes in Windows paths; write guest scripts with a quoted heredoc.
- Under x64 emulation on ARM64, `$env:PROCESSOR_ARCHITECTURE` and .NET both say x64. `probe`
reads the native value from the registry.
- A PowerShell 5 script without a BOM is read as the system code page; keep `.ps1` files ASCII.
© runkids · MIT · runkids/skillshare