Skip to content

docs(playbook): document the local plugin development loop #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kyle-sexton merged 1 commit into from
Jun 24, 2026
Merged

docs(playbook): document the local plugin development loop #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/MIGRATION-PLAYBOOK.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,30 @@ For each skill/hook/agent being migrated:
2026-06-23). Then run `claude plugin validate --strict <repo-root>` to validate the **catalog manifest
itself** — a bad entry surfaces only there, not in per-plugin validation. Document the plugin in the README.

## Local development loop

For a plugin that already ships here, iterate against your local clone without re-publishing and
without changing any consumer's marketplace registration. `--plugin-dir` loads a plugin straight from
a directory; when its `name` matches an installed marketplace plugin, **the local copy takes
precedence for that session**, so you exercise working-tree edits against the installed copy without
uninstalling it (verified 2026-06-24).

```shell
# from this repo root — point at the plugin directory, not the marketplace root
claude --plugin-dir ./plugins/<name>
```

- **Edit, then `/reload-plugins`** to pick up changes without restarting — it reloads skills, agents,
hooks, and plugin MCP/LSP servers, reading the files on disk, so no commit or reinstall is needed.
- **Session-scoped and non-destructive.** The override lasts only for that session and never edits a
consumer's `extraKnownMarketplaces`; the published registration stays on its GitHub remote. The lone
exception: `--plugin-dir` cannot override a plugin that *managed* settings force-enable or
force-disable.
- **Trust.** A locally loaded plugin carries the same trust considerations as any source — only load
directories you control.
- **Then ship.** Run `claude plugin validate` before opening a PR; after merge, consumers pull the
change with `/plugin marketplace update melodic-software`, gated by the `version` bump in `plugin.json`.

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Tell consumers to update the installed plugin

For release instructions, this command only refreshes the marketplace catalog/version data; the Claude plugin reference lists installed plugin upgrades under /plugin update/auto-update and uses the plugin version as the cache key. A consumer with <name>@melodic-software already installed can run this and still keep using the old cached plugin code, so the playbook should include /plugin update <name>@melodic-software (then reload/restart as needed) when the intent is to receive shipped changes.

Useful? React with 👍 / 👎.


## What to wait on / avoid for now

- Don't pre-build cross-plugin `dependencies` graphs until two plugins genuinely share a need.
Expand Down
Loading