* 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.
13 KiB
sidebar_position
| sidebar_position |
|---|
| 4 |
Cross-Machine Sync
Sync your skills across multiple computers using git.
Overview
flowchart LR
subgraph A["Machine A (Work)"]
A_TARGETS["`Claude
Cursor`"]
A_SRC["Source (git)"]
A_TARGETS --- A_SRC
end
REMOTE["GitHub Remote"]
subgraph B["Machine B (Home)"]
B_SRC["Source (git)"]
B_TARGETS["`Claude
Codex`"]
B_SRC --- B_TARGETS
end
A_SRC -->|push| REMOTE
REMOTE -->|pull| B_SRC
First Machine Setup
Interactive (guided prompts)
skillshare init --remote git@github.com:you/my-skills.git
Non-interactive (no prompts)
# Remote already has your skills (or start fresh source)
skillshare init --remote git@github.com:you/my-skills.git --no-copy --all-targets --no-skill
# First machine with existing Claude skills: import during init
skillshare init --remote git@github.com:you/my-skills.git --copy-from claude --all-targets --no-skill
This:
- Creates source directory
- Initializes git with initial commit
- Adds remote
- Auto-detects and configures targets
Optional later (only if you install additional AI CLIs after setup):
skillshare init --discover
Then push your skills:
skillshare push
:::tip Already initialized? Add a remote to an existing setup:
skillshare init --remote git@github.com:you/my-skills.git
This works even after initial setup — it just adds the remote. :::
Second Machine Setup
Run skillshare init, choose Connect my existing skillshare repo, and paste the repo URL:
Or pass the URL directly:
skillshare init --remote git@github.com:you/my-skills.git
Init checks the repo before writing anything, then pulls it down. No manual git clone needed.
:::info What happens behind the scenes
- Clones the repo into a temporary folder to count its skills and detect its layout: a whole-folder repo pushed with
--git-root root, or skills in askills/folder - Skills on this machine with the same name as one in the repo use the repo version; skills only on this machine are kept and added on the next
skillshare push - After you confirm: creates the source, initializes git, adds the remote, resets to the remote branch, and sets up tracking
- Configures the detected local targets and offers a first sync :::
If you prefer manual control:
# Clone directly, then init with existing source
git clone git@github.com:you/my-skills.git ~/.config/skillshare/skills
skillshare init --source ~/.config/skillshare/skills
skillshare sync
Daily Workflow
Machine A: Make changes and push
# Edit skills (changes visible immediately via symlinks)
$EDITOR ~/.config/skillshare/skills/my-skill/SKILL.md
# Optional: create a local checkpoint without pushing
skillshare commit -m "Update my-skill"
# Push to remote when ready to share
skillshare push -m "Update my-skill"
Machine B: Pull and sync
skillshare pull
That's it. pull automatically runs sync after pulling. It syncs what the git root scope holds: skills by default, agents or extras with those scopes, and all three with git_root: root. Plugins, MCP servers and hooks need the extra steps below.
Both ways in one command
When you edit skills on more than one machine, run this instead of push and pull:
skillshare push --pull -m "Update my-skill"
It commits your changes, merges what the other machines pushed, pushes, and syncs targets. A conflict stops it before anything is pushed. See Push and Pull Together.
Plugins, MCP and Hooks
push and pull version the files in the git root directory. Plugins, hooks and MCP servers are settings in config.yaml, and config.yaml is never part of that repository: the default skills scope keeps it outside the repo, and the root scope ignores it. Each machine keeps its own config.yaml, with its own targets and paths.
| Resource | Stored in | Moves with push / pull |
|---|---|---|
| Skills | Skills source | Yes |
| Agents | Agents source | With git_root: agents or root |
| Extras | Extras source | With git_root: extras or root |
| MCP servers | config.yaml, or the file named by sources.mcp |
Only when that file is inside the repository |
| Plugins | plugins: in config.yaml |
No |
| Hooks | hooks: in config.yaml |
No |
After pulling on another machine, apply the rest yourself:
skillshare pull
skillshare sync --all # adds agents, extras, MCP and hooks
skillshare sync plugins --no-tui # plugins are never part of --all
MCP servers
Keep the server definitions in a separate file inside the repository. With git_root: root, the repository is the directory that holds config.yaml (~/.config/skillshare, or %AppData%\skillshare on Windows), so a relative sources.mcp path is committed while config.yaml stays local:
sources:
mcp: ./mcp.yaml
mcp:
targets: [claude, codex]
mcp.targets stays in config.yaml, so each machine chooses its own receiving clients. Set sources.mcp on every machine. To move existing servers out of config.yaml, see Split MCP into its own file. To switch an existing setup to the root scope, see git_root.
Skillshare stores credentials as fromEnv references, never as values. Set those environment variables on each machine where the Agent can read them.
Plugins
Share the plugins: section of the config to share version 2 declarations: sources,
refs and selected targets. Keep StateDir local on every machine. Alternatively,
use Plugins → Share to copy an add command into a separately managed config.
On a new machine, run skillshare plugin sync to review and install source-managed
plugins using local snapshot paths. Review and commit pinning are per machine:
a shared branch ref is resolved when that machine installs or updates it. A
non-interactive sync may install a newer commit than another machine reviewed.
Use a commit SHA as source_ref when every machine must use the same revision.
Local source paths must exist on each machine.
Native-only declarations show Import required on this machine and sync skips
them. Install in the native client, then run
skillshare plugin import LOCAL-ID --from TARGET --name NAME on each machine.
Importing into an existing source declaration only records a local receipt;
other machines keep their source recipe and installation.
Before the first v2 edit, upgrade every writer and run skillshare plugin list
on each machine while the shared YAML is still legacy to save its local
migration hints. See plugin state and migration.
sync installs missing plugins, reconciles changed refs and retries local cleanup.
Use skillshare plugin check and skillshare plugin update for new releases on an
unchanged ref.
Hooks
Hooks have no separate file. Copy the hooks: section of config.yaml to the other machine, then run skillshare sync hooks.
What stays on each machine
- The native CLIs that install plugins (
claude,codex, and so on) must be installed and onPATHwhere Skillshare runs. A scheduled job often has a shorterPATHthan your terminal. Codex is also found inside the Codex desktop app and in Homebrew's folders; setSKILLSHARE_CODEX_CLIon a machine where it is elsewhere. - Sign-ins, OAuth tokens, native trust prompts and enabled/disabled state stay in each Agent.
- The values of environment variables that MCP servers reference.
Commands
Commit
Create a local checkpoint without pushing:
skillshare commit # Default message
skillshare commit -m "Add pdf" # Custom message
skillshare commit --dry-run # Preview
What happens:
git add -A
git commit -m "Add pdf"
commit does not require a remote and never pushes.
Push
Commit and push local changes:
skillshare push # Auto-generated message
skillshare push -m "Add pdf" # Custom message
What happens:
git add -A
git commit -m "Add pdf"
git push # auto-sets upstream on first push
Pull
Pull remote changes and sync:
skillshare pull
What happens:
git pull # merges when both machines committed; fetch + merge or reset on first pull
skillshare sync
Conflict Handling
Pull fails (local uncommitted changes)
If you want to keep the local changes but are not ready to push them yet, commit them locally first:
skillshare commit -m "Save local changes"
skillshare pull
Push fails (remote ahead)
$ skillshare push
Push failed
Remote may have newer changes
Run: skillshare pull
Then: skillshare push
Solution:
skillshare pull
skillshare push
Pull still fails with local uncommitted changes
$ skillshare pull
Local changes detected
Run: skillshare push
Or: cd ~/.config/skillshare/skills && git stash
Solution:
# Option 1: Commit locally first
skillshare commit -m "Local changes"
skillshare pull
# Option 2: Push your changes first
skillshare push -m "Local changes"
skillshare pull
# Option 3: Stash changes temporarily
cd ~/.config/skillshare/skills
git stash
skillshare pull
git stash pop
Merge conflicts
When both machines committed, pull merges them. Conflicts in .metadata.json resolve automatically. A conflict in any other file stops the pull, undoes the merge, and names the files:
$ skillshare pull
pull stopped: this machine and the remote both changed my-skill/SKILL.md; the merge was undone, resolve it with git in ~/.config/skillshare/skills
Solution:
cd ~/.config/skillshare/skills
git pull --no-rebase # Redo the merge and keep the conflicts
# Edit the conflicted files
git add .
git commit --no-edit
skillshare push
skillshare sync
Check Status
skillshare status
Shows:
- Git status (clean, ahead, behind)
- Remote configuration
- Sync status
Private Repository
Use SSH URL for private repos:
skillshare init --remote git@github.com:you/private-skills.git
Tips
Use SSH keys
Set up SSH keys to avoid password prompts:
ssh-keygen -t ed25519 -C "your@email.com"
# Add public key to GitHub
Portable paths for dotfiles
If you share config.yaml via dotfiles, enable preserve_tilde_on_save to keep paths as ~/... instead of /home/alice/...:
preserve_tilde_on_save: true
This prevents noisy diffs when the same config is used across machines with different usernames or OS-specific home prefixes. See Configuration — preserve_tilde_on_save.
Multiple remotes
Add backup remotes:
cd ~/.config/skillshare/skills
git remote add backup git@gitlab.com:you/skills-backup.git
git push backup main
Sync on shell startup
Add to ~/.bashrc or ~/.zshrc:
# Sync skillshare on terminal open (if remote configured)
skillshare pull 2>/dev/null
Alternative: Install from Config
If you don't want to set up a git remote, config.yaml doubles as a portable skill manifest. Every install / uninstall auto-updates the skills: section, and skillshare install (no args) reinstalls everything listed:
# Machine A — config.yaml records what you installed
skillshare install anthropics/skills -s pdf
# config.yaml now has: skills: [{name: pdf, source: "..."}]
# Machine B — copy config.yaml, then:
skillshare install # Installs all listed skills
skillshare sync
When to use which
push / pull |
install (no args) |
|
|---|---|---|
| What's synced | Actual skill files (full content) | Source URLs only — re-downloads on install |
| Local/hand-written skills | Included | Not included (no source URL) |
| Setup required | Git remote on source dir | Just config.yaml |
| Project mode | Global only | Works with -p (.skillshare/config.yaml) |
| Maintenance | Manual push after changes |
Auto-reconciled on install/uninstall |
Recommendation: Use push/pull for personal cross-machine sync. Use install from config for team onboarding and project setup.
See Also
- push — Push to remote
- pull — Pull from remote
- install — Install from config
- Organization-Wide Skills — Team sharing
- init — Init with
--remote
