quickshell

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

Updated Mar 31, 2026
One-click install
npx skills add https://github.com/dotBeeps/pantry --skill quickshell
Or copy as Structured Prompt for Agent
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.