quickshell

Standardize QML-based Wayland desktop shell development with file structure and singleton conventions.

Updated Mar 31, 2026

Search Tags:#wayland #singleton #qml #quickshell #design-conventions #desktop-shell

Ready to run

npx skills add https://github.com/dotBeeps/pantry --skill quickshell

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: quickshell
Source: https://github.com/dotBeeps/pantry/tree/main/morsels/skills/quickshell
Command: npx skills add https://github.com/dotBeeps/pantry --skill quickshell

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

QuickShell conventions standardize QML-based desktop shell development on Wayland, reducing setup friction and inconsistencies across projects.

Core Features & Use Cases

Entry point is shell.qml with ShellRoot as the root object
One QML type per file — filename matches the type name (PascalCase)
Use pragma Singleton + Singleton {} root for shared state (clocks, services, settings)
Use Scope {} to group shared resources outside Variants — avoids duplicating processes/timers per screen
Use Variants with model: Quickshell.screens + delegate: Component {} for multi-monitor support
Consistent naming and inline component patterns to improve readability and maintainability

Quick Start

Create a new QuickShell project by starting with shell.qml and defining ShellRoot as the root object

Frequently Asked Questions about quickshell

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I structure a QML desktop shell for multi-monitor Wayland support?▼

Structure a QML desktop shell on Wayland by using Variants with model: Quickshell.screens and delegate: Component {} to handle multi-monitor support. Group shared resources outside Variants using Scope {} to avoid duplicating processes or timers per screen.

What is the best way to manage shared state in a Wayland shell using QML?▼

Manage shared state in a Wayland QML shell by using pragma Singleton and defining a Singleton {} root object. This approach standardizes the organization of clocks, services, and settings across the project.

How do I set up the entry point for a QuickShell project on Wayland?▼

Set up the QuickShell entry point by creating a shell.qml file and defining ShellRoot as the root object. This standardizes the initialization process and reduces setup friction for Wayland desktop shells.

Do I need to follow specific naming conventions for QML files in a Wayland shell?▼

Follow the convention of one QML type per file, ensuring the filename matches the type name in PascalCase. This consistent naming pattern improves readability and maintainability across Wayland shell projects.

Why should I group shared resources outside Variants in a multi-monitor Wayland shell?▼

Group shared resources outside Variants using Scope {} to prevent duplicating processes and timers for each screen. This optimization is essential for maintaining efficient multi-monitor Wayland desktop shells.

Can small teams use these QML conventions to reduce setup friction for new Wayland shells?▼

Small teams and new Wayland shell projects can use these QML conventions to reduce setup friction and inconsistencies. The standards guide file structure, singleton usage, and resource organization for streamlined development.