---
name: omarchy-plugin-publishing
description: >-
  Submit, verify, update, publish, or troubleshoot an Omarchy plugin listing on
  omarchyplugins.com and the HANCORE marketplace. Use when completing marketplace
  forms, responding to listing validation, handling approved-and-verified,
  reopening or editing a submission, pushing an exact release candidate, or
  promoting a newer exact commit. Do not use for local implementation, linking,
  testing, or source changes; use omarchy-plugin-development. Requires current
  official instructions, commit-bound checks, and explicit owner approval before
  public actions.
metadata:
  internal: "true"
---

# Omarchy Plugin Publishing

Take a release-ready Omarchy plugin from an exact candidate commit through marketplace submission, verification, update, and publication. Treat official marketplace documents and issue templates as live contracts: refresh them every publishing session instead of relying only on this skill's examples.

This skill owns public marketplace operations. Local implementation, testing, full security review, local linking, manual testing, versioning, and release-candidate preparation belong to `omarchy-plugin-development`.

## Official sources

Fetch these at the start of every publishing session:

- Publishing guide: https://omarchyplugins.com/publish.html
- CLI and agent submission contract: https://github.com/HANCORE-linux/omarchy-plugin-marketplace/blob/main/SUBMISSION.md
- Submission form: https://github.com/HANCORE-linux/omarchy-plugin-marketplace/issues/new?template=submit-plugin.yml
- Verification contract: https://github.com/HANCORE-linux/omarchy-plugin-marketplace/blob/main/VERIFICATION.md
- Verification form: https://github.com/HANCORE-linux/omarchy-plugin-marketplace/issues/new?template=verify-plugin.yml
- Marketplace security policy: https://github.com/HANCORE-linux/omarchy-plugin-marketplace/blob/main/SECURITY.md
- GitHub security policy guidance: https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository
- GitHub private vulnerability reporting: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository

If current documents conflict with this skill, follow the official documents and update this skill afterward. Stop before submission if authoritative documents cannot be checked.

See [`references/forms.md`](references/forms.md) for the form map, [`references/submission-template.md`](references/submission-template.md) for CLI body structure, [`references/verification.md`](references/verification.md) for commit-bound states, and [`references/security-hardening.md`](references/security-hardening.md) for optional repository security practices.

## Require a release-readiness handoff

Begin with the release-readiness record produced by `omarchy-plugin-development`:

- plugin ID, name, and version;
- repository root URL;
- new listing or existing-listing update;
- exact candidate commit SHA, branch name, and currently listed commit when applicable;
- clean working-tree status, push status, and whether remote branch HEAD equals the candidate;
- tests and validation results;
- full security-review scope, findings, fixes, and residual risks;
- manual testing;
- capabilities, dependencies, privacy behavior, attribution, and preview status;
- release-facing commit message.

If this record does not exist, use `omarchy-plugin-development` to prepare it before continuing. Do not compress a full source review into marketplace form filling.

Verify the handoff against the repository:

- The exact candidate commit exists locally and contains the intended manifest version.
- The working tree is clean and the committed tree matches the reviewed snapshot.
- The repository root contains one plugin, valid manifest, README, license, notices when needed, and an allowed preview without private data.
- The root URL has no trailing slash or `/tree/...` path.
- The configured plugin ID set is unchanged for an update.
- Required tests, `omarchy plugin validate .`, QML lint, and diff hygiene passed on the exact candidate.
- Findings are resolved or explicitly recorded as residual risk; do not describe validation or review as a security audit.

Before publication, confirm the pushed remote branch head equals the exact reviewed candidate. If the candidate is not pushed yet, keep the local SHA as the proposed target and follow the push approval boundary below.

## Determine the operation

Choose exactly one path:

1. **Submit a new plugin** — the plugin is not listed yet.
2. **Verify the currently listed snapshot** — scan the exact commit already recorded by the listing.
3. **Verify and publish a newer upstream commit** — validate and atomically promote a new exact commit.
4. **Respond to feedback** — repair and resubmit after a finding, scan failure, review block, or publication failure.

Do not use the submission form to update an existing listing. Do not open a duplicate issue to retry a failed request unless the current official contract or an authorized maintainer explicitly requires a new issue.

A new plugin submission already includes commit-bound validation and verification through `approved-and-verified`; do not file a second verification issue after approval. The verification form is for already-listed snapshots and newer commits.

## Approval boundaries

Marketplace actions are public and plugins execute unsandboxed. Keep the owner in control.

Obtain explicit approval immediately before each action:

- pushing the exact release or corrective commit;
- changing repository visibility;
- enabling or disabling private vulnerability reporting or another repository security setting;
- creating a marketplace submission or verification issue;
- reopening an issue when resubmitting;
- editing an existing marketplace issue to trigger validation again.

A general request to publish does not replace showing the exact prepared action. Before a push, show the full SHA, branch, repository, commit title, and validation result. Before creating or editing an issue, show:

- exact issue title;
- complete issue body or every populated form field;
- repository URL and exact 40-character commit SHA;
- category and tags when applicable;
- every acknowledgment and whether it is checked.

Never store credentials or tokens in plugin source, issues, screenshots, or reports.

## Handle acknowledgments literally

Read each checkbox label together with its live description and required/optional state. Do not check a conditional acknowledgment merely because its sentence is factually true.

In particular, the verification form's **Standard installation acknowledgment** is currently described as required only when requesting removal of a manual-installation override. Leave it unchecked for ordinary verification or update requests unless that exact override-removal operation applies.

After editing an issue, read the body back and verify every checkbox, target SHA, and operation before reporting success.

## Recommend optional repository hardening

Before a first submission, recommend these as optional and non-blocking:

- Add `.github/SECURITY.md` with supported-version guidance and a private reporting path. Do not direct undisclosed vulnerabilities to public issues.
- Enable GitHub private vulnerability reporting after the repository is public.
- Confirm repository administrators receive security notifications.

A source policy addition or edit changes the reviewed tree. Return to `omarchy-plugin-development` to prepare and review a new exact candidate; do not commit or push source hardening from this skill. Ask for explicit approval immediately before changing any GitHub repository security setting. If the owner declines, record the choice and continue; these are not marketplace requirements.

See [`references/security-hardening.md`](references/security-hardening.md).

## Submit a new plugin

1. Confirm the plugin is absent from the marketplace and its ID has never been used by another current, retired, or renamed listing.
2. Refresh allowed categories, tags, fields, helper text, and checklist wording from the live contract.
3. Choose one category and one to three tags, then ask the owner to confirm them.
4. Populate the title as `[Plugin]: <manifest name>`; never leave only the prefix.
5. Prepare the browser fields or exact CLI body in the required order.
6. Ask the owner to confirm every checklist statement, especially ownership or permission for source and preview assets.
7. Show the complete proposed title and submission.
8. If visibility must change, show that action and obtain its own explicit approval before making the repository public.
9. If the candidate must be pushed, show the SHA, branch, remote, commit title, and validation result; obtain separate explicit approval, push, and verify remote branch HEAD equals the candidate.
10. After separate explicit approval, create the issue.
11. Record the issue URL and monitor validation, the Automated Security Baseline, remote review, and publication on that issue.

Screenshots are not a prerequisite when fields are known from the live form.

## Verify or update an existing listing

Use the verification form, not the new-submission form.

For **Verify the currently listed snapshot**, provide the plugin ID, repository root URL, and exact full `listingValidatedCommit` recorded by the marketplace. Do not substitute current HEAD.

For **Verify and publish a newer upstream commit**, provide the plugin ID, repository root URL, and exact full candidate SHA. Ensure the configured plugin ID set is unchanged. The existing snapshot remains active while validation is pending.

Before creating or editing the request, require the pushed remote branch HEAD to equal the full 40-character candidate SHA. If a push is needed, show the exact action and obtain separate approval first.

Then show every form value and acknowledgment, obtain explicit approval, and create or edit the request. Afterward, confirm bot reports bind to the intended commit rather than merely checking that old labels remain.

## Respond to feedback

Read the current validation, security-baseline, maintainer-review, and publication comments in full. Bind every finding to the exact reviewed commit.

When source changes are required:

1. Return to `omarchy-plugin-development` for implementation, tests, full or focused security review, manual testing, and a new exact release-readiness record.
2. Commit locally and capture the full SHA.
3. Show the exact push and obtain approval before pushing.
4. Prefer reopening and editing the existing request when the live contract permits it; do not create a duplicate merely because the old request was closed.
5. Show the complete proposed issue body and obtain separate approval before reopening or editing.
6. Verify the body after editing and confirm new bot reports reference the new exact commit.
7. A concise maintainer comment may summarize concrete fixes, but it does not replace updating the issue's target commit and must not claim a security audit.

Current baseline outcomes are:

- `passed` — eligible for the clean automated verification path;
- `review-required` — requires authorized maintainer acceptance of the exact reported capabilities and permitted findings;
- `needs-fixes` — requires a corrected repository and new validated commit;
- scan failure or stale/mismatched evidence — fail closed.

For new listings and promoted updates, publication requires the current `approved-and-verified` workflow. Historical labels or stale comments are insufficient.

## Interpret issue automation

Opening or editing a correctly formatted request may update existing bot comments in place instead of adding new comments. Timestamps and old labels alone do not prove that a new commit was checked.

Verify:

- issue is open when review is expected;
- issue body contains the intended full SHA;
- compatibility comment references that SHA;
- Automated Security Baseline references that SHA and has a complete result;
- required labels describe the current request;
- maintainer approval and final publication bind to that same SHA.

If workflow state is unclear, inspect the issue-triggered workflow run and current comments before advising another edit or duplicate request.

## Optional screenshot-assisted guidance

Screenshots supplement but never override the live issue template. Request one only when the user asks for visual guidance, reports a UI mismatch, a visible field is ambiguous, or authoritative form content cannot be fetched.

Reuse screenshots already supplied. Ask only for the unresolved section, explain the uncertainty, and avoid credentials, private notifications, unrelated tabs, or personal account data.

## Completion report

Report:

- operation performed;
- repository visibility and root URL;
- plugin ID and version;
- exact candidate, pushed, validated, and listed commit SHAs as distinct values;
- validation and release-readiness results;
- category and tags when submitting;
- issue URL and current labels;
- bot reports and the exact commit they reference;
- current marketplace state and required next action;
- security policy and private-vulnerability-reporting status;
- unresolved findings, residual risks, or maintainer action.