omarchy-plugin-build

Integrates omakit Run and Store blocks into Omarchy Quattro plugins for process and state management.

3|Updated Sep 12, 2026
One-click install
npx skills add https://github.com/mtolhuys/omakit --skill omarchy-plugin-build-mtolhuys
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: omarchy-plugin-build
Source: https://github.com/mtolhuys/omakit/tree/main/skills/omarchy-plugin-build
Command: npx skills add https://github.com/mtolhuys/omakit --skill omarchy-plugin-build-mtolhuys

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Omarchy plugin code that starts programs through bare QML Process blocks or keeps state through FileView writes fails marketplace security review with process-lifecycle, unbounded-buffering, environment-trust, and file-boundary findings. This Skill replaces those patterns with omakit's tested Run and Store blocks so the plugin passes review checks. ## Core Features & Use Cases - Run block integration: Copies Run.qml and run-supervisor.py into the plugin so every spawned program gets an absolute argv path, a closed environment, a deadline, and bounded stdout/stderr with defined result states. - Store block integration: Copies Store.qml and store-helper.py so plugin state lives in a private 0700 directory with schema validation, atomic writes, and a 64 KiB value cap. - Review alignment: Each block carries a sha256 header that omakit inspect recognizes as unmodified, collapsing security findings into a single clean row. - Use Case: A plugin polls a catalog script and caches remembered choices; you add both blocks, move each Process and FileView site onto them, and verify with omakit inspect that no process-lifecycle or file-boundary rows remain. ## Quick Start Ask the AI to add omakit's Run and Store blocks to your Omarchy plugin and migrate its Process and FileView code onto them.

Frequently Asked Questions about omarchy-plugin-build

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a shell command from an Omarchy QML plugin securely?▼

Run the omakit add run command in the plugin directory, then use the Run QML component with an absolute argv command array and a deadlineMs value. Bare Process blocks, execDetached, and bash -c shell strings are refused by the block.

How do I store plugin state files in Omarchy without FileView writes?▼

Add the Store block with omakit add store and declare a pluginId, file name, and JSON schema. Store writes atomically into a private 0700 directory under XDG_STATE_HOME with values capped at 64 KiB.

Can I modify the omakit Run or Store block files after copying them?▼

No. omakit inspect recognizes blocks by the sha256 in their header; a modified copy is reported as modified and read like any other file, and the update command refuses to overwrite it. Fixes belong upstream in omakit.

Why does my helper script fail when started through the Run block?▼

Run gives the program a closed environment containing only PATH=/usr/bin, HOME, LANG, and XDG_RUNTIME_DIR. Pass any additional variables explicitly through the environment property, and use absolute paths for programs the helper starts.

What are the limitations of the Store block for plugin files?▼

Store only keeps plugin state in its private directory with one value of at most 64 KiB per write. Copies, moves, or symlinks to variable destinations like hooks or wallpapers are not covered by any block yet.