53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
|
# Operational procedures
|
||
|
|
|
||
|
|
_Stable runbooks referenced from CLAUDE.md. Keep this file's procedures current — they are
|
||
|
|
the canonical copies._
|
||
|
|
|
||
|
|
## Renaming or moving a local plugin
|
||
|
|
|
||
|
|
Renaming a plugin directory under a directory-source marketplace (like `local-plugins`, whose
|
||
|
|
source is `~/.claude/plugins` itself) requires updating **three** places, not just the
|
||
|
|
directory and `settings.json`:
|
||
|
|
|
||
|
|
1. **Plugin directory / symlink** — the actual files (or symlink target, for plugins that
|
||
|
|
live in a git repo like `cc-os/plugins/os-vault/`).
|
||
|
|
2. **Marketplace manifest** — `~/.claude/plugins/.claude-plugin/marketplace.json` (for
|
||
|
|
`local-plugins`) lists each plugin's `name` and `source` path explicitly; this does
|
||
|
|
**not** auto-discover from the directory listing. Update the entry to match the new
|
||
|
|
name/path.
|
||
|
|
3. **`settings.json` `enabledPlugins`** — the `<name>@<marketplace>` key must match the
|
||
|
|
manifest entry from step 2.
|
||
|
|
|
||
|
|
Then refresh the plugin manager's state so it re-resolves the marketplace and drops the
|
||
|
|
stale install record:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
claude plugin marketplace update <marketplace-name> # re-validates the manifest
|
||
|
|
claude plugin install <new-name>@<marketplace-name> # creates the new install record
|
||
|
|
claude plugin uninstall <old-name>@<marketplace-name> # drops the stale one
|
||
|
|
claude plugin list # verify: new name enabled, old name gone
|
||
|
|
claude plugin details <new-name>@<marketplace-name> # verify skills/agents/hooks resolved
|
||
|
|
```
|
||
|
|
|
||
|
|
Skipping step 2 is the failure mode to watch for: hooks (wired by absolute path in
|
||
|
|
`settings.json`) keep working, masking the fact that skills/slash-commands silently stopped
|
||
|
|
registering under the plugin's new name. See ADR-0018.
|
||
|
|
|
||
|
|
## Editing a local plugin (cache refresh)
|
||
|
|
|
||
|
|
Plugin source edits (including SKILL.md wording, hook scripts, or CLI code) do not reach
|
||
|
|
running sessions until the cache is refreshed. Claude Code caches plugins when installed,
|
||
|
|
copying them to `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`. To refresh a
|
||
|
|
stale cache after source edits:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bin/refresh-plugins [marketplace-names...] # refresh all or specific local marketplaces
|
||
|
|
```
|
||
|
|
|
||
|
|
This uninstalls and reinstalls each plugin, forcing the cache to repopulate. See
|
||
|
|
`bin/refresh-plugins --help` for usage. After refreshing,
|
||
|
|
`claude plugin details <name>@<marketplace>` should show updated skill descriptions and hook
|
||
|
|
counts. Directory-source marketplaces (e.g., `local-plugins` sourced from
|
||
|
|
`~/.claude/plugins`, `cc-plugins` sourced from `~/dev/cc-plugins`) are the only ones that
|
||
|
|
need manual refresh — public marketplaces auto-update.
|