tcballard-omarchy
Twelve skills for building and publishing Omarchy shell plugins.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/tcballard--build-omarchy-plugins)HTML
<a href="/listings/tcballard--build-omarchy-plugins"><img src="/api/listings/tcballard--build-omarchy-plugins/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Clone a reviewed release, then install the skills into the shared interoperable location used by Codex, Cursor, Gemini CLI, and OpenCode:
These instructions target **v0.10.0**. Use its published tag and checksummed assets from [GitHub Releases](https://github.com/tcballard/build-omarchy-plugins/releases). A draft release or a newer `main` checkout is not a published release.
git clone --branch v0.10.0 --depth 1 https://github.com/tcballard/build-omarchy-plugins.git cd build-omarchy-plugins python3 scripts/install_agent_skills.py --target agents --scope user
Host-specific locations are also supported:
python3 scripts/install_agent_skills.py --target codex --scope user python3 scripts/install_agent_skills.py --target cursor --scope user python3 scripts/install_agent_skills.py --target gemini --scope user python3 scripts/install_agent_skills.py --target claude --scope user python3 scripts/install_agent_skills.py --target opencode --scope user
Use `--scope project` to install into the current repository, `--skill NAME` to install a subset, or `--target generic --destination PATH` for another Agent-Skills-compatible host. Existing differing skill directories are never overwritten unless `--force` is supplied explicitly.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 14 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "tcballard-omarchy",
- "owner": {
- "name": "Tom Ballard"
- },
- "plugins": [
- {
- "name": "build-omarchy-plugins",
- "source": "./",
- "description": "Design, scaffold, implement, test, debug, demo, release, migrate, and publish Omarchy 4 Quattro shell plugins."
- }
- ],
- "description": "Twelve skills for building and publishing Omarchy shell plugins."
- }
README.md · README · 296 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <h1 align="center">Build Omarchy Plugins</h1>
- <p align="center">
- <a href="https://github.com/tcballard/omarchy-badges"><img src="https://raw.githubusercontent.com/tcballard/omarchy-badges/75975e5b5bf75e7ede3764bcd2950046f7abfe2c/badges/v1/omarchy-plugin.svg" alt="Built for Omarchy: Plugin" height="24"></a>
- </p>
- <p align="center">
- <a href="https://buymeacoffee.com/tcballard"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?logo=buymeacoffee&logoColor=000" alt="Buy Me a Coffee" height="20"></a>
- </p>
- **Tell your agent what to build. Give it the Omarchy contract.**
- A set of twelve agent skills for building Omarchy 4 Quattro shell plugins. They
- help your agent choose the right shell surface, create a working starting point,
- write hosted QML, debug failures, test the result and prepare a release or
- marketplace submission.
- Use the full bundle or install only the skills your project needs.
- I built this because a plugin that loads inside Omarchy's long-running shell
- needs more care than a manifest and a few QML examples. The bundle includes
- generators and checks for that work; the plugin you make still needs testing on
- your target Omarchy desktop.
- **Start here:** [Install the v0.9.0 skills](#install-the-agent-skills), then
- [choose a workflow](docs/WORKFLOWS.md). [Release downloads and checksums](https://github.com/tcballard/build-omarchy-plugins/releases/tag/v0.9.0).
- ## Use with Omarchy's Agents panel
- On current Quattro development builds, the Agents panel's **Plugin** button launches your default coding agent with Omarchy's built-in plugin guide. This bundle adds focused engineering guidance; the button does not automatically load it.
- After installing the skills, tell your agent: “Use the installed Build Omarchy Plugins skills where useful, alongside Omarchy's built-in guide. Build the smallest working version, enable it locally and verify the interaction.” See [the host workflow](skills/omarchy-plugin-design/references/host-workflow.md) for personal tweaks and the exact entry point.
- The instructions can be read by any agent or harness with file access. No model API, proprietary tool names, planner, worker topology or companion service is required. Bundled helpers have their own explicit runtimes; provider-specific discovery and packaging remain optional adapters.
- ## Compatibility
- This toolkit targets **Omarchy 4.0.0 and later with Quattro shell-plugin support**.
- The supported range refers to the installed Omarchy version, reported by `omarchy-version`,
- not the ISO image version or the underlying Quickshell engine version.
- That is the scope of the maintained guidance and generators, not a claim that
- every current or future Omarchy release has been tested. The `4.0.0+` label
- has no upper major-version bound; compatibility changes will be documented here. Individual APIs and marketplace
- contracts are pinned in [the contract ledger](contracts/upstream-contracts.json).
- The CI workflow reports this repository's `main` checks. Portable tests
- validate tooling and generated output; they do not establish live desktop
- compatibility for every generated plugin. See [acceptance evidence](evals/ACCEPTANCE.md)
- for completed checks and outstanding behavioural or live-host testing.
- Projects built with the bundle must declare and test their own supported range.
- ## Why this exists
- Omarchy's desktop is one long-running Quickshell process. Third-party plugins
- run as unsandboxed user code inside that process, so a useful coding-agent
- toolkit needs more than a manifest example. It must understand lifecycle,
- multi-monitor state, theme tokens, process boundaries, recovery, reproducible
- evidence, and the community marketplace's exact submission contract.
- This project turns those requirements into focused Agent Skills and
- deterministic tools. The portable package uses the open Agent Plugins 1.0.0
- layout. An OpenAI plugin remains available as one distribution adapter.
- ## What "provider neutral" means
- The twelve skills do not call a model API, require a hosted service, or depend
- on provider-specific tools. The agent host chooses the model and supplies its
- normal file and shell capabilities. Provider-specific manifests and UI metadata
- live only in distribution adapters.
- The repository root is a portable Agent Plugin:
- ```text
- plugin.json
- skills/
- omarchy-plugin-design/
- ...
- ```
- See [PORTABILITY.md](PORTABILITY.md) for the tested host paths and exact
- compatibility boundary.
- For agent/harness-independent usage, see the
- [workflow guide](docs/WORKFLOWS.md) and
- [behavioral evaluation cases](evals/README.md). The skills keep model selection
- in the host and scale their workflow to the requested change.
- The next release, **v0.11.0**, is in preparation. Read the [candidate release notes](submission/release-notes.md); the installation commands below stay on published v0.9.0 until publication.
- ## Install the Agent Skills
- Clone a reviewed release, then install the skills into the shared interoperable
- location used by Codex, Cursor, Gemini CLI, and OpenCode:
- These instructions target **v0.9.0**. Use its published tag and checksummed
- assets from [GitHub Releases](https://github.com/tcballard/build-omarchy-plugins/releases).
- A draft release or a newer `main` checkout is not a published release.
- ```bash
- git clone --branch v0.9.0 --depth 1 https://github.com/tcballard/build-omarchy-plugins.git
- cd build-omarchy-plugins
- python3 scripts/install_agent_skills.py --target agents --scope user
- ```
- Host-specific locations are also supported:
- ```bash
- python3 scripts/install_agent_skills.py --target codex --scope user
- python3 scripts/install_agent_skills.py --target cursor --scope user
- python3 scripts/install_agent_skills.py --target gemini --scope user
- python3 scripts/install_agent_skills.py --target claude --scope user
- python3 scripts/install_agent_skills.py --target opencode --scope user
- ```
- Use `--scope project` to install into the current repository, `--skill NAME` to
- install a subset, or `--target generic --destination PATH` for another
- Agent-Skills-compatible host. Existing differing skill directories are never
- overwritten unless `--force` is supplied explicitly.
- ## Update, inspect, and remove
- The installer writes a receipt containing exact file hashes and modes. Preview
- every lifecycle change before applying it:
- ```bash
- git fetch --tags
- git checkout v0.9.0
- python3 scripts/install_agent_skills.py --target agents --scope user --update --diff
- python3 scripts/install_agent_skills.py --target agents --scope user --update
- ```
- If a managed file changed locally, update and removal stop. Inspect the diff;
- use `--force` only when replacing that named managed copy is intentional.
- Removal is equally explicit and leaves unrelated skills untouched:
- ```bash
- python3 scripts/install_agent_skills.py --target agents --scope user --uninstall --diff
- python3 scripts/install_agent_skills.py --target agents --scope user --uninstall
- ```
- Inspect discovery, duplicate names, hashes, and executable modes without
- starting the host:
- ```bash
- python3 scripts/doctor_agent_skills.py --host opencode --json
- ```
- The doctor reports filesystem evidence only; it cannot claim a model or host
- invocation succeeded. See [PORTABILITY.md](PORTABILITY.md) for the tested host
- matrix and OpenCode's optional deny-by-default live probe.
- ## Install the OpenAI plugin
- For ChatGPT and Codex plugin distribution:
- ```bash
- codex plugin marketplace add tcballard/build-omarchy-plugins
- codex plugin add build-omarchy-plugins@tcballard-omarchy
- ```
- In ChatGPT, refresh the Plugins Directory after adding the marketplace, then
- install **Build Omarchy Plugins** and start a new conversation.
- ## Start here
- Use the [workflow guide](docs/WORKFLOWS.md) to choose an entry point, follow a
- new build through the skills, or take the shorter path for a fix, demo or
- release. Each skill defines the inputs it uses and the evidence it hands on.
- ## Skills
- | Skill | Purpose |
- | --- | --- |
- | [omarchy-plugin-design](skills/omarchy-plugin-design/SKILL.md) | Choose kinds, boundaries, state, dependencies, IPC, and evidence before implementation. |
- | [omarchy-plugin-scaffold](skills/omarchy-plugin-scaffold/SKILL.md) | Generate a working Quattro plugin repository for any supported kind. |
- | [omarchy-qml-patterns](skills/omarchy-qml-patterns/SKILL.md) | Implement hosted QML with Omarchy theme, component, process, and state conventions. |
- | [omarchy-bar-widget](skills/omarchy-bar-widget/SKILL.md) | Build responsive bar widgets, settings, optional panels, and singleton services. |
- | [omarchy-panel-overlay](skills/omarchy-panel-overlay/SKILL.md) | Build panels, overlays, and menus with correct lifecycle, focus, and monitor behavior. |
- | [omarchy-service-ipc](skills/omarchy-service-ipc/SKILL.md) | Build process-wide services and stable IPC contracts without leaking credentials. |
- | [omarchy-plugin-debug](skills/omarchy-plugin-debug/SKILL.md) | Diagnose discovery, validation, load, reload, config, and runtime failures. |
- | [omarchy-plugin-test](skills/omarchy-plugin-test/SKILL.md) | Run manifest, static security, QML, fixture, and live-shell test layers. |
- | [omarchy-plugin-demo](skills/omarchy-plugin-demo/SKILL.md) | Create reversible demos and marketplace-ready screenshots using fictional data. |
- | [omarchy-plugin-release](skills/omarchy-plugin-release/SKILL.md) | Preflight a clean, documented, reproducible plugin release. |
- | [omarchy-plugin-publish](skills/omarchy-plugin-publish/SKILL.md) | Prepare and, after owner approval, submit the exact marketplace issue. |
- | [omarchy-plugin-migrate](skills/omarchy-plugin-migrate/SKILL.md) | Separate legacy machine integration from the Quattro shell surface and migrate safely. |
- ## Deterministic tools
- The scaffold skill now also includes the complete
- [plugin repository template](https://github.com/tcballard/omarchy-plugin-template)
- at a fixed commit. Ask for a new GitHub-ready bar-widget project, or follow the
- [offline starter instructions](skills/omarchy-plugin-scaffold/references/repository-template.md).
- Node.js 22+ generates the project without npm dependencies or network access;
- the existing six-kind generator remains available. The template travels with
- individual skill installs and every plugin/skills archive. The bundled starter is included from v0.8.0.
- The portable skills include reusable scripts that:
- - generate all six Quattro plugin kinds;
- - mirror Omarchy's manifest and path checks without requiring an Omarchy host;
- - report advisory marketplace security findings and review capabilities;
- - diagnose a local Omarchy installation without mutating it;
- - preflight releases and generate exact marketplace submission bodies;
- - install safely into supported agent-host skill locations; and
- - produce deterministic portable Agent Plugin and OpenAI submission archives.
- Run the repository verification suite with:
- ```bash
- ./scripts/test
- ```
- Package all distribution artifacts with:
- ```bash
- python3 scripts/package_submission.py --output-dir dist --require-clean --git-tree HEAD
- ```
- This produces the portable Agent Plugin, the OpenAI plugin, the OpenAI skills
- upload, reviewer materials, strict source/release manifests, an SPDX 2.3 SBOM,
- and one checksum manifest. Artifacts are built from the exact committed Git
- tree rather than ambient working files.
- ## Recommended companion: Omakit
- We recommend [Omakit](https://github.com/mtolhuys/omakit) alongside this bundle
- for reusable Run/Store plumbing and local marketplace preflight. Its `inspect`
- command highlights code worth reviewing, `verify` runs the pinned marketplace
- security baseline, and `submit` prepares submission checks and an issue draft
- without posting it. Omakit requires Node 22+ and Git; follow its
- [installation guide](https://github.com/mtolhuys/omakit/blob/main/docs/INSTALL.md).
- Use it against the intended committed candidate and record both that SHA and
- the marketplace baseline revision. Passing checks does not establish desktop
- behavior, security certification or marketplace approval. Omakit is an optional
- companion; this bundle's portable validators remain available without it.
- For deeper review, the optional
- [community security skill](https://github.com/wbso-ai/omarchy-plugin-security-skill)
- collects historical reviewer findings. For clean-desktop GUI testing,
- [OmaVM](https://github.com/mlclifton/omavm) provides QEMU/KVM guest workflows.
- Consult their current prerequisites and scope; neither establishes marketplace
- approval. The testing skill explains how to record their evidence and limits.
- ## Scope
- The default target is an Omarchy 4 Quattro shell plugin: a public Git repository
- with `manifest.json` and QML at its root. Older Omarchy integrations that install
- packages, systemd units, or privileged helpers are treated as a separate machine
- integration layer. The migration skill preserves that layer when it is genuinely
- required instead of pretending Quattro's no-install-hook model can replace it.
- ## Safety boundary
- Generated and reviewed Omarchy plugins are still unsandboxed third-party code.
- The static checks in this project are advisory and cannot prove that a plugin is
- safe. Review source and dependencies before enabling any plugin.
- ## Support and policies
- - [Support](SUPPORT.md)
- - [Security](SECURITY.md)
- - [Privacy](PRIVACY.md)
- - [Terms](TERMS.md)
- - [Contributing](CONTRIBUTING.md)
- ## License
- MIT
- ## Claude Code plugin (v0.9.0)
- Native Claude Code packaging was introduced in v0.3.1. From a reviewed v0.9.0 checkout,
- validate and try the plugin locally:
- ```bash
- claude plugin validate .
- claude --plugin-dir .
- ```
- The repository marketplace tracks the default branch. To install it in Claude
- Code:
- ```text
- /plugin marketplace add tcballard/build-omarchy-plugins
- /plugin install build-omarchy-plugins@tcballard-omarchy
- ```
- Use either this plugin or the existing `--target claude` skills installer to
- avoid loading duplicate skills. The v0.9.0 release build includes a separate
- `build-omarchy-plugins-claude-plugin-0.9.0.zip`, with the same twelve canonical
- skills and their helpers. This is a community marketplace, not an official
- Anthropic listing. OpenAI and Anthropic marketplace submissions remain on hold
- while stewardship is discussed.
- See [maintenance and adoption](docs/MAINTENANCE.md) for ownership decisions and
- [acceptance evidence](evals/ACCEPTANCE.md) for what has actually been exercised.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.