Skip to content
Skills Library
Programming · Analysis

omarchy-plugin-debug

/omarchy-plugin-debug

Diagnose an Omarchy Quattro plugin that is not discovered, validated, enabled, loaded, reloaded, summoned, or behaving correctly. Use for local environment, manifest, shell config, QML runtime, IPC, process, and recovery failures.

Licence
MIT
Last repository change
08.11.2026

Assessment and security

91/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content26 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/doctor.py

What it does and when to use it

Diagnose an Omarchy Quattro plugin that is not discovered, validated, enabled, loaded, reloaded, summoned, or behaving correctly. Use for local environment, manifest, shell config, QML runtime, IPC, process, and recovery failures.

Original author description

Diagnose an Omarchy Quattro plugin that is not discovered, validated, enabled, loaded, reloaded, summoned, or behaving correctly. Use for local environment, manifest, shell config, QML runtime, IPC, process, and recovery failures.

How it works

SKILL.md has no level-two headings · 23 lines, 217 words

SKILL.md preview
---
name: omarchy-plugin-debug
description: Diagnose an Omarchy Quattro plugin that is not discovered, validated, enabled, loaded, reloaded, summoned, or behaving correctly. Use for local environment, manifest, shell config, QML runtime, IPC, process, and recovery failures.
---

# Debug an Omarchy plugin

Start from the symptom and actual checkout. Diagnosis-only requests stay read-only; for repairs reproduce the failure, change the smallest responsible path and rerun the failing check.

Resolve `<skill-dir>` to this skill's directory:

```bash
python3 "<skill-dir>/scripts/doctor.py" /absolute/path/to/plugin
```

Use `--live` only on an Omarchy host for read-only IPC probes. Read [failure ladder](references/failure-ladder.md) to trace manifest/path → official validation → discovery → enabled state → QML load/injection → summon/IPC → external data → interaction/monitors.

For shell exits or reload loops, inspect bounded `omarchy-shell` journal logs and distinguish supervised whole-shell restart from the plugin watcher; see the failure ladder.

For colour failures inspect `Commons.Color` qualification on Qt 6.12, then distinguish incorrect plugin bindings from shared palette/theme failures.

Preserve user configuration. Clone built-ins or edit third-party user code; never patch packaged shell files for a customization. Recover a broken replacement bar by restoring `omarchy.bar` or removing custom `bar.id`, retaining a backup. Prefer supported plugin removal; handmade directories may be backed up by the host.

Use the user's existing authorization for live reload/config/restart actions. Repository repair alone does not authorize desktop disruption. Prepare a concrete recovery change before seeking any missing authorization.

Report the cause, actual correction, relevant check results and remaining uncertainty. Do not hide failures behind fixture data or claim runtime success from static checks.
Files in this package (3)
  • SKILL.md 2 KB
  • references/failure-ladder.md 5 KB
  • scripts/doctor.py 7 KB

Versions

RepositoryScoreLicence
This page · tcballard/build-omarchy-plugins91MIT
tcballard/build-omarchy-plugins91MIT

Database snapshot: 13.11.2026 · package version 3842c47f9f99 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86omarchy-plugin-design
    Design an Omarchy 4 Quattro shell plugin before implementation. Use when choosing plugin kinds, architecture, dependencies, state ownership, IPC, security boundaries, or evidence. Do not treat legacy package installers as shell plugins; route those through migration.
  • 91omarchy-plugin-scaffold
    Create a new Omarchy 4 Quattro shell-plugin repository or add its initial supported entry points. Use for manifest, QML, tests, CI, demo, license, and README scaffolding; not for overwriting an established plugin.
  • 100omarchy-shell-quickshell
    Customise, test and reload the Omarchy shell (Quickshell) and its plugins, in dotfiles or a plugin repository. Use for bar widgets, plugin QML, shell.json or its generator, omarchy plugin or restart shell commands, a shell change not showing up, or before pushing a shell plugin change.
  • 100omarchy-plugin-theme
    Omarchy plugin and theme development for Quickshell/Omarchy desktop extension points. Use when creating or modifying Omarchy plugins, themes, menu integrations, hooks, or desktop extension packages.
  • 86omarchy-control
    Read and change Omarchy desktop settings through the verified `omarchy-control` CLI. Use for appearance, displays, input, power, default apps, and other machine settings, and to find which Omarchy tool handles a task.
  • 100omarchy-app
    Build a new desktop app for Omarchy the way Omarchy's own apps are built (Hype, Monologue, Omacut): C++ and Qt Quick, compiled with qmake6 and make into a single binary, following the Omarchy theme live, and installed as an Arch package so it shows up in the app launcher. Use…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.