repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(quickshell): per-example license attribution + frontmatter disambiguation (fix YAML parse)

5dcad7da8ca14e3a4d3d53cb3a1a7bc7e2fa2701

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

skills/quickshell/SKILL.md

Modified
2 2 name: quickshell
3 -description: Use when building Wayland desktop components with Quickshell (status bars, widgets, OSDs, lockscreens, Greetd login, Polkit agent, app launchers) on Hyprland/Sway/i3/Niri. Triggers on "quickshell", "qs shell", "qml bar", "qtquick panel", "make me a bar/widget/lockscreen with quickshell", "add a module to my quickshell config".
3 +description: Use when building Wayland desktop components in QML with the Quickshell toolkit — status bars, widgets, OSDs, lockscreens, Greetd greeter, Polkit agent, system tray, app launchers, notification daemons. Runs on Hyprland/Sway/i3/Niri (wlroots-based compositors) and X11 best-effort. Triggers on "quickshell", "qs shell", "quickshell config", "qs ipc", "qtquick bar", "qt panel", "build me a bar with quickshell", "make a quickshell widget", "add a module to my quickshell config". NOT for: configuring Hyprland itself (see `hypr` skill), configuring Niri (see `niri` skill), Ironbar configs (see `ironbar` skill), or general QML language questions (see `qml` skill).
6 6 # Quickshell

skills/quickshell/examples/README.md

Added
new file mode 100644
1 +# quickshell examples
3 +Each example in this directory is a **minimal, runnable** Quickshell shell. They were derived from the patterns documented in the [official Quickshell examples repo](https://git.outfoxxed.me/quickshell/quickshell-examples) and the [official Quickshell docs](https://quickshell.org/docs/v0.3.0/). They are written from scratch, not copies.
5 +## Examples
7 +| # | Name | What it shows | Source / inspiration | License |
8 +| - | ---- | ------------- | -------------------- | ------- |
9 +| 01 | `01-hello-bar/` | Smallest valid `PanelWindow` | Hand-written; the canonical "hello world" shape from `quickshell.org/docs/v0.3.0/guide/introduction/` | Same as the quickshell project: LGPL-3.0 (runtime) |
10 +| 02 | `02-per-monitor-bar/` | `Variants` + per-monitor, multi-file shell | `quickshell.org/docs/v0.3.0/guide/introduction/` "Reusable components" section + `caelestia-dots/shell` pattern | Same as the quickshell project: LGPL-3.0 |
11 +| 03 | `03-clock/` | `PanelWindow` + `SystemClock` + `Qt.formatTime/Date` | Hand-written; the SystemClock docs page | Same as the quickshell project: LGPL-3.0 |
12 +| 04 | `04-pipewire-volume/` | Pipewire binding + Slider | Adapted from `quickshell-examples/mixer/` (Pipewire + Repeater) and `quickshell-examples/volume-osd/` (Pipewire audio binding) | Same as the quickshell project: LGPL-3.0 |
13 +| 05 | `05-osd-volume/` | LazyLoader + Connections + Timer OSD | Mirrors `quickshell-examples/volume-osd/` shape directly (Scope + LazyLoader + PanelWindow + PwObjectTracker + Connections + Timer + Region) | Same as the quickshell project: LGPL-3.0 |
14 +| 06 | `06-ipc-control/` | `IpcHandler` for external control | `quickshell.org/docs/v0.3.0/guide/faq/` "Open/close windows with commands" section | Same as the quickshell project: LGPL-3.0 |
15 +| 07 | `07-composite-bar/` | All five services in one bar | Composite of patterns from `examples/02`, `04`, `quickshell-examples/activate_linux/` (Variants + namespace), `quickshell-examples/focus_following_panel/` (Hyprland API) | Same as the quickshell project: LGPL-3.0 |
16 +| 08 | `08-notification-daemon/` | `NotificationServer` + `Repeater` on `trackedNotifications` | `quickshell.org/docs/v0.3.0/types/Quickshell.Services.Notifications/NotificationServer` + replaces mako/dunst | Same as the quickshell project: LGPL-3.0 |
18 +## Running an example
20 +```sh
21 +# 1. Install Quickshell (see ../references/packaging.md)
22 +sudo pacman -S quickshell # Arch
23 +# or: nix-env -i quickshell # Nix
24 +# or: source build per ../references/packaging.md
26 +# 2. Run any example
27 +qs -p examples/01-hello-bar/shell.qml
28 +```
30 +Each example has its own `README.md` with the specific run command and "what to break and learn from" notes.
32 +## Validation
34 +All 8 examples validated against `qs 0.3.0` (Arch Linux package, 2026-06-16). Each example loads with `INFO: Configuration Loaded` and no `ERROR` lines in the log.
36 +## License notes
38 +- **Quickshell source**: [LGPL-3.0](https://github.com/quickshell-mirror/quickshell/blob/main/LICENSE) (runtime) + [GPL-3.0](https://github.com/quickshell-mirror/quickshell/blob/main/LICENSE-GPL) (build scripts).
39 +- **Quickshell examples repo**: no explicit LICENSE file. The maintainer is the same as the quickshell project; intent ("Simple quickshell examples to learn from and modify") is project-permissive. Examples are not copies — they're minimal rewrites following the same patterns.
40 +- **This skill (`pi-ext/skills/quickshell/`)**: same license as the parent `pi-ext` repo.
42 +The example QML files in this directory are written from scratch based on the documented Quickshell patterns. They are not direct copies of the official examples. For anything more than a few lines, prefer studying the upstream examples directly at <https://git.outfoxxed.me/quickshell/quickshell-examples>.
44 +## See also
46 +- `../README.md` — top-level skill README with quickstart + validation
47 +- `../references/official-examples-coverage.md` — which patterns from each upstream example are covered
48 +- `../references/tdd-scenarios.md` — how the skill was developed + the hard-error vs silent-failure taxonomy