mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
* fix(plugins): separate shared intent from machine-local receipts Shared configs currently carry native paths, reviewed snapshots and pending failures, so one host can publish local progress over another host's target selection. Persist versioned declarations separately from local applied and pending receipts, and reconcile reviewed installs, imports and cleanup against this machine's native inventory without rewriting intent during sync/update. Keep snapshot names and adapter safeguards, move the operation lock locally, validate legacy adoption with local evidence, and invalidate approval on local state or native-context changes. Preserve source recipes after native adoption, require local import for absent native-only targets, and document the shared writer upgrade boundary in schemas and translated references. Cover two-host behavior, generated legacy fixtures, failure/recovery, stale intent, cleanup, npm recipes and the existing CLI/API/UI consumers with focused resource-capped tests. Fixes #651. * fix(plugins): preserve intent and ownership across host transitions Repeat-add must retain shared target selection, and update previews must resolve the requested ref before reviewing fresh or replacement installs. Keep disabled targets on the uninstall path and reject refs unsupported by native-only/npm intent before they can produce invalid shared declarations. Block changed-context add/import before Pi registration preparation so a new account cannot overwrite the old receipt. Preserve unresolved legacy bindings as passive private proof candidates before rewriting shared YAML, retaining original intent/store for later verified adoption and cleanup. Never compose these hints as executable state, and persist their explicit resolution. Cover the five review classes, native/private failure boundaries, requested-ref retry, and original-context hint proofs with isolated focused regressions. Keep local format v1 and baseline account validation unchanged. Refs #651. * fix(plugins): allow receipt-only orphan cleanup to complete An installation already removed on this host can retain a local receipt when another host removes or replaces shared intent. Sync correctly plans forget, but native command verification rejects that metadata-only action and blocks all targets before the receipt can be cleared. Exclude forget from native command verification while retaining host inventory checks and OMP scoped cleanup preparation. The existing completion path then persists receipt deletion, including pending work and passive legacy hints. Cover the cross-host disable/re-enable/remove walk, five native adapters, failed work with a legacy hint, and absent source replacement alongside a healthy target. Assert Apply completion, unchanged shared bytes/mtime, and a quiet second sync. Refs #651. * fix(plugin): reconcile ref intent across inventory consumers Validate explicit ref changes before disabled targets can save them and reuse one reviewed discovery throughout a preview. Surface shared ref changes as local reconciliation work while preserving the applied native identity and receipts. Reuse scoped legacy proofs for Pi extension ownership and make full inventory the dashboard's authoritative package/host pair. Cover invalid and replacement refs, read-only ownership, and shared-state properties without new persisted state or dependencies. * test(plugin): repair and consolidate host-state fixtures Create source intent and a pending imported Claude update through supported operations so direct and batch updates exercise the intended fixture. Keep the marketplace-loss case locally owned before testing its skipped reinstall. Consolidate cross-host repeat-add and requested-ref replacement/orphan retries at their existing owners, retaining failure recovery and shared-byte checks. Trim duplicate HTTP and translated-text assertions from consumer tests. * fix(plugin): reconcile legacy snapshot reads and native imports Resolve legacy snapshot ownership through existing scoped proofs before listing, reading or discovering cached source files. Keep adoption read-only and limit proof work to the requested package and targets; current receipts need no CLI. Only preserve reviewed source metadata on reimport when intent remains source managed. Native-only intent must not resurrect an older Git source after a same-ID local import. Retain identity mismatch and reviewed-source safeguards. Remove the unused source-folding helper left by the old shared runtime writer. * Preserve reviewed package versions locally * Fix reviewed package version lifecycle * fix(plugin): report missing local imports in doctor Show the local-import instruction instead of claiming a skipped imported plugin is healthy. Preserve the missing-CLI warning and shared config bytes. Keep fixture native settings inside scratch XDG directories and serialize the fake CLI calls used by concurrent inventories. Update assertions to separate shared declarations from local versions and native IDs, and align the raw-write audit with private plugin state and operation locks. * test(plugin): use declarations for doctor source fixture The missing-CLI case has no native ID, so encode it with the version 2 declaration schema. Keep the native-only import case in legacy syntax. * fix(plugin): install shared sources from reviewed snapshots When a source target is already declared, first sync must install its reviewed local snapshot even if the native client has a package from the same marketplace. Keep explicit add adoption and native-only import intact. Extend the existing two-host adoption check to cover an independent native installation on the second host and verify a quiet subsequent sync. * fix(plugin): preserve reviewed retries and native collision boundaries Retry a pending source update through the existing reviewed update path, so a rolled-back native failure cannot clear progress at the old snapshot. Record default-source versions for add, sync, and update while retaining the recipe fingerprint and generic-version checks for target overrides. Keep explicit native adoption, but block shared Claude sources when an independent same-name native plugin could shadow their hooks. Extract the existing adoption decision so the preview function becomes smaller. * test(plugin): respect OMP update safety in version control Check generic and target versions during review, then confirm the existing OMP upgrade guard preserves the installed and default-source versions. * fix(plugin): declare first local native imports explicitly A first local import into a shared source target now changes that target to native-only intent while preserving its sync selection. Verified source reimports retain their reviewed source and the preview discloses conversion. Cover the explicit import, local sync, and other-host cleanup flow, and remove the unconsumed internal observation assertion from the OMP test. * docs(plugin): explain first local import intent changes Describe the shared native-only target conversion and its effect on other machines, while distinguishing verified source reimports. * fix(plugin): verify checked sources before native reinstalls A checked update that becomes an install after native removal must still match the source digest the user approved. Reject moved or unchecked sources before native work, and allow a stable approved reinstall. Clear completed reinstalls from dashboard update availability while keeping failed targets available for retry. Cover both native presence states in the existing checked-update tests and the dashboard outcome rule. * fix(plugin): guard replacement before cleanup * fix(plugin): refresh discovery for each manager action A later Add action must review the current source even when the manager previously observed that source. Keep discovery sharing across one action while ending its cache before the next wizard invocation. Exercise a fresh source version after an earlier Add preview without TTY input or native writes, using an unavailable client to stop at review. * test(plugin): cover desired checks and final update outcomes Consolidate checked batch approval and dashboard completion tests while retaining removed-native, digest, version and approval controls. Reproduce stale shared recipes and failed or unfinished replacement installs. * test(plugin): make stale source discovery observable Remove the old repository before native-only and npm desired checks so those existing cases cannot pass by reading the applied source. * fix(plugin): check desired source and final outcome * test(plugin): bind checked updates to the observed recipe Reproduce a shared candidate change with equal version, commit and digest, and preserve a freshly checked replacement whose native ID differs. Use actual check observations in approval and native update controls, reject missing source identity, and verify the UI carries the observation through. * fix(plugin): bind checked update to source recipe * fix(ui): classify npm recipes as Pi packages * fix(plugin): retain legacy removal intent during migration Omit pending removals from shared declarations while retaining original local ownership proof so sync retries cleanup. Verification: focused regression passed in an isolated Linux Codex container, not the devcontainer (GOMAXPROCS=4, -p=4). * fix(plugin): keep imports local to an existing shared recipe Adopt a native installation into its local receipt without converting the shared source target or removing other machines installations. Verification: focused import regressions passed in an isolated Linux Codex container, not the devcontainer (GOMAXPROCS=4, -p=4). * fix(plugin): capture legacy evidence on first read Persist passive hints before another machine writes v2 and save verified adoption on reads. Apply reuses preview receipts instead of querying every legacy binding again. Document the per-machine pre-migration read. Verification: migration regressions passed in isolated Linux Codex container runs, not the devcontainer (GOMAXPROCS=4, -p=4). * fix(plugin): target named declarations in interactive imports Offer unresolved package names in dashboard and TUI imports and pass the selected name in single and batch requests. Drop display-only rendered assertions. Verification: 47 UI tests passed with at most four workers in an isolated Linux Codex container, not the devcontainer. * fix(plugin): localize shared intent plan guidance Add message keys for local imports, account changes, cleanup and native collisions across all dashboard locales. Localized guidance contains no CLI flags. Verification: failing localization regression now passes in an isolated Linux Codex container, not the devcontainer (GOMAXPROCS=4, -p=4). * refactor(plugin): reuse preview inventory and guard apply boundaries Capture hints on first load without persisting in-memory adoption during preview, keeping approval revisions stable. Apply reuses preview inventory. Reuse accountEnv and guard applyChange plus native write boundaries without inspecting argv. Verification: migration, receipt, account and sync regressions passed in an isolated Linux Codex container, not the devcontainer (GOMAXPROCS=4, -p=4). * test(plugin): organize host state coverage around lifecycle scenarios Group migration, ref drift, account context and cleanup tests behind shared host fixtures and public Preview/Apply assertions. Cover Codex, Cursor, Antigravity and project scopes; add second-machine doctor coverage and the two-machine runbook. Consolidate package-version tests and remove the unused private-record fixture. Verification: focused plugin regressions passed in an isolated Linux Codex container, not the devcontainer (GOMAXPROCS=4, -p=4). * docs(plugin): explain local imports and per-machine migration Document local receipts, per-machine review and commit pinning, config-path state identity and the required legacy read on every machine. Align sharing, doctor, troubleshooting, file-layout and four translated plugin references; restore schema editing guidance. Verification: context-router check passed. Runtime verification uses an isolated Linux Codex container, not the devcontainer. * refactor(plugin): separate unrelated review scope Move project OMP configuration, plugin list ordering, and npm Pi classification to independent local branches based on upstream/main. Keep the shared intent change focused and cover named import selection in the pure flow helper. The three local branches have passing builds in a Linux Codex container, not the devcontainer, with isolated test homes and capped parallelism. * perf(plugin): avoid recapturing v2 state on reads Only compare and persist passive migration hints when legacy bindings exist. Native v2 reads need no state serialization for migration. Verification: pending removal and first-read/import regressions passed in a Linux Codex container, not the devcontainer, with isolated HOME/XDG/TMPDIR and GOMAXPROCS=4 GOFLAGS=-p=4. * docs(plugin): clarify native marketplace repair after import A local import receipt is not a reviewed reinstall source. Correct the remaining troubleshooting instruction and its four translations to require native-client repair, and align the nearby code comment. Validation: checked against prepareChange, context-router check and git diff --check passed. Verification for this review ran in a Linux Codex container, not the devcontainer. * fix(plugins): preserve local ownership across shared intent changes Retain completed legacy migration markers so unchanged v1 YAML cannot uninstall a later manual reinstall. Serialize read-side hint persistence with native operations and keep local imports when shared recipes change. Require explicit dashboard import names and validate recipe identities. Correct schema descriptions, messages, CLI ref status, translated migration guidance and runbooks. Add failing-first Preview/Apply regressions and a real two-ssenv CLI lifecycle script. * fix(plugins): preserve migration history and show retained import guidance Mark existing legacy hints and receipts as captured before cleanup so state from the previous serializer cannot re-adopt a later manual installation. Keep recipe-change guidance in unchanged sync outcomes and visible dashboard rows, and resolve nested OpenCode entries through their package manifest. Cover public migration, ref, account, import and message contracts across adapters. Correct the real two-host Cursor assertions, explicit dashboard selection flow, and remaining localized guidance. * fix(plugins): retain explicit OpenCode entry during import matching Standalone OpenCode packages can rely on a reviewed explicit entry rather than an SDK dependency. Preserve that entry when reading native package identity so matching nested imports remain supported. * fix(plugins): preserve migrated imports and verify native entry identity Recognize older native-only receipts by their existing declaration fingerprint so remote source recipe edits cannot replace migrated imports. Keep managed npm receipts distinct through their source fingerprints. Only borrow an ancestor OpenCode package identity when its resolved entry is the actual registered file. Retain nested and explicit entry support. Add public two-host migration and mismatching-entry regressions. * fix(plugins): retain imported ownership through repeated adds Persist inferred imported ownership when a matching add refreshes the receipt intent, so later shared recipe changes still preserve local native installations. Keep the legacy replacement regression aligned with that ownership contract while retaining removed-intent cleanup. Reject missing or unstatable absolute OpenCode entries before identity matching rather than falling back to the file name. Cover both paths through public Preview and Apply regressions. * test(plugins): isolate OpenCode adapter fixtures from host config Keep native registration fixtures inside their fake agent home by setting XDG_CONFIG_HOME and clearing inherited OpenCode overrides. Ambient config writes can otherwise leak into config-discovery tests in other packages. Cover the XDG, file, directory and inline override cases with temporary config sentinels, while retaining the existing MCP listing expectation. * fix(plugin): let local imports return to the shared source Add a local unimport action that removes only this machine’s installation and receipt while preserving the shared source declaration. Keep retained-import guidance visible across matching adds, list, doctor and dashboard consumers. Avoid idle OMP guidance and unchanged legacy-read locks, preserve localized errors, keep import identity checks offline, and normalize OpenCode drive URLs. Cover the A/B transition and align translations, runbooks and environment cleanup. * fix(plugin): complete unimport validation and guidance Reject missing targets before planning local unimports and share per-target eligibility with the wizard. Make native uninstall effects explicit in help and translated docs, preserve structured update guidance, and cover error paths and shell completion.
614 lines
40 KiB
Markdown
614 lines
40 KiB
Markdown
---
|
||
sidebar_position: 4
|
||
---
|
||
|
||
# plugin
|
||
|
||
Manage complete native plugins across supported tools. Capability checks distinguish
|
||
installation support from format discovery. Start with
|
||
[Manage plugins across tools](/docs/how-to/daily-tasks/sharing-plugins).
|
||
|
||
```bash
|
||
skillshare plugin # Interactive manager
|
||
skillshare plugin add # Source → plugin → targets → review
|
||
skillshare plugin discover ./my-plugin --json
|
||
skillshare plugin add ./my-plugin --target claude --target codex --no-tui
|
||
skillshare plugin add ./my-plugin --no-tui # Keep it in Skillshare; choose targets later
|
||
skillshare plugin import review@team --from claude --no-tui
|
||
skillshare plugin list --json
|
||
skillshare plugin inspect review --json
|
||
skillshare plugin disable review --target codex --no-tui
|
||
skillshare sync plugins --dry-run --json
|
||
skillshare sync plugins --no-tui
|
||
skillshare plugin enable review --target codex --no-tui
|
||
skillshare plugin check review --json
|
||
skillshare plugin update review --target claude --no-tui
|
||
skillshare plugin update --all --no-tui
|
||
skillshare plugin remove review --no-tui
|
||
```
|
||
|
||
`enable` and `disable` change **Skillshare's sync selection**, not the Agent's native
|
||
enabled state. Deselecting a target saves the choice. The next `sync plugins`
|
||
removes its managed installation while retaining the definition. Selecting it
|
||
again allows the next sync to reinstall it. Unmanaged plugins are unaffected.
|
||
|
||
`add` without `--target` (or with nothing selected in the interactive picker) keeps
|
||
the plugin in Skillshare without installing it anywhere. Add targets later with the
|
||
same source and `--name`, or from the plugin's row in the dashboard; that install
|
||
uses the source as it is then. Such a plugin stays managed when its last target is
|
||
removed. `remove NAME` without `--target` removes it from Skillshare.
|
||
|
||
## Commands
|
||
|
||
| Command | Behavior |
|
||
|---|---|
|
||
| `list` | Configured bindings and native installation state; interactive manager in a terminal |
|
||
| `discover SOURCE` | Inspect a local directory, `owner/repo`, or HTTPS Git repository |
|
||
| `add [SOURCE]` | Choose and install a whole plugin with its target adapter, or an `npm:` package through Pi |
|
||
| `import [NATIVE-ID]` | Adopt an existing installation without reinstalling or enabling it |
|
||
| `unimport NAME` | Uninstall this machine’s imported bindings for explicit targets; keep shared source declarations |
|
||
| `inspect NAME` | Inspect one managed package |
|
||
| `sync [NAME]` | Reconcile selected targets and retry incomplete native operations |
|
||
| `check [NAME]` | Compare source content with the recorded digest, or a Pi npm package's version with npm's latest; never update |
|
||
| `update [NAME \| --all]` | Review source changes and use a supported native update operation |
|
||
| `enable / disable [NAME]` | Include/exclude a target in the next sync |
|
||
| `remove [NAME]` | Uninstall managed bindings and remove their definitions |
|
||
|
||
Bare commands prompt for missing inputs in a terminal. Noninteractive mutation
|
||
commands require explicit inputs. `sync` and `check` may operate on all packages;
|
||
`update` updates all managed packages when passed `--all` (`-a`).
|
||
`sync --all` does **not** include plugins; use `sync plugins` explicitly.
|
||
|
||
## Options
|
||
|
||
| Option | Meaning |
|
||
|---|---|
|
||
| `--target TARGET` | Repeatable selection: `claude`, `codex`, `cursor`, `antigravity` (`agy` alias), `antigravity-cli`, `copilot`, `grok`, `pi`, `omp`, `opencode`, or the name of [another account of an Agent](#accounts); see the capability table below |
|
||
| `--plugin NAME` | Select one plugin from a source marketplace |
|
||
| `--name NAME` | Logical package name when adding or importing |
|
||
| `--from TARGET` | Import from Claude, Codex, Antigravity CLI, Copilot, Grok, Pi, OMP marketplaces, OpenCode, or [another account of an Agent](#accounts) |
|
||
| `--all`, `-a` | Update all managed plugins (`update` only; cannot be combined with a package name or `--source-ref`) |
|
||
| `--dry-run`, `-n` | Preview without changing Skillshare or Agent configuration |
|
||
| `--source-ref REF` | Git branch, tag, or commit for `discover`, `add`, and `update`; remote sources only |
|
||
| `--entry PATH` | Explicit built OpenCode JS/TS entry, relative to the package root (`discover` and `add`) |
|
||
| `--revision ID` | Refuse application if source, configuration, or native inventory changed since preview |
|
||
| `--json` | Machine-readable output; disables TUI |
|
||
| `--no-tui` | Disable interactive menus; also respects `tui: false` |
|
||
| `--global`, `-g` | Global Skillshare config and native user scope |
|
||
| `--project`, `-p` | Project config; Claude, Antigravity, Pi, OMP, or OpenCode (never global fallback) |
|
||
|
||
JSON output includes source paths and native identifiers. Do not put credentials
|
||
in source URLs. A failed mutation can still return successful per-target outcomes;
|
||
the CLI exits nonzero when any target fails. Inspect the result before retrying.
|
||
|
||
## Target support
|
||
|
||
| Target | Format | Global | Project | Update |
|
||
|---|---|:---:|:---:|---|
|
||
| Claude Code | `.claude-plugin/plugin.json` | Yes | Yes | Native update |
|
||
| Codex | `.codex-plugin/plugin.json` or Agent Plugins root manifest | Yes | No | Refresh reviewed source and add it again, only if enabled in Codex |
|
||
| Cursor | `.cursor-plugin/plugin.json` or Agent Plugins root manifest | Yes | No | Replace reviewed local copy |
|
||
| Antigravity Desktop | Root `plugin.json` with an explicit name | Yes | Yes | Replace reviewed local copy |
|
||
| Pi | `package.json` with `pi` resources, or `pi-package` keyword and conventional resource folders | Yes | Yes, with native project trust | Refresh managed source snapshot |
|
||
| Oh My Pi | Marketplace-backed local/Git plugins with native-compatible metadata | Fresh-cache install/reinstall, import and scoped removal | At OMP's project anchor | Updates blocked; removal retains shared cache |
|
||
| OpenCode | `package.json` with an SDK dependency, `.opencode/plugins/` entry, or explicit `--entry` | Yes | Yes | Refresh managed source snapshot |
|
||
|
||
| Antigravity CLI | Native root manifest or Claude manifest accepted by `agy` | Yes | No | Refresh reviewed source, only if native enabled state is known and enabled |
|
||
| GitHub Copilot CLI | `.plugin/plugin.json`, `.github/plugin/plugin.json`, Claude manifest, or Agent Plugins root manifest | Yes | No | Refresh reviewed source, only if native enabled state is known and enabled |
|
||
| Grok Build | `.grok-plugin/plugin.json` or Claude manifest | Import/remove only; native trust required for install | No | Update natively |
|
||
| Kimi Code | `kimi.plugin.json` or `.kimi-plugin/plugin.json` | Discovery only | No | Not automated |
|
||
| Hermes | `.hermes-plugin/plugin.yaml` | Discovery only | No | Not automated |
|
||
| Devin | `.devin-plugin/plugin.json` | Discovery only | No | Not automated |
|
||
|
||
Kimi's noninteractive lifecycle, Hermes's profile inventory/consent, and Devin's
|
||
local inventory/trust/cloud distinction are not yet verified by these adapters.
|
||
Their formats are shown during discovery, but installation is disabled with a
|
||
reason. A source declaring a target does not imply that Skillshare can manage it.
|
||
`list --json` and `discover --json` include `targetDefinitions` with allowed
|
||
operations; discovery also exposes `targetInfo` for each format's version,
|
||
components, entry, and validation problem. A broken manifest is isolated to its
|
||
target; a malformed catalog is reported as a warning without hiding valid formats.
|
||
|
||
### Another account of an Agent {#accounts}
|
||
|
||
A target declared as [another account of an Agent](/docs/reference/targets/configuration#agent-config-dir) is a plugin target too, for `claude`, `codex`, `opencode` and `pi`. Skillshare runs that Agent's own CLI against the account's config directory, through `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `OPENCODE_CONFIG_DIR` or `PI_CODING_AGENT_DIR`:
|
||
|
||
```yaml
|
||
targets:
|
||
claude-work:
|
||
agent: claude
|
||
config_dir: ~/.claude-work
|
||
```
|
||
|
||
```bash
|
||
skillshare plugin add owner/repo --target claude-work
|
||
skillshare plugin import demo@market --from claude-work
|
||
```
|
||
|
||
An account with [`cli`](/docs/reference/targets/configuration#agent-config-dir) runs that compatible CLI instead, such as `omo` for a Pi account, against the same config directory. A Pi account also sets `SENPI_CODING_AGENT_DIR` and `OMO_CODING_AGENT_DIR`, which Pi forks read before `PI_CODING_AGENT_DIR`. If the CLI cannot be found, the operation fails; Skillshare does not fall back to the Agent's own.
|
||
|
||
The account takes the operations of the Agent it belongs to and keeps its own bindings under its own name, so a plugin can be installed in one account and not in the other. Accounts exist in global scope only: a project's plugins belong to the project, not to one account. `--target` and `--from` accept the account name, and the terminal picker and the dashboard's Plugins page list it next to the Agents.
|
||
|
||
### Cursor and Antigravity
|
||
|
||
These adapters copy the whole plugin into documented local discovery directories.
|
||
They do not require a CLI executable or modify marketplace registries:
|
||
|
||
- Cursor: `~/.cursor/plugins/local/<name>`; local imports must be allowed. Reload
|
||
Cursor and check Customize. An installed marketplace plugin with the same name
|
||
takes precedence over a local copy.
|
||
- Antigravity desktop: `~/.gemini/config/plugins/<name>` globally; `.agents/plugins/<name>`
|
||
in a workspace (or an existing `_agents/plugins/` directory). If both workspace
|
||
directories exist, consolidate them first.
|
||
- The standalone **agy CLI** has a separate plugin store. The `antigravity` target
|
||
manages the desktop/workspace discovery paths, not that CLI store. `agy` is only
|
||
a Skillshare target alias. Use `--target antigravity-cli` for the standalone CLI;
|
||
`--target agy` retains its existing desktop meaning.
|
||
|
||
Use `plugin add` for these local packages. Importing pre-existing local folders or
|
||
marketplace installs is not supported. Skillshare refuses to overwrite unowned
|
||
folders, symlinks, or locally edited managed content. An explicit Antigravity
|
||
manifest name keeps the identity stable across Git checkouts and snapshots.
|
||
|
||
### Oh My Pi (OMP) {#omp}
|
||
|
||
OMP uses its own marketplace lifecycle, not Pi's package commands. Skillshare
|
||
manages reviewed local/Git plugin sources and imports native marketplace entries
|
||
identified as `name@marketplace`:
|
||
|
||
```bash
|
||
skillshare plugin add ./my-omp-plugin --target omp --dry-run --json -g
|
||
skillshare plugin add ./my-omp-plugin --target omp --no-tui -g
|
||
skillshare plugin import demo@my-market --from omp --dry-run --json -g
|
||
```
|
||
|
||
Installation requires OMP **18.6.1+**, a reviewed local/Git source and a verified,
|
||
previously unused cache destination and an absent scope-local runtime destination.
|
||
The runtime package name comes from the reviewed source, not just the marketplace
|
||
name. Existing module directories or links block installation rather than being
|
||
replaced; the destination is bound to the preview and checked again before install.
|
||
The adapter keeps the plugin tree together,
|
||
uses native marketplace installation, and verifies the resulting registration. Catalogs can use
|
||
`.omp-plugin/marketplace.json`, with `.claude-plugin/marketplace.json` as a fallback
|
||
only when no OMP catalog exists. An OMP catalog entry can point to a package with
|
||
`omp.extensions` or `pi.extensions` in `package.json`; its marketplace name identifies the plugin even
|
||
when the npm name differs or is absent. If two catalogs place the same plugin in
|
||
different folders, OMP keeps its own path, version and components. Text discovery
|
||
shows these builds on separate rows; JSON keeps one logical candidate with
|
||
per-target paths and metadata in `targetInfo`. The shared `version` is empty when
|
||
target versions differ or one is unknown; adding without an Agent does not record
|
||
an arbitrary build version. A missing or invalid OMP entry never
|
||
falls back to the Claude build while an OMP catalog exists.
|
||
Preview does not invoke OMP's native `--dry-run`, which can write files. Review
|
||
the source before applying: OMP can execute plugin
|
||
extensions and tools in-process at the next startup, without a project trust
|
||
prompt. Installation is not proof that those resources loaded successfully.
|
||
|
||
**Shared-cache limitation in OMP 18.6.1+:** its native uninstall and upgrade can
|
||
delete or replace plugin cache files still referenced by a different project.
|
||
Native inventory lists only the user registry and the current project's registry,
|
||
so it cannot establish the safety of those operations across other projects.
|
||
Skillshare does not invoke those destructive commands. **Remove** and
|
||
disable-plus-sync instead use a scoped adapter that deletes the installation's
|
||
registry entry, runtime selection and verified `node_modules` link. The plugin
|
||
is uninstalled from that scope, not merely disabled. Shared cache, marketplaces
|
||
and plugin settings are retained; no cache garbage collection is attempted.
|
||
Reinstall automatically chooses a fresh marketplace/cache identity when the old
|
||
cache still exists, without replacing files another project may use. Unreadable,
|
||
linked or non-directory cache destinations remain blocked.
|
||
|
||
Removal requires the verified 18.6.1+ metadata contract, matching installed
|
||
version, unambiguous JSON and proven runtime-link ownership. A real module folder,
|
||
foreign link, npm dependency collision or ambiguous runtime owner is refused.
|
||
If the cache manifest is missing, the adapter requires a unique runtime-lock key
|
||
whose scope-local link points to that installation's cache; it never guesses the
|
||
marketplace name and reports success with the actual runtime link still installed.
|
||
Unverifiable active installations remain blocked. If native uninstall already
|
||
removed the cache, registration and runtime link/selection, Forget drops only the
|
||
stale Skillshare binding; another plugin's `node_modules` directory does not block it.
|
||
Native file changes invalidate the preview. Partially completed removal can be
|
||
retried from the retained cache and binding identity without saving full native
|
||
settings backups. Windows writes additionally require verifiable private ACLs;
|
||
Skillshare does not change permissions to make them pass. No extension code runs.
|
||
|
||
The adapter serializes Skillshare removals and checks native file revisions, but
|
||
OMP's plugin commands do not participate in its lock; do not run native plugin
|
||
mutations concurrently. This is not an atomic multi-file native transaction.
|
||
**Updates remain blocked** until a non-destructive upgrade contract is available;
|
||
imported code is never upgraded without a reviewed source.
|
||
|
||
Project operations require the selected root to match OMP's native project
|
||
anchor; they never silently install globally or in an ancestor project. Native
|
||
profile/config-root overrides (`PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`,
|
||
`OMP_PROFILE` or `PI_PROFILE`) block plugin management. A relocated native cache
|
||
invalidates an existing preview. An arbitrary account `config_dir` does not redirect OMP's
|
||
plugin store, so OMP account plugin targets are not supported.
|
||
|
||
Native npm/Git/link packages are visible in inventory but are not imported as
|
||
marketplace plugins. Manage those packages in OMP; `plugin add npm:...` remains a
|
||
Pi-only workflow. Do not separately copy a plugin's extensions, hooks, skills or
|
||
MCP entries into Skillshare's other resources.
|
||
|
||
#### Choosing standalone OMP extensions
|
||
|
||
Open an OMP target's **Extensions** tab to review file-based selection. Cards group
|
||
files by source and scope, with plugins grouped by their inspected package root
|
||
and other files by directory. File lists remain visible. Plugin cards use a package
|
||
icon and `Plugins · <name>` heading from the native package identity, not the
|
||
extension folder name. Known manifest versions and scope stay visible, with an
|
||
**Open Plugins** navigation icon rather than repeated origin tags. Shared folders
|
||
are plugin-relative, and full file paths remain in tooltips. **Details** uses the
|
||
same labeled two-column layout as Pi for the full source, native name, selection
|
||
identifiers and notes. Missing identity metadata falls back to the inspected
|
||
folder; no package identity or version is guessed. Read-only
|
||
reasons and links to Hooks or Plugins remain visible with their entries.
|
||
Supported standalone modules have switches; **Preview** shows the change and **Apply**
|
||
writes only `disabledExtensions` in the selected native YAML settings file.
|
||
Global, project and explicitly configured account directories remain separate.
|
||
The editor preserves unrelated YAML and comments, checks the reviewed revision
|
||
again under OMP's native lock, and refuses stale or busy writes.
|
||
|
||
Selection editing requires a verifiable OMP **18.6.1+** package behind the selected
|
||
launcher. Unidentified versions, standalone binaries and wrapper launchers stay
|
||
read-only. This check reads package metadata without running OMP. Same-name
|
||
module groups, explicit files that bypass the disabled-name filter, ambient
|
||
`hooks/pre|post` factories, uncertain selection and linked paths are read-only.
|
||
Hooks-owned and plugin-owned entries stay with their respective managers.
|
||
|
||
The backup records the before/after selection and settings hashes under
|
||
`omp-extensions/backups` in Skillshare's state directory, not unrelated YAML
|
||
values or credentials. It is a selection recovery record, not a whole-settings
|
||
restore. A successful apply describes configuration on disk, not a running
|
||
extension; restart/reload remains an OMP action.
|
||
|
||
### Pi and OpenCode
|
||
|
||
Pi keeps the first global registration and the last project registration of a
|
||
package. If an earlier global or later project source has an unresolved identity,
|
||
Skillshare cannot prove which entry owns a package and keeps potentially shadowed
|
||
entries Unknown/read-only, including inherited project deltas. It does not guess
|
||
identity by stripping URL queries. Proven entries outside that ambiguity remain editable.
|
||
|
||
Pi uses `pi install` / `pi remove`; inventory reads documented package settings
|
||
without loading extension code. `PI_CODING_AGENT_DIR` is respected. Pi project
|
||
trust must be established in Pi; Skillshare does not pass `--approve` for you.
|
||
|
||
#### npm packages from pi.dev
|
||
|
||
`plugin add npm:<package>` installs a package published to npm, such as one listed on
|
||
[pi.dev](https://pi.dev/packages), through Pi itself:
|
||
|
||
```bash
|
||
skillshare plugin add npm:@scope/package --target pi --dry-run --json -g
|
||
skillshare plugin add npm:@scope/package@1.2.0 --target pi --no-tui -g
|
||
```
|
||
|
||
Pi downloads the package and runs its install scripts, so Skillshare can't review its
|
||
content first; check the package on pi.dev or npm before adding it. `discover` does not
|
||
accept npm sources, and an npm source takes no `--source-ref`, `--entry` or `--plugin`.
|
||
Only Pi targets take npm sources, including a Pi account that runs `pi`. For an account
|
||
that runs another executable, install the package with that executable, then import it.
|
||
With `--project`, Pi installs the package into the project's settings; once the project
|
||
has a `.pi` folder, Pi changes its packages only after you trust the project in Pi.
|
||
|
||
Pi keeps one entry per package name. If Pi already has the same source, `add` imports
|
||
it; another version of the package is installed, and Pi replaces that entry's source.
|
||
`update` runs `pi update`, except for a package pinned to an exact version, which Pi
|
||
keeps: add the package again with the new version instead. For a package added without a
|
||
version, `check` compares the version in the installed package's `package.json` with the
|
||
version npm's `latest` tag names on the public registry, and `update` leaves a package that is
|
||
already at that version alone. A package added with a version range or tag, one that the
|
||
environment or an `.npmrc` sends to another registry, or one whose version is not a plain
|
||
`X.Y.Z`, is reported as something to check in Pi. The dashboard shows the installed version of every Pi package, on
|
||
the Plugins page and in a Pi target's Extensions tab. When you turned off some of the
|
||
package's extensions, Pi keeps those rules on the new version, and Skillshare records them
|
||
again so a later reinstall restores them. A Pi package that another Skillshare package
|
||
already manages is refused; update or remove that one instead.
|
||
|
||
In the dashboard's add dialog, you can paste the `pi install npm:<package>` command or the
|
||
package's pi.dev address; either becomes its `npm:` source.
|
||
|
||
#### Choosing a package's extensions
|
||
|
||
In the dashboard, the target page of `pi` and of a Pi account has an **Extensions**
|
||
tab. It lists each package entry of that target's `settings.json` with the
|
||
extensions its filters select. Packages managed by Skillshare use a package icon
|
||
and `Plugins · <name>` heading, matching OMP plugin cards. They retain the installed
|
||
version, scope and relevant project override shape; the navigation icon opens
|
||
Plugins. Unmanaged Pi packages keep their native identity and Pi icon. This
|
||
presentation does not change ownership or extension-selection rules. Extension
|
||
rows remain visible; **Details** independently shows the source and filter rules.
|
||
A switch writes one exact `+path` or `-path` rule
|
||
into that entry's `extensions` list. When removing the file's own exact rule already
|
||
gives the state the switch asks for, the switch removes that rule instead, so turning
|
||
a file back to what the remaining rules select leaves no rule behind. **Remove rule**,
|
||
shown when the switch would not remove the rule itself, deletes the exact rule for that
|
||
file, written as a relative or an absolute path, and the file then follows the
|
||
remaining rules; the preview shows the result. Apply shows a preview first and
|
||
edits only those lists: the entry's other keys, its `skills`, `prompts` and
|
||
`themes` filters, glob and `!` rules, and the rest of the file stay exactly as
|
||
written. A string entry becomes `{"source": ...}` so it can hold a rule. For a
|
||
string entry, Pi takes a package's skills, prompts and themes only from its `pi`
|
||
manifest, while an object entry also loads them from the package's `skills`,
|
||
`prompts` and `themes` folders when the manifest leaves them out. A string entry
|
||
of a package with such a folder is read-only, because Skillshare can't show that
|
||
converting it leaves those resources as they are. A source that is one file is
|
||
read-only too, because Pi loads it as it is and ignores filters. A user-scoped npm registration without a managed cache is Unknown/read-only, not
|
||
necessarily uninstalled: Pi may use a legacy global npm/pnpm root that Skillshare
|
||
does not probe. If the file changed after the preview, or Pi holds its settings lock, nothing is written.
|
||
An empty lock directory older than Pi's 10-second stale threshold can be reclaimed
|
||
only if its inode and mtime are unchanged. Fresh, renewed, replaced, nonempty,
|
||
file, and symlink locks are refused. Reclamation follows Pi's stale-lock protocol;
|
||
age does not prove an owner has died, and the final check/removal is not an atomic CAS.
|
||
While writing, Skillshare holds that lock the way Pi does and writes nothing if it
|
||
loses it. Before each apply, Skillshare saves a persistent record of the changed
|
||
extension lists and the before/after file hashes. Successful records are kept
|
||
without automatic pruning; if Apply fails, only the new record for that attempt
|
||
is removed. This is not a copy of `settings.json` and cannot restore the whole file. The tab lists every package in the settings, including ones installed with Pi itself, such as `npm:` packages from [pi.dev](https://pi.dev/packages). Skillshare installs and removes packages only through `plugin`: `plugin add` takes a local directory, a Git source or an [npm package](#npm-packages-from-pidev), and `plugin import --from pi` adopts a package installed with Pi.
|
||
|
||
Skillshare reads packages without running them, so the tab shows what the
|
||
settings select (switches and selection notes), not whether Pi loaded them; reload Pi
|
||
after applying. A file the settings name but the package lacks is marked as
|
||
missing. A choice Skillshare can't work out shows **Can't tell** with the reason
|
||
and where to change it, never a guessed on or off. Editing needs the target's own
|
||
Pi to be 0.99.2 or later (the oldest version checked against Pi itself) and
|
||
strict JSON settings; an older version is read-only and the tab says which version it found. A Pi account that runs a
|
||
different executable is read-only, and Skillshare does not run it. An entry whose
|
||
list is `[]` (nothing loads) is read-only, as is any extension decided by a
|
||
pattern Skillshare cannot evaluate, such as `?` against an emoji. An entry with an
|
||
empty source, or whose source or rules contain an unpaired UTF-16 surrogate escape
|
||
or invalid UTF-8, is left as written and read-only, since Skillshare can't read it
|
||
exactly as Pi does. Pi uses only the first global entry of a package, so when
|
||
Skillshare can't read that entry, the package's later entries are read-only too.
|
||
|
||
A project that syncs to Pi has the same tab on its project page. It shows each
|
||
package as the project's settings select it on top of the global ones, marked as
|
||
inherited from `pi (global)` or as a project override. A switch saves a rule to
|
||
the project's `.pi/settings.json` only, the way `pi config` does: a global package
|
||
gets a project entry `{"source": ..., "autoload": false, "extensions": [...]}`
|
||
that changes only the files it names and leaves the global entry as it is. A local
|
||
source is written relative to `.pi`, an npm or git source as the global settings
|
||
have it. When the last project rule of such an entry is removed, the entry is
|
||
removed only if that cannot reveal an earlier registration's filters; otherwise
|
||
the empty winning override is kept. Only explicit JSON `false` means a delta;
|
||
`autoload: null` is not `false`. A project entry with `autoload: false` and no global entry loads only the
|
||
files it names with `+`. The file, and its `.pi` folder, are created only when you
|
||
apply. The global settings and Pi's `trust.json` are never written, and
|
||
Skillshare never trusts a project for you: Pi uses the project's settings only if
|
||
it trusts the project. A global source that carries credentials or a query is
|
||
never copied into a project, so that package is read-only there, and so is every
|
||
package when the project's settings have an entry Skillshare can't read. Apply
|
||
holds Pi's lock on the project file and checks both settings files and the
|
||
package again right before it writes. Extensions in Pi's own `extensions`
|
||
folders, including files linked there by [extras](./extras.md), are listed
|
||
read-only with where to change them; a project lists its own folder, which Pi
|
||
reads only if it trusts the project, and the global one.
|
||
|
||
OpenCode registers the managed entry as a file URL in `opencode.json` or the
|
||
existing `opencode.jsonc`, preserving comments and unrelated entries. Version 1
|
||
uses `plugin`; version 2 uses `plugins`. `XDG_CONFIG_HOME` and an absolute global
|
||
`OPENCODE_CONFIG` are respected; ambiguous or unsupported overrides are rejected.
|
||
OpenCode must be on PATH so Skillshare can choose the version's schema.
|
||
|
||
A local OpenCode source must already include its built entry (`main`, a string
|
||
root export, or `index.js`) and required runtime dependencies. Skillshare does not
|
||
run build scripts or install dependencies into the source. Registration is not
|
||
proof the module loaded successfully; check OpenCode after reload.
|
||
|
||
Import accepts plain Pi package sources and, on Pi 0.99.2 or later,
|
||
filtered object entries with supported sources and option shapes. Preview lists
|
||
retained field names, never opaque values. Import changes neither native settings
|
||
nor installed files. The original entry is kept in private Skillshare state;
|
||
the local receipt stores only its digest. Sync/update retain the live entry. When
|
||
uninstalling, Skillshare captures its latest rules and options; reinstall restores
|
||
that object before native installation, avoiding a default-enabled window.
|
||
Multiple restores in one Apply recognize only that Apply's own exact writes;
|
||
unrelated settings changes still stop later restores.
|
||
Keep private state with these bindings: a missing, modified, or cross-target record
|
||
blocks restoration. On Windows, new registration directories use protected owner/SYSTEM
|
||
ACLs. Existing directories and records must grant access only to the current user and
|
||
privileged SYSTEM/Administrators principals; unsafe or unverifiable ACLs refuse import
|
||
or restoration. Skillshare does not rewrite existing ACLs: retain the records and repair
|
||
their access protection as the owner before retrying. Unresolved sources, ambiguous precedence, unsupported encoding,
|
||
and local references Pi would normalize remain read-only. Plain OpenCode entries
|
||
can be imported; filtered OpenCode entries are still rejected.
|
||
Imported Pi packages are updated with `pi update SOURCE` in global mode, which
|
||
keeps their settings entry; a project's are updated in Pi, because `pi update`
|
||
also reaches global packages. Imported OpenCode v1 packages are updated in their
|
||
native tool. OpenCode v2 global imports can use its native update command; project imports must be
|
||
updated natively because the v2 update command is global.
|
||
|
||
```bash
|
||
skillshare plugin add ./cursor-plugin --target cursor --no-tui
|
||
skillshare plugin add ./agy-plugin --target agy --no-tui -p
|
||
skillshare plugin add ./pi-package --target pi --no-tui
|
||
skillshare plugin add ./opencode-package --target opencode --no-tui
|
||
skillshare plugin import npm:my-pi-package --from pi --name my-package --no-tui
|
||
```
|
||
|
||
## Refs and explicit entries
|
||
|
||
Advanced options in **Add plugin** accept an optional Git ref and OpenCode entry.
|
||
Leave them empty for the normal guided flow. The terminal wizard accepts the same
|
||
flags; automation can use:
|
||
|
||
```bash
|
||
skillshare plugin discover obra/superpowers --source-ref v6.3.0 --json
|
||
skillshare plugin add owner/repo --source-ref v1.0.0 --target copilot --no-tui
|
||
skillshare plugin add ./package --entry dist/plugin.js --target opencode --no-tui
|
||
skillshare plugin update review --source-ref v1.1.0 --target claude --dry-run --json
|
||
```
|
||
|
||
Shared bindings record `source_ref`; the resolved `commit` stays in the local receipt. Installation uses the
|
||
locally reviewed commit; `check` and `update` resolve the configured ref again, so a branch
|
||
can advance while a commit remains pinned. `--revision` is a preview token, not
|
||
a Git ref. `--entry` is relative to each candidate's package root and must already
|
||
exist; it does not trigger a build or package-manager install.
|
||
|
||
Copilot and Antigravity CLI installs use reviewed local snapshots. Imports have
|
||
no reviewed source for reinstall: after removal, install in the native client and
|
||
sync again. Grok also requires native trust before install/reinstall. Skillshare
|
||
never supplies native trust approval flags.
|
||
|
||
## Compatibility and boundaries
|
||
|
||
- Claude requires its native `.claude-plugin/plugin.json` package.
|
||
- Codex accepts `.codex-plugin/plugin.json` and recognized portable root
|
||
`plugin.json` packages. When a package has both, Codex installs from the portable
|
||
root `plugin.json`, so Skillshare expects that manifest's version, or `1.0.0`
|
||
when it has none.
|
||
A Claude-only package is not silently converted.
|
||
- Sources may contain a marketplace with local plugin entries. Native
|
||
catalogs are merged by plugin name, retaining each target's package path; external
|
||
entries are reported with instructions to add their repository directly or
|
||
install natively and import. Command-based sources are not auto-approved.
|
||
- Complete source snapshots retain plugin scripts, assets, and safe relative
|
||
symlinks (including `AGENTS.md → CLAUDE.md`). Absolute, escaping, dangling,
|
||
cyclic, and `.git`-referencing links and special files are rejected; sources are limited to 20,000 files and 100 MiB.
|
||
- Native installation is not proof of runtime activation. Restart/reload the
|
||
Agent and complete authentication or hook trust in that Agent.
|
||
- Codex runs `codex` from `PATH`. When it is not there, Skillshare tries Homebrew's
|
||
`/opt/homebrew/bin` and `/usr/local/bin`, then the CLI inside the Codex desktop app
|
||
(`ChatGPT.app` or `Codex.app` on macOS, `%LOCALAPPDATA%\OpenAI\Codex\bin` on Windows). Set
|
||
[`SKILLSHARE_CODEX_CLI`](/docs/reference/appendix/environment-variables#skillshare_codex_cli)
|
||
on a machine where Codex is elsewhere. An account with its own `cli` is not searched.
|
||
- Codex native project installation is not provided by this adapter. Sync
|
||
selection still works for global Codex installations.
|
||
- Codex has no update command, so an update adds the plugin again from the
|
||
refreshed snapshot. Adding always enables it, so a plugin disabled in Codex is
|
||
skipped. An imported Codex plugin is updated with
|
||
`codex plugin marketplace upgrade NAME`, which reinstalls every plugin Codex
|
||
installed from that marketplace, as Codex also does when it starts.
|
||
- An update skips a target it cannot reach and says why; the plugin's other
|
||
Agents still update, and a skipped update stays pending for a later sync.
|
||
- Imported plugins retain their original marketplace identity. `check` cannot
|
||
infer release availability for an imported plugin without a source, except an npm
|
||
package in Pi, which it checks against npm. If an
|
||
imported Claude or Codex plugin's native marketplace is gone, sync and update
|
||
skip that target and say so. A new machine requires an explicit local import,
|
||
even if a marketplace with the same name exists. Restore the marketplace in the Agent, or remove
|
||
the target and add the plugin again from its source; Skillshare never moves an
|
||
imported plugin to another source on its own.
|
||
- Skillshare registers one marketplace per managed Claude/Codex plugin, named
|
||
`skillshare-<plugin>-<hash>` (older installs keep `skillshare-<hash>`).
|
||
Removing or excluding the plugin also removes that marketplace, even when the
|
||
plugin is already gone; a failed cleanup is retried on the next sync. An update
|
||
registers it again if it went missing. Same-name registrations at another path
|
||
and imported plugins' marketplaces are left alone; snapshots and native caches
|
||
are retained.
|
||
- These registrations point at this machine's Skillshare state directory, in
|
||
user and project settings alike. Sharing Agent settings through Git or a
|
||
dotfile manager carries paths that do not exist elsewhere; add the plugin from
|
||
its source on each machine instead.
|
||
- Claude also reads a skill folder in its skills directory that has a plugin
|
||
manifest as a plugin named `<name>@skills-dir`, and loads only one plugin per
|
||
name. Adding a Claude plugin with the same name says so in the preview: Claude
|
||
loads the plugin and skips the skill folder until one of them is renamed or
|
||
removed.
|
||
|
||
The native lifecycle is exercised with Claude Code `2.1.276`, Codex CLI
|
||
`0.154.0`, Pi `0.85.1`, and Copilot CLI `1.0.86`. Antigravity CLI
|
||
`1.2.6` was checked with isolated native install/list/remove operations. OpenCode `1.18.31` is used to verify version-aware
|
||
registration; the v2 schema is covered by fixture tests. Cursor and Antigravity
|
||
filesystem lifecycles are tested in isolated directories, without claiming GUI
|
||
runtime activation. Installed command capabilities and inventory schemas are checked at
|
||
runtime; unsupported operations are blocked with an explanation.
|
||
|
||
## Official format references
|
||
|
||
- [Cursor local plugins](https://prod.cursor.com/docs/plugins)
|
||
- [Antigravity desktop plugins](https://www.antigravity.google/docs/plugins)
|
||
- [Antigravity standalone CLI plugins](https://www.antigravity.google/docs/cli/plugins)
|
||
- [Pi packages](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)
|
||
- [OpenCode v1 plugins](https://opencode.ai/docs/plugins/)
|
||
- [OpenCode v2 plugins](https://opencode.ai/v2/docs/plugins)
|
||
|
||
## Shared declarations and local installations {#host-state}
|
||
|
||
`plugins.version: 2` stores intent in global or project configuration: package
|
||
source/ref/plugin/entry, target-specific source overrides, `sync` selection, or
|
||
`imported: true` for native-only targets. A target's effective source is recorded
|
||
explicitly so changing package defaults cannot change another target's distribution.
|
||
|
||
```yaml
|
||
plugins:
|
||
version: 2
|
||
packages:
|
||
router:
|
||
source: https://github.com/acme/router.git
|
||
plugin: router
|
||
bindings:
|
||
pi: {source: https://github.com/acme/router.git, plugin: router}
|
||
omp: {imported: true}
|
||
```
|
||
|
||
Each machine keeps native IDs, reviewed commits/digests/versions, private Pi
|
||
registration references and pending operations under
|
||
`<StateDir>/plugins/<config-path-hash>/state.json` (local format version 1).
|
||
State is keyed by the config's **absolute path**. Moving or renaming a project
|
||
folder or config starts a new state namespace. Previous installs are not
|
||
implicitly tracked or cleaned up; remove them through the old config location
|
||
before moving, or manage/import them explicitly at the new location.
|
||
Keep StateDir machine-local. Sync, update, verification, failure and retry never
|
||
write shared declarations; `update --source-ref` writes only a changed desired ref.
|
||
Reads capture legacy evidence under the local operation lock without changing shared YAML. If another operation holds the lock, the read leaves persistence to that operation or the next unlocked read. Explicit add, import, selection
|
||
and removal edit declarations with changed-byte checks. This does not merge simultaneous
|
||
Syncthing intent edits: concurrent declaration edits can still conflict.
|
||
|
||
On a new machine, sync reviews source content and derives that machine's native
|
||
snapshot paths. Review and commit pinning are per machine: a branch ref resolves
|
||
when that machine installs or updates it, so non-interactive sync on another
|
||
machine can install a newer commit. A ref change also resolves locally. Set
|
||
`source_ref` to a commit SHA to pin all machines to the same revision.
|
||
Local source paths remain user input and must exist on each machine.
|
||
Native-only targets show **Import required on this machine**: install natively,
|
||
then run `plugin import LOCAL-ID --from TARGET --name NAME` on that machine.
|
||
Repeating that import records the local ID without rewriting identical intent.
|
||
Importing into an existing source-managed target records only a local receipt;
|
||
other machines keep their source recipe and working installation. Reimporting
|
||
the same native ID with an existing verified source binding preserves its source
|
||
recipe.
|
||
An explicit Pi `add npm:PACKAGE` shares an npm install recipe and Pi runs its
|
||
install scripts; an npm import shares only native-only intent.
|
||
|
||
Import never fetches a remote source. For a manually written remote recipe without
|
||
`plugin:`, set `plugin:` to the native package name before importing so Skillshare
|
||
can verify its identity offline. Recipes created with `plugin add` already record
|
||
this identity. Local directory recipes can be discovered locally.
|
||
|
||
Old configurations remain readable. Native IDs are adopted only with local
|
||
inventory and, for source installs, owned snapshot evidence. Foreign pending
|
||
operations are ignored. Reads and sync leave old YAML unchanged; the next actual
|
||
declaration edit writes version 2. Unresolved legacy bindings remain private,
|
||
passive hints across that edit. They are retried in their original native context
|
||
and become receipts only after ownership checks, retaining the old intent for
|
||
cleanup even if its shared target was removed. Legacy npm entries cannot prove whether they
|
||
came from add or import, so they remain native-only; explicitly add the npm spec
|
||
again to establish a shared recipe. Upgrade **every writer** of a shared config
|
||
before editing version 2; older binaries cannot safely write this format. On **each
|
||
machine**, run `skillshare plugin list` against the shared config while it is still
|
||
legacy YAML, before any machine makes the first v2 declaration edit. This captures
|
||
that machine's legacy hints locally, even if its native client is temporarily unavailable.
|
||
|
||
A machine returning after a target or source changed retains its previous local
|
||
receipt until cleanup succeeds. Failed cleanup or replacement remains local and
|
||
retryable. Repointing/removing an account preserves its old receipt and requires
|
||
resolving the previous native context before cleanup. Authentication, native
|
||
settings and trust remain in each tool; do not copy them as plugin state.
|
||
|
||
A local import remains installed when its shared source recipe changes. To switch
|
||
to the shared source recipe on this machine, run:
|
||
|
||
```bash
|
||
skillshare plugin unimport NAME --target TARGET --no-tui
|
||
skillshare plugin sync NAME --no-tui
|
||
```
|
||
|
||
`unimport` requires one or more explicit `--target` flags, an existing local import
|
||
receipt, and a shared source recipe for each selected target. It uninstalls the
|
||
imported binding on this machine using the target's removal adapter, then drops
|
||
its local receipt. Shared declarations and other machines' installations stay
|
||
unchanged. The next sync installs the shared source recipe.
|
||
|
||
Uninstalling also removes native-client configuration or login associated with that installation.
|