quickshell/
├── SKILL.md
├── references/
├── examples/
├── bin/
└── package.json

# quickshell skill

Guidance and small examples for building Linux desktop components with Quickshell.
Read [`SKILL.md`](SKILL.md) first.

## Contents

```text
quickshell/
├── SKILL.md
├── references/
├── examples/
├── bin/
└── package.json
```

The references intentionally avoid broad service API summaries.
Resolve the installed `qs` version and consult its official type pages before writing service, IPC, windowing, or authentication code.

## Examples

The examples cover:

1. a single panel
2. one panel per screen
3. a clock panel
4. PipeWire volume display and control
5. a volume OSD
6. typed IPC functions
7. a composite bar
8. a minimal notification daemon

Examples are teaching inputs, not proof of target-desktop behavior.
Do not launch them on the user's real desktop as routine validation.
Notification and authentication components can claim session-global protocols or services.

## Validation levels

- `npm test` checks the Node helper tools.
- `qmllint` checks supported QML structure and installed imports without launching the shell.
- An offscreen load check establishes load behavior only.
- Interaction acceptance requires exercising input, IPC, timers, hotplug, and service events.
- Visual acceptance requires observing mapped surfaces on the target display setup.

Runtime checks belong in a nested compositor with isolated runtime and session services.
A nested compositor without an isolated D-Bus and service environment is insufficient for notification, tray, Polkit, greetd, or similar checks.
Never claim interaction or visual validation from static or offscreen checks.

### Upstream tooling boundary

[Quickshell recommends `qmlls` with generated `.qmlls.ini`](https://quickshell.org/docs/v0.3.1/guide/install-setup/#language-server) and explicitly documents unresolved `PanelWindow` types.
Its runtime backend registration is not fully described by static `.qmltypes`; [issue #543](https://github.com/quickshell-mirror/quickshell/issues/543) tracks related false positives.
Use Qt6 tooling, not an unverified executable named `qmllint` that may belong to Qt5.
The earlier claim that typed `IpcHandler` functions cause an independent linter defect was incorrect: minimal typed IPC passes with Qt6 and the existing project lint policy.
Keep that policy unchanged; do not add warning suppressions or fabricated metadata.
The offscreen Qt platform has no Quickshell `PanelWindow` backend.
Mapped surfaces, services, and interaction require an isolated nested compositor rather than more offscreen retries.

## Helpers

See [`bin/README.md`](bin/README.md).
The helpers use Node built-ins and have no package dependencies.