Skip to content
Back to search

tcballard-omarchy

MarketplaceWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tcballard--build-omarchy-plugins/badge.svg)](/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.

  1. {
  2. "name": "tcballard-omarchy",
  3. "owner": {
  4. "name": "Tom Ballard"
  5. },
  6. "plugins": [
  7. {
  8. "name": "build-omarchy-plugins",
  9. "source": "./",
  10. "description": "Design, scaffold, implement, test, debug, demo, release, migrate, and publish Omarchy 4 Quattro shell plugins."
  11. }
  12. ],
  13. "description": "Twelve skills for building and publishing Omarchy shell plugins."
  14. }
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.

  1. <h1 align="center">Build Omarchy Plugins</h1>
  2. <p align="center">
  3. <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>
  4. </p>
  5. <p align="center">
  6. <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>
  7. </p>
  8. **Tell your agent what to build. Give it the Omarchy contract.**
  9. A set of twelve agent skills for building Omarchy 4 Quattro shell plugins. They
  10. help your agent choose the right shell surface, create a working starting point,
  11. write hosted QML, debug failures, test the result and prepare a release or
  12. marketplace submission.
  13. Use the full bundle or install only the skills your project needs.
  14. I built this because a plugin that loads inside Omarchy's long-running shell
  15. needs more care than a manifest and a few QML examples. The bundle includes
  16. generators and checks for that work; the plugin you make still needs testing on
  17. your target Omarchy desktop.
  18. **Start here:** [Install the v0.9.0 skills](#install-the-agent-skills), then
  19. [choose a workflow](docs/WORKFLOWS.md). [Release downloads and checksums](https://github.com/tcballard/build-omarchy-plugins/releases/tag/v0.9.0).
  20. ## Use with Omarchy's Agents panel
  21. 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.
  22. 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.
  23. 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.
  24. ## Compatibility
  25. This toolkit targets **Omarchy 4.0.0 and later with Quattro shell-plugin support**.
  26. The supported range refers to the installed Omarchy version, reported by `omarchy-version`,
  27. not the ISO image version or the underlying Quickshell engine version.
  28. That is the scope of the maintained guidance and generators, not a claim that
  29. every current or future Omarchy release has been tested. The `4.0.0+` label
  30. has no upper major-version bound; compatibility changes will be documented here. Individual APIs and marketplace
  31. contracts are pinned in [the contract ledger](contracts/upstream-contracts.json).
  32. The CI workflow reports this repository's `main` checks. Portable tests
  33. validate tooling and generated output; they do not establish live desktop
  34. compatibility for every generated plugin. See [acceptance evidence](evals/ACCEPTANCE.md)
  35. for completed checks and outstanding behavioural or live-host testing.
  36. Projects built with the bundle must declare and test their own supported range.
  37. ## Why this exists
  38. Omarchy's desktop is one long-running Quickshell process. Third-party plugins
  39. run as unsandboxed user code inside that process, so a useful coding-agent
  40. toolkit needs more than a manifest example. It must understand lifecycle,
  41. multi-monitor state, theme tokens, process boundaries, recovery, reproducible
  42. evidence, and the community marketplace's exact submission contract.
  43. This project turns those requirements into focused Agent Skills and
  44. deterministic tools. The portable package uses the open Agent Plugins 1.0.0
  45. layout. An OpenAI plugin remains available as one distribution adapter.
  46. ## What "provider neutral" means
  47. The twelve skills do not call a model API, require a hosted service, or depend
  48. on provider-specific tools. The agent host chooses the model and supplies its
  49. normal file and shell capabilities. Provider-specific manifests and UI metadata
  50. live only in distribution adapters.
  51. The repository root is a portable Agent Plugin:
  52. ```text
  53. plugin.json
  54. skills/
  55. omarchy-plugin-design/
  56. ...
  57. ```
  58. See [PORTABILITY.md](PORTABILITY.md) for the tested host paths and exact
  59. compatibility boundary.
  60. For agent/harness-independent usage, see the
  61. [workflow guide](docs/WORKFLOWS.md) and
  62. [behavioral evaluation cases](evals/README.md). The skills keep model selection
  63. in the host and scale their workflow to the requested change.
  64. 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.
  65. ## Install the Agent Skills
  66. Clone a reviewed release, then install the skills into the shared interoperable
  67. location used by Codex, Cursor, Gemini CLI, and OpenCode:
  68. These instructions target **v0.9.0**. Use its published tag and checksummed
  69. assets from [GitHub Releases](https://github.com/tcballard/build-omarchy-plugins/releases).
  70. A draft release or a newer `main` checkout is not a published release.
  71. ```bash
  72. git clone --branch v0.9.0 --depth 1 https://github.com/tcballard/build-omarchy-plugins.git
  73. cd build-omarchy-plugins
  74. python3 scripts/install_agent_skills.py --target agents --scope user
  75. ```
  76. Host-specific locations are also supported:
  77. ```bash
  78. python3 scripts/install_agent_skills.py --target codex --scope user
  79. python3 scripts/install_agent_skills.py --target cursor --scope user
  80. python3 scripts/install_agent_skills.py --target gemini --scope user
  81. python3 scripts/install_agent_skills.py --target claude --scope user
  82. python3 scripts/install_agent_skills.py --target opencode --scope user
  83. ```
  84. Use `--scope project` to install into the current repository, `--skill NAME` to
  85. install a subset, or `--target generic --destination PATH` for another
  86. Agent-Skills-compatible host. Existing differing skill directories are never
  87. overwritten unless `--force` is supplied explicitly.
  88. ## Update, inspect, and remove
  89. The installer writes a receipt containing exact file hashes and modes. Preview
  90. every lifecycle change before applying it:
  91. ```bash
  92. git fetch --tags
  93. git checkout v0.9.0
  94. python3 scripts/install_agent_skills.py --target agents --scope user --update --diff
  95. python3 scripts/install_agent_skills.py --target agents --scope user --update
  96. ```
  97. If a managed file changed locally, update and removal stop. Inspect the diff;
  98. use `--force` only when replacing that named managed copy is intentional.
  99. Removal is equally explicit and leaves unrelated skills untouched:
  100. ```bash
  101. python3 scripts/install_agent_skills.py --target agents --scope user --uninstall --diff
  102. python3 scripts/install_agent_skills.py --target agents --scope user --uninstall
  103. ```
  104. Inspect discovery, duplicate names, hashes, and executable modes without
  105. starting the host:
  106. ```bash
  107. python3 scripts/doctor_agent_skills.py --host opencode --json
  108. ```
  109. The doctor reports filesystem evidence only; it cannot claim a model or host
  110. invocation succeeded. See [PORTABILITY.md](PORTABILITY.md) for the tested host
  111. matrix and OpenCode's optional deny-by-default live probe.
  112. ## Install the OpenAI plugin
  113. For ChatGPT and Codex plugin distribution:
  114. ```bash
  115. codex plugin marketplace add tcballard/build-omarchy-plugins
  116. codex plugin add build-omarchy-plugins@tcballard-omarchy
  117. ```
  118. In ChatGPT, refresh the Plugins Directory after adding the marketplace, then
  119. install **Build Omarchy Plugins** and start a new conversation.
  120. ## Start here
  121. Use the [workflow guide](docs/WORKFLOWS.md) to choose an entry point, follow a
  122. new build through the skills, or take the shorter path for a fix, demo or
  123. release. Each skill defines the inputs it uses and the evidence it hands on.
  124. ## Skills
  125. | Skill | Purpose |
  126. | --- | --- |
  127. | [omarchy-plugin-design](skills/omarchy-plugin-design/SKILL.md) | Choose kinds, boundaries, state, dependencies, IPC, and evidence before implementation. |
  128. | [omarchy-plugin-scaffold](skills/omarchy-plugin-scaffold/SKILL.md) | Generate a working Quattro plugin repository for any supported kind. |
  129. | [omarchy-qml-patterns](skills/omarchy-qml-patterns/SKILL.md) | Implement hosted QML with Omarchy theme, component, process, and state conventions. |
  130. | [omarchy-bar-widget](skills/omarchy-bar-widget/SKILL.md) | Build responsive bar widgets, settings, optional panels, and singleton services. |
  131. | [omarchy-panel-overlay](skills/omarchy-panel-overlay/SKILL.md) | Build panels, overlays, and menus with correct lifecycle, focus, and monitor behavior. |
  132. | [omarchy-service-ipc](skills/omarchy-service-ipc/SKILL.md) | Build process-wide services and stable IPC contracts without leaking credentials. |
  133. | [omarchy-plugin-debug](skills/omarchy-plugin-debug/SKILL.md) | Diagnose discovery, validation, load, reload, config, and runtime failures. |
  134. | [omarchy-plugin-test](skills/omarchy-plugin-test/SKILL.md) | Run manifest, static security, QML, fixture, and live-shell test layers. |
  135. | [omarchy-plugin-demo](skills/omarchy-plugin-demo/SKILL.md) | Create reversible demos and marketplace-ready screenshots using fictional data. |
  136. | [omarchy-plugin-release](skills/omarchy-plugin-release/SKILL.md) | Preflight a clean, documented, reproducible plugin release. |
  137. | [omarchy-plugin-publish](skills/omarchy-plugin-publish/SKILL.md) | Prepare and, after owner approval, submit the exact marketplace issue. |
  138. | [omarchy-plugin-migrate](skills/omarchy-plugin-migrate/SKILL.md) | Separate legacy machine integration from the Quattro shell surface and migrate safely. |
  139. ## Deterministic tools
  140. The scaffold skill now also includes the complete
  141. [plugin repository template](https://github.com/tcballard/omarchy-plugin-template)
  142. at a fixed commit. Ask for a new GitHub-ready bar-widget project, or follow the
  143. [offline starter instructions](skills/omarchy-plugin-scaffold/references/repository-template.md).
  144. Node.js 22+ generates the project without npm dependencies or network access;
  145. the existing six-kind generator remains available. The template travels with
  146. individual skill installs and every plugin/skills archive. The bundled starter is included from v0.8.0.
  147. The portable skills include reusable scripts that:
  148. - generate all six Quattro plugin kinds;
  149. - mirror Omarchy's manifest and path checks without requiring an Omarchy host;
  150. - report advisory marketplace security findings and review capabilities;
  151. - diagnose a local Omarchy installation without mutating it;
  152. - preflight releases and generate exact marketplace submission bodies;
  153. - install safely into supported agent-host skill locations; and
  154. - produce deterministic portable Agent Plugin and OpenAI submission archives.
  155. Run the repository verification suite with:
  156. ```bash
  157. ./scripts/test
  158. ```
  159. Package all distribution artifacts with:
  160. ```bash
  161. python3 scripts/package_submission.py --output-dir dist --require-clean --git-tree HEAD
  162. ```
  163. This produces the portable Agent Plugin, the OpenAI plugin, the OpenAI skills
  164. upload, reviewer materials, strict source/release manifests, an SPDX 2.3 SBOM,
  165. and one checksum manifest. Artifacts are built from the exact committed Git
  166. tree rather than ambient working files.
  167. ## Recommended companion: Omakit
  168. We recommend [Omakit](https://github.com/mtolhuys/omakit) alongside this bundle
  169. for reusable Run/Store plumbing and local marketplace preflight. Its `inspect`
  170. command highlights code worth reviewing, `verify` runs the pinned marketplace
  171. security baseline, and `submit` prepares submission checks and an issue draft
  172. without posting it. Omakit requires Node 22+ and Git; follow its
  173. [installation guide](https://github.com/mtolhuys/omakit/blob/main/docs/INSTALL.md).
  174. Use it against the intended committed candidate and record both that SHA and
  175. the marketplace baseline revision. Passing checks does not establish desktop
  176. behavior, security certification or marketplace approval. Omakit is an optional
  177. companion; this bundle's portable validators remain available without it.
  178. For deeper review, the optional
  179. [community security skill](https://github.com/wbso-ai/omarchy-plugin-security-skill)
  180. collects historical reviewer findings. For clean-desktop GUI testing,
  181. [OmaVM](https://github.com/mlclifton/omavm) provides QEMU/KVM guest workflows.
  182. Consult their current prerequisites and scope; neither establishes marketplace
  183. approval. The testing skill explains how to record their evidence and limits.
  184. ## Scope
  185. The default target is an Omarchy 4 Quattro shell plugin: a public Git repository
  186. with `manifest.json` and QML at its root. Older Omarchy integrations that install
  187. packages, systemd units, or privileged helpers are treated as a separate machine
  188. integration layer. The migration skill preserves that layer when it is genuinely
  189. required instead of pretending Quattro's no-install-hook model can replace it.
  190. ## Safety boundary
  191. Generated and reviewed Omarchy plugins are still unsandboxed third-party code.
  192. The static checks in this project are advisory and cannot prove that a plugin is
  193. safe. Review source and dependencies before enabling any plugin.
  194. ## Support and policies
  195. - [Support](SUPPORT.md)
  196. - [Security](SECURITY.md)
  197. - [Privacy](PRIVACY.md)
  198. - [Terms](TERMS.md)
  199. - [Contributing](CONTRIBUTING.md)
  200. ## License
  201. MIT
  202. ## Claude Code plugin (v0.9.0)
  203. Native Claude Code packaging was introduced in v0.3.1. From a reviewed v0.9.0 checkout,
  204. validate and try the plugin locally:
  205. ```bash
  206. claude plugin validate .
  207. claude --plugin-dir .
  208. ```
  209. The repository marketplace tracks the default branch. To install it in Claude
  210. Code:
  211. ```text
  212. /plugin marketplace add tcballard/build-omarchy-plugins
  213. /plugin install build-omarchy-plugins@tcballard-omarchy
  214. ```
  215. Use either this plugin or the existing `--target claude` skills installer to
  216. avoid loading duplicate skills. The v0.9.0 release build includes a separate
  217. `build-omarchy-plugins-claude-plugin-0.9.0.zip`, with the same twelve canonical
  218. skills and their helpers. This is a community marketplace, not an official
  219. Anthropic listing. OpenAI and Anthropic marketplace submissions remain on hold
  220. while stewardship is discussed.
  221. See [maintenance and adoption](docs/MAINTENANCE.md) for ownership decisions and
  222. [acceptance evidence](evals/ACCEPTANCE.md) for what has actually been exercised.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.