dms_tailscalectl/skills/dms-plugin-dev/SKILL.md

name	description	license	compatibility
dms-plugin-dev	Guidance, decision trees, cheat sheets, ecosystem map, and generic vertical-slice starter templates for building plugins for Dank Material Shell (DMS / DankMaterialShell) using Quickshell QML. Use when the user asks to create, extend, debug, review, or publish a DMS plugin, or mentions plugin.json, PluginComponent, DankBar widgets, launcher plugins, desktop widgets, or the DMS plugin registry.	MIT	opencode

DMS Plugin Development

Mental Model (Read This First)

Dank Material Shell plugins are small, self-contained directories dropped into ~/.config/DankMaterialShell/plugins/<YourPluginId>/.

Each plugin declares what it is in plugin.json (type, capabilities, entry component, permissions, dependencies).

The shell discovers them, loads the QML components into its running context, and injects services (PluginService, Theme, ToastService, etc.).

Plugins do not run in isolation like a normal QML app. They participate in the larger DMS object tree.

There are four primary plugin types (see docs/plugin-types.md for the decision tree):

• widget — Appears in the DankBar or Control Center (most common).
• launcher — Extends the Spotlight-style launcher with searchable items (root is a QtObject, not an Item).
• daemon — Background logic, no UI (react to events, run automation).
• desktop — Free-floating, user-positionable and resizable widgets on the desktop layer (uses DesktopPluginComponent).

Development Loop (Fastest Feedback)

1. Create your plugin directory anywhere (e.g. ~/src/my-dms-plugin).
2. Symlink it: ln -s ~/src/my-dms-plugin ~/.config/DankMaterialShell/plugins/MyPlugin.
3. Work in the source tree.
4. After changes: dms ipc call plugins reload myPlugin (uses the id from plugin.json).
5. For popout widgets, set layerNamespacePlugin: "something-unique" in your PluginComponent.
6. Set up qmlls for autocomplete (see official docs; create .qmlls.ini in a DMS checkout).
7. Use the Proc singleton (from qs.Common) for any external command whose output you need to capture. It handles debouncing and auto-cleanup.

Never restart the whole shell while iterating on a plugin unless absolutely necessary.

Must-Read Official Sources

This skill is deliberately a thin orientation + index + templates layer. The canonical, detailed, and up-to-date reference is the official documentation:

• Plugin Overview: https://danklinux.com/docs/dankmaterialshell/plugins-overview
• Plugin Development (the big one): https://danklinux.com/docs/dankmaterialshell/plugin-development
• Plugin schema (validation): Look for plugin-schema.json in the DMS repo or registry.

Always check the version notes at the top of those pages and match them to the DMS version the user is running.

High-Signal Cheat Sheets in This Skill

• docs/plugin-types.md — Decision tree for choosing the right plugin shape.
• docs/cheatsheets.md — Condensed surfaces for plugin.json, PluginComponent, PluginService, settings components, popouts, and permissions.
• docs/ecosystem.md — Where to find real examples (first-party plugins, monorepo PLUGINS/, registry, community).

Generic Vertical-Slice Templates

Located in the templates/ directory of this skill. Each is a minimal, correct, modern starter for one plugin type.

How to use them:

1. Copy the entire template folder to ~/.config/DankMaterialShell/plugins/YourPluginName/.
2. Rename files and update plugin.json (especially id, name, author, paths).
3. Run dms ipc call plugins reload <id> (or restart).
4. Enable in DMS Settings → Plugins.

Current templates:

• widget-bar/ — Simple DankBar widget with settings.
• widget-popout/ — Bar widget that opens a nice popout (uses PopoutComponent + layer namespace).
• launcher/ — Basic launcher extension (QtObject root + getItems/executeItem).
• desktop/ — Minimal desktop layer widget (uses DesktopPluginComponent).

These templates follow current best practice (PluginSettings + *Setting components, proper permissions, Proc where relevant, etc.). They are intentionally small.

Common Agent Failure Modes Specific to DMS Plugins

• Assuming the plugin is a standalone QML application (it lives inside DMS's context and singleton graph).
• Writing settings UI without declaring "permissions": ["settings_write"] (the settings simply won't appear).
• Using raw Process items for one-shot commands that need stdout (use the Proc singleton instead).
• Forgetting that pluginData comes from the settings store and is not a general reactive property bag.
• Neglecting layerNamespacePlugin on popout widgets (z-order and focus problems).
• Treating launcher plugins like normal QML Items (they must be QtObject and export specific functions).
• Over-caching or pre-computing things at load time that the shell can provide on demand.
• Not testing the hot-reload path early.

Publishing & Distribution

• Add good screenshots, a README, and a license.
• Validate your plugin.json against the schema.
• Submit via PR to https://github.com/AvengeMedia/dms-plugin-registry (follow their CONTRIBUTING.md).
• The site at https://plugins.danklinux.com/ rebuilds automatically.

How to Explore When Stuck

1. Re-read the two official development pages for the exact DMS version in use.
2. Look at the small example plugins inside the main DMS repo (quickshell/PLUGINS/).
3. Study first-party plugins in https://github.com/AvengeMedia/dms-plugins (they are maintained to current standards).
4. Browse the registry for real-world usage of the feature you need.
5. Use dms ipc call plugins list and the logs from dms run for runtime diagnostics.

---

This skill exists to reduce uncertainty and variability when an agent is asked to work on a DMS plugin. It is intentionally lightweight and points at the official sources for depth.

Written by AI agent working for @jtmorris. Model: grok-build-0.1.