---
name: obsidian-plugin-ship
description: >-
  Ship an Obsidian community plugin: semver lockstep, GitHub Release assets
  (no v-prefix tags), community directory submission, and review-failure
  re-release. Use when releasing, bumping versions, fixing directory review,
  or /obsidian-plugin-ship.
---

# Ship an Obsidian plugin

Obsidian installs from a GitHub Release whose **tag equals** `manifest.json` `version`. It does not install from the git tree. A zip in the repo or a `v` prefix on the tag will not load in Community plugins.

Canonical submit guide: [Submit your plugin](https://docs.obsidian.md/plugins/releasing/submit-plugin).

DOM/CSS/settings bans: [obsidian-plugin-ui](../obsidian-plugin-ui/SKILL.md) and its [guidelines checklist](../obsidian-plugin-ui/references/guidelines-checklist.md). Do not restate those rules here.

Identity (`id`, `name`, `authorUrl`, `isDesktopOnly`): [obsidian-plugin-scaffold](../obsidian-plugin-scaffold/SKILL.md). Listing extra: `version` must be `x.y.z` semver; `name`/`description` sentence-level English, no emoji.

Done bar before a tag: hub [definition of done](../obsidian-plugin/SKILL.md), executed via [obsidian-plugin-verify](../obsidian-plugin-verify/SKILL.md).

## Version files

Keep these in lockstep on a release commit:

| File | Field |
| --- | --- |
| `package.json` | `version` |
| `package-lock.json` | root `version` and `packages[""].version` |
| `manifest.json` | `version`, and `minAppVersion` if you raised the floor |
| `versions.json` | `{ "<plugin version>": "<minAppVersion>" }` |

Do not bump on every feature PR. CI tests and builds; humans (or a manual `workflow_dispatch` job) cut the release.

If two PRs both ship, the merged version must be **greater than** `main`. CI itself must not push version commits.

Mechanics: [references/release.md](references/release.md).

## Review gate before you tag

Directory review is an automated gate. Before tagging, the UI checklist tests must pass. Editing the listing description does not re-run asset checks.

## Cut a GitHub Release

1. Bump version files in lockstep
2. Run the verify loop (`npm test`, `npm run typecheck`, `npm run build`, `npm run test:e2e` or a recorded skip after a real Obsidian install/launch attempt)
3. Refuse if tag `VERSION` already exists
4. Commit version files, tag `VERSION` (**no** `v` prefix), push branch and tag
5. Attach `main.js`, `manifest.json`, `styles.css` as release binaries (zip is optional extra)
6. Prefer artifact attestation when your Actions setup supports it

`PLUGIN_ID` in the workflow must equal `manifest.json` `id`.

## Community directory (first publish)

1. Default branch has `README.md`, `LICENSE`, and a correct `manifest.json`.
2. A GitHub Release exists for that `version` with the three assets.
3. Sign in at [community.obsidian.md](https://community.obsidian.md), link GitHub, add the plugin.
4. The directory reads `manifest.json` at HEAD of the default branch.
5. Automated review comments are blocking. Fix, bump, release again (see [release.md](references/release.md#after-a-review-failure)).

Older writeups say to PR `obsidianmd/obsidian-releases` `community-plugins.json`. Follow the live submit guide if that process has changed again.

After the plugin is listed, new tags on GitHub are enough. Do not open a directory PR for each version.

## Sideload / source install

Users who are not on the directory copy `main.js`, `manifest.json`, and `styles.css` into `.obsidian/plugins/<id>/`. Document that path. Optional: esbuild deploy via `OBSIDIAN_PLUGIN_OUT`.