Omarchy Plugin Builder for OpenCode

An OpenCode skill for creating, auditing, repairing, extending, and preparing third-party Omarchy 4/Quattro shell plugins for publication.

The skill is intentionally conservative about API drift: it uses bundled references as a fallback, but instructs OpenCode to inspect the installed Omarchy source tree and a current first-party plugin of the same kind before generating QML.

What it covers

• All current Omarchy shell plugin kinds: bar-widget, bar, panel, overlay, menu, and service
• manifest.json generation and validation
• Multi-kind plugins
• Quickshell/QML structure and lifecycle
• Omarchy theme tokens and shared UI conventions
• shell.json settings and shell IPC
• Security review for unsandboxed plugin code
• GitHub-ready README and license generation
• Official omarchy plugin validate integration
• Existing-plugin audits and repairs

This skill targets the Quickshell-based Omarchy 4/Quattro plugin system. It is not a Waybar/v3 plugin generator.

Install

Global OpenCode skill

Clone the repository into the OpenCode global skill directory using the exact directory name omarchy-plugin-builder:

git clone https://github.com/tuxmontero/omarchy-plugin-builder.git \
  ~/.config/opencode/skills/omarchy-plugin-builder

Project-local skill

mkdir -p .opencode/skills
git clone https://github.com/tuxmontero/omarchy-plugin-builder.git \
  .opencode/skills/omarchy-plugin-builder

OpenCode discovers SKILL.md from these locations and loads the full instructions on demand.

Example prompts

Create an Omarchy 4 bar widget that shows my Tailscale exit-node state.

Build a multi-kind Omarchy plugin with a background service and a bar widget.

Audit this Omarchy plugin repository for manifest, QML, security, README, and licensing problems.

Add a summoned panel to this existing bar-widget plugin and keep its current configuration compatible.

Prepare this Omarchy plugin repository for publishing on GitHub.

Repository structure

omarchy-plugin-builder/
├── SKILL.md
├── README.md
├── LICENSE
├── scripts/
│   ├── inspect-omarchy.sh
│   └── validate-plugin.sh
├── references/
│   ├── source-of-truth.md
│   ├── plugin-contract.md
│   ├── official-patterns.md
│   ├── qml-ui.md
│   ├── security.md
│   └── readme-license-publishing.md
└── templates/
    ├── LICENSE.MIT
    ├── README.plugin.md
    ├── manifest-bar-widget.json
    ├── manifest-bar.json
    ├── manifest-menu.json
    ├── manifest-overlay.json
    ├── manifest-panel.json
    └── manifest-service.json

The skill intentionally does not bundle static QML entry-point templates. Quattro is still evolving, so OpenCode is instructed to inspect a current first-party implementation of the same plugin kind and generate against the local API rather than copying a stale QML skeleton.

Validation helper

The included helper performs a deterministic static preflight and then delegates to the official Omarchy validator when available:

./scripts/validate-plugin.sh /path/to/plugin

On an Omarchy system this ultimately runs:

omarchy plugin validate /path/to/plugin

The official validator remains the authority.

Design principles

1. Current local Omarchy wins. $OMARCHY_PATH documentation and runtime code take precedence over bundled notes.
2. Inspect official peers. Generate QML from current first-party patterns rather than memory.
3. Generate the minimum. Do not add empty directories, installers, or abstractions without a need.
4. Security is part of correctness. Plugins execute unsandboxed inside omarchy-shell.
5. Theme-aware by default. Prefer Omarchy Color, Style, Border, and shared UI components over hard-coded styling.
6. Official validation is mandatory when available. Never claim a plugin is ready after a failed omarchy plugin validate.
7. Publication is separate from preparation. The skill may prepare Git content, but it does not push or publish unless explicitly requested.

Upstream sources

The skill is based on the official OpenCode and Omarchy documentation/code:

• OpenCode Agent Skills: https://opencode.ai/docs/skills
• Omarchy shell/plugin contract: https://github.com/basecamp/omarchy/blob/quattro/docs/omarchy-shell.md
• Omarchy plugin registry: https://github.com/basecamp/omarchy/blob/quattro/shell/services/PluginRegistry.qml
• Omarchy first-party plugin catalogue: https://github.com/basecamp/omarchy/blob/quattro/shell/plugins/README.md
• Omarchy shell plugin manual: https://github.com/basecamp/omarchy/blob/quattro/manual/32-shell-plugins.md
• Omarchy repository conventions: https://github.com/basecamp/omarchy/blob/quattro/AGENTS.md

The bundled reference snapshot was prepared in August 2026. The skill is designed to detect and prefer newer local Omarchy behavior.

License

MIT. See LICENSE.