waku-shell — Claude Code skill: setup and installation
This Claude Code skill builds and edits waku shells for Windows. It handles screenshot-based recreations, Quickshell or Hyprland ports, and changes to an existing shell.
MIT ★ 115 updated 2026-11-16
/plugin marketplace add JanDeDobbeleer/waku
/plugin install waku-shell@wakuWhat waku-shell does
The skill creates QML shells for waku, ports Quickshell or Hyprland setups to Windows, and revises existing configurations. It checks each visible element for a working backend; unsupported features are left out. For screenshot recreations, it turns the visual reference into measured layout and style values, marking estimates separately.
Work and tests run from a throwaway config folder, not the user's live setup. The process includes an audit with scripts/audit.ps1, a candidate run, and checks of interactive elements; the scripts require pwsh. waku is under active development, so QML types and flags can change. The skill points to reference/engine-surface.md for the current engine surface.
What it helps with
- build a waku shell from a screenshot or description
- port a Quickshell or Hyprland shell to Windows
- revise an existing waku configuration
- remove interface elements with no working backend
Example prompts for the agent
- Build a waku shell from this screenshot.
- Port my Hyprland shell to Windows.
- Change the existing waku shell in this folder.
How to install waku-shell
1Plugin marketplace
/plugin marketplace add JanDeDobbeleer/waku/plugin install waku-shell@wakuThis installs the whole waku-shell plugin with all its skills
2Skills CLI (Vercel)
npx skills add JanDeDobbeleer/waku --skill waku-shell -a claude-code3Manually: put the files in place
~/.claude/skills/waku-shell/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/waku-shell/
1Skills CLI (Vercel)
npx skills add JanDeDobbeleer/waku --skill waku-shell -a codex2Manually: put the files in place
.agents/skills/waku-shell/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add JanDeDobbeleer/waku --skill waku-shell -a cursor2Manually: put the files in place
.cursor/skills/waku-shell/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install JanDeDobbeleer/waku skills/waku-shell2Manually: put the files in place
.github/skills/waku-shell/SKILL.md1Skills CLI (Vercel)
npx skills add JanDeDobbeleer/waku --skill waku-shell -a gemini-cli2Platform CLI
gemini skills install https://github.com/JanDeDobbeleer/waku --path skills/waku-shellManually: put the files in place
.devin/skills/waku-shell/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 waku-shell
How do I install waku-shell in Claude Code?
Add the marketplace with /plugin marketplace add JanDeDobbeleer/waku, then install the skill with /plugin install waku-shell@waku.
What does waku-shell do?
It helps create, port, and restyle waku shells in QML. It checks visible elements for working implementations and excludes those that lack support.
How does waku-shell verify a shell?
It checks whether the config loads, inspects a visible desktop run, then exercises interactive elements. Builds and tests use a throwaway config folder.
Source text
SKILL.md · MIT
--- name: waku-shell description: Create, port or restyle a waku shell (bar, dock, launcher, panels) so that every element works. Use when the user wants a waku config or shell, wants to recreate a look from a screenshot or from a Reddit post such as an r/unixporn URL, wants to port a Quickshell or Hyprland shell to Windows, or wants to change an existing waku shell. --- # waku shell authoring waku is a Qt Quick shell runtime for Windows, configured in QML, with Quickshell-compatible modules. waku is in active development: flags, QML types and formats can change without notice, so read `reference/engine-surface.md` for the current surface. A shell is a config home: a folder with `shell.qml` and its own QML. The engine holds only what QML cannot do. This skill gets a shell right the first time. ## Hard rules 1. **Everything works.** No element ships without a real backend. No mock data, no empty `onClicked`, no placeholder panel, no widget bound to an empty model, no hardcoded value that stands in for live data. If an element cannot work on Windows, drop it from the shell and tell the user. A visual match never outranks function. 2. **Say what you verified.** Use the three levels in `reference/verify.md`. Never claim a level you did not reach. You cannot press keys or answer UAC; mark those rows `needs the user`. 3. **Never touch the user's live setup.** Build and test in a throwaway config home with `--no-tray --no-app-bar --keep-taskbar --no-keys --no-tiling` (waku reserves screen space, hides the taskbar, starts the key daemon and tiles windows by default). Do not write to `%USERPROFILE%\.config\waku`. Start the live bar only when asked. 4. **Licences.** Copy no code from a shell under a licence that is not MIT into this repository. From a third-party config, take the look (colours, sizes, layout) and write the QML yourself. 5. **No shell-specific engine code.** A missing engine feature is reported as a generic gap. The element stays dropped until the engine has it. ## Workflow Do the steps in order. Do not start writing QML before step 3 is written down. ### 1. Intake - Identify the source: screenshot(s), a Reddit post URL, a path to an existing shell, or a description. See `reference/from-image.md` for screenshots and Reddit. - Confirm the target: which config home (a new folder unless the user names one), which monitor, its resolution and scale. Read the target folder first if it exists. Do not assume a shell name or path; check it exists. - Ask a question only when the source cannot answer it and a wrong guess costs a rebuild. ### 2. Spec the look Write measured values, not adjectives. "Flush", "tight" and "rounded" are not specs. Output: - Tokens: colours (hex with alpha), fonts and sizes, radii, bar thickness, gaps, padding, border widths, opacity, blur or not. - Layout: edges used, what sits in each region, order, spacing. - Mark each value `measured` or `guessed`. Tell the user which values are guessed. ### 3. Build the ledger One row per visible element (widget, button, indicator, panel, popup, menu entry, shortcut): | Element | Should do | Backend on waku | Status | |---|---|---|---| Status is one of: - `functional`: a built-in widget, a `waku.services` service or a Quickshell module does it. - `functional-with-difference`: works, behaves differently. Say how. - `not possible`: no backend. **Drop it.** Name the Windows reason and any real substitute. - `engine gap`: waku could do it, does not yet. Drop it. Describe the generic engine feature. Find backends in `reference/engine-surface.md`. Linux-only features and the replacements to use are in `reference/porting-checklist.md`. Rows with status `not possible` or `engine gap` do not enter the shell. Do not build a lookalike. ### 4. Build - Work in a new config home. Start from `examples/config` (a bar) or the closest example (`examples/sidebar`, `examples/launcher`, `examples/gallery`). Run `wakuc config init` for the built-in starter. - Prefer built-in widgets from `waku.widgets` and the theme (`theme.qml`, `ThemeSpec`). Copy a built-in into `widgets/` under a new name to change it. - Own types: one component per file in the config home. Do not name a file after a waku service (`Wallpapers.qml`, `Workspaces.qml`, `Bluetooth.qml`, `Media.qml`): `import Quickshell` shows Quickshell names only, so your file is your own type. - Read `reference/windows-gotchas.md` before writing layout, keys or launch code. - Services are `null` or unavailable until they report ready. Never gate a widget's `visible` on such an object. - Workspace ids are strings (`DISPLAY1:0`). Use `var`, not `int`. - Add what the shell needs to run beyond QML: a `keys.conf` beside `shell.qml` (waku starts `wakukeys.exe` with it) and, if the shell needs an environment, a `start.ps1`. Window gaps, layout and ratio come from `Tiling` (`gap`, `ratio`, `layout`), not from a separate tiler config. ### 5. Audit and verify - Run `scripts/audit.ps1 -ConfigHome <dir>`. It flags stubs, mock text and Linux-only calls. Fix every finding or drop the element. Exit code 0 is required. - Run `scripts/run-candidate.ps1 -ConfigHome <dir>` for level 1 (loads, `error=none`). - Run it on the desktop (`-Visible`) and capture with `scripts/capture.ps1` for level 2. Compare crops with the reference side by side. - Exercise each interactive row for level 3 (see `reference/verify.md`). ### 6. Deliver Report, in this order: 1. How to run it (exact command, throwaway first, then how to make it live and start at logon). 2. The ledger with final status per row and the verification level reached. 3. **Dropped elements**: what, why, and any real substitute. 4. Guessed values, `needs the user` checks, and engine gaps. Do not commit or publish unless asked. If the shell is meant for the waku-ports repository, say which licence applies. ## Reference - `reference/engine-surface.md`: modules, types, widgets, theme, CLI. - `reference/windows-gotchas.md`: lessons from past port work. - `reference/porting-checklist.md`: Hyprland, Wayland and Linux replacements. - `reference/verify.md`: the three levels, capture, and the report. - `reference/from-image.md`: screenshots and Reddit. - `scripts/`: `audit.ps1`, `run-candidate.ps1`, `capture.ps1`. Run them with `pwsh`.
© Jan De Dobbeleer · MIT · JanDeDobbeleer/waku