Files
skillshare/website/docs/reference/commands/plugin.md
T
Willie ccc0fbdf74 feat(pi): manage individual extensions per target (#350)
* feat(pi): manage individual extensions per target

Keep package lifecycle in Plugins while letting global, account, and project Pi targets configure individual extensions with reviewed, lossless changes. Project overrides save only project settings and never grant trust.

Bind edits to native version contracts, settings snapshots, source ownership, and discovery; preserve unrelated resources and enforce renewable native locks, stale rejection, and backups. Verify Pi 0.99.2 and 1.0.0 without running extension factories.

Simplify configured-state UI and distinguish Skillshare-managed packages from native tool registrations, with localized guidance and regression coverage. Closes #342.

* fix(pi): address project extensions review findings

Keep exact project delta rules visible when their extension files are missing so users can remove stale rules without changing global settings or trust.

Show the project Extensions tab only when its generated Pi target resolves. Cover missing and agents-only projects, absent targets, and another project target with regression tests.

* fix(pi): recognize official Windows account launchers

Accept pi.cmd and pi.exe account launcher names on Windows, including case-insensitive and native Windows paths, before probing the existing exact-version gate. Preserve POSIX behavior and never probe unrecognized forks or stacked launcher suffixes.

Add platform-name and account-gate regressions covering verified, unsupported, and missing CLI versions. Focused race tests, make check, and Windows amd64/arm64 test cross-compilation pass; real Windows runtime remains unverified because the UTM guest is stopped.

* fix(pi): align rule removal and backup descriptions

Offer Remove rule only for owned exact +/- rules, not project delta globs that the apply path cannot remove. Keep supported glob rows switchable and cover delta and deltaOnly forms with RED/GREEN regressions.

Describe retained artifacts as extension-list and file-hash records rather than complete settings backups in English, all four website translations, and the implementation report.

* fix(pi): discard records for aborted extension applies

Require a validated preview and owned native lock before recording an extension change. Discard only the newly created record if final revalidation, lock ownership, or the atomic settings write fails; retain successful history and propagate cleanup errors with the original failure.

Keep discovery revalidation after record I/O so cleanup does not weaken the write-boundary guard. Cover global and new/existing project settings with nine RED/GREEN regressions, including injected commit failures. Align English and translated docs with the retained-record lifecycle.

* fix(pi): retain anonymous global packages in projects

Keep ordered anonymous registrations separate from the proven-identity map so unsupported query-bearing sources remain visible as redacted read-only packages, rather than being dropped or associated with a project override.

Preserve first-global-entry precedence for known identities. Add RED/GREEN coverage for string and object registrations, query/userinfo redaction, project entries, zero-write refusal, ordering, and continued editing of known packages.

* fix(pi): deduplicate only proven project identities

Exclude unresolved identities from project duplicate tracking. Preserve each anonymous registration as sourceUnknown instead of pretending unrelated query-bearing URLs are the same package.

Cover mixed string/object anonymous project sources, redaction and zero-write refusals, retained anonymous globals, and last-project-entry precedence for known packages. Verify known project entries remain editable.

* fix(pi): guard unresolved package precedence

An unresolved earlier global registration may own a later known package, and an unresolved later project registration may supersede an earlier known entry. Keep those potentially shadowed entries and inherited deltas Unknown/read-only instead of offering edits to ignored registrations. Do not infer identities by dropping credentials or queries.

Cover both ordering directions for global, inherited, project-owned, and delta views with RED/GREEN tests. Execute native query identity and dedupe evidence on Pi 0.99.2 and 1.0.0 through core and CLI-bundle contracts, now 28 scenarios and 87 assertions each. Align docs and evidence while retaining independent anonymous entries.

* fix(pi): propagate unreadable source ambiguity

Treat badSource entries as unresolved instead of letting an unreadable source expose editable later global registrations. Preserve the same uncertainty in inherited globals and before unreadable later project entries.

Add twelve global/inherited/project regressions for null, empty, whitespace and invalid UTF-8 sources. Native core and CLI-bundle evidence confirms invalid UTF-8 can decode to and own the same identity as a later valid source on both supported Pi versions; the executed contracts now pass 29 scenarios and 90 assertions.

* feat(pi): preserve filtered imports and reclaim stale locks

Adopt native object registrations without changing their configured resources. Keep lossless entries in scoped private state, retain current rules across lifecycle operations, restore filters before native installation, and preserve pending retries after failures.

Reclaim only unchanged empty directories after the native stale threshold, retaining renewed, replaced, nonempty and non-directory locks. Verify exact supported Pi contracts and keep unsupported cases read-only.

* docs(pi): record filtered import verification after branch sync

Document the current merged UI test count and repeated checks while retaining the native and visual verification limitations.

* docs(pi): clarify stale acquisition exception

Keep the lock safety summary consistent with the approved acquisition policy while preserving strict ownership for renewal and release.

* fix(pi): keep legacy npm fallback installations unknown

A missing user-scoped managed npm root cannot prove a package is absent because native Pi may use a legacy global npm or pnpm root. Keep it read-only without probing host-global state, while retaining missing-state behavior for project npm packages.

* fix(pi): preserve project precedence and batch restore ownership

Retain empty winning overrides when deleting them could expose older resource filters. Advance filtered restore batches only to exact writes made by the same Apply, while rejecting external changes and retaining failed native retries. Match Pi strict-false autoload semantics instead of treating null as a delta.
2026-10-03 20:47:20 +08:00

23 KiB

sidebar_position
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.

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 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
import [NATIVE-ID] Adopt an existing installation without reinstalling or enabling it
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; never update
update [NAME] 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. 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, opencode, or the name of another account of an Agent; 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, OpenCode, or another account of an Agent
--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, 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
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 | Update natively to preserve enablement | | 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

A target declared as another account of an Agent is a plugin target too, for claude, codex and pi. Skillshare runs that Agent's own CLI against the account's config directory, through CLAUDE_CONFIG_DIR, CODEX_HOME or PI_CODING_AGENT_DIR:

targets:
  claude-work:
    agent: claude
    config_dir: ~/.claude-work
skillshare plugin add owner/repo --target claude-work
skillshare plugin import demo@market --from claude-work

An account with cli 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.

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.

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. A switch writes one exact +path or -path rule into that entry's extensions list. Remove rule 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. Installing and removing packages stays in plugin.

Skillshare reads packages without running them, so the tab shows what the settings select (the Configured column), 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 a version Skillshare has verified (currently 0.99.2 and 1.0.0, each checked against Pi itself) and strict JSON settings; any other 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, 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 verified Pi 0.99.2/1.0.0, 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; shared config 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. 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.

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:

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

Bindings record source_ref and the resolved commit. Installation uses the 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. A Claude-only package is not silently converted.
  • Sources may contain a marketplace with local plugin entries. External catalog catalogs are merged by plugin name/path. Conflicting paths are rejected; 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 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. If an imported Claude or Codex plugin's native marketplace is gone, sync and update skip that target and say so. This also happens on another machine where that marketplace was never added. 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