* 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.
24 KiB
sidebar_position
| sidebar_position |
|---|
| 2 |
Common Errors
Error messages and their solutions.
Config Errors
config not found: run 'skillshare init' first
Cause: No configuration file exists.
Solution:
skillshare init
Add --source if you want a custom path:
skillshare init --source ~/my-skills
failed to load project config: ...
Cause: .skillshare/config.yaml exists but cannot be parsed (malformed YAML, wrong types, etc.). Mutating commands (uninstall, new, enable/disable, check) refuse to proceed in this state so they don't accidentally touch the default .skillshare/skills/ directory when you have a custom sources configuration.
Solution: Fix the YAML and re-run the command. Common issues:
# WRONG — targets must be a list
targets: {}
# RIGHT
targets: []
# WRONG — skills must be a list
skills: my-skill
# RIGHT
skills:
- name: my-skill
source: github.com/org/my-skill
Validate the file with any YAML linter, or temporarily restore from .skillshare/backups/ if you have one.
target "<name>": skills target path X overlaps skills source Y
Cause: Your sources.skills resolves to the same directory as a target's skills path (or one contains the other). For example, configuring sources.skills: .claude/skills together with a claude target — both point to .claude/skills/. Without this guard, sync --force would treat the source as a target directory and delete its contents.
Solution: Choose a source path that does not alias any target. Common safe choices:
# Co-locate with project docs
sources:
skills: ./docs/skills
# Keep under .skillshare/ (default — remove the sources key entirely)
The same check applies to sources.agents against agent target paths.
Target Errors
target add: path does not exist
Cause: The skills directory doesn't exist yet.
Solution:
mkdir -p ~/.myapp/skills
skillshare target add myapp ~/.myapp/skills
target path does not end with 'skills'
Cause: Warning that path doesn't follow convention.
Solution: This is a warning, not an error. Proceed if your path is intentional, or fix it:
skillshare target add myapp ~/.myapp/skills # Preferred
target directory already exists with files
Cause: Target has existing files that might be overwritten.
Solution:
skillshare backup
skillshare sync
Sync Errors
deleting a symlinked target removed source files
Cause: You ran rm -rf on a target in symlink mode.
Solution:
# If git is initialized
cd ~/.config/skillshare/skills
git checkout -- .
# Or restore from backup
skillshare restore <target>
Prevention: Use skillshare target remove instead of manual deletion.
sync keeps showing the same changes
Cause: Two targets sync skills into the same folder with different include or exclude filters, mode, or target_naming (filters and naming don't matter when both targets use symlink mode, which links the whole folder). Each sync redoes the folder the way one target wants and undoes the other's work (adding or removing filtered skills, renaming entries, or switching links and copies), so the folder never settles. sync names them:
! codex and universal sync skills to ~/.agents/skills with different settings, so each sync undoes the other
keep one: skillshare target codex --skills=false
Solution: Let one target write the folder and turn skills off for the other. Its agents, MCP servers and instructions stay managed, and the tool still reads the skills in the shared folder:
skillshare target codex --skills=false --dry-run
skillshare target codex --skills=false
In the dashboard, the Sync page shows the same warning with a button that stops syncing skills for that target. Giving both targets the same filters, mode and target naming also works.
A target from a registered project (<project>@<tool>) has no skills switch of its own, because a project's skills setting covers all its targets. For one, the command drops only that tool from the project, skillshare project edit <root> --target <other tools>, or turns skills off with skillshare project edit <root> --no-skills when it is the project's only target.
sync seems stuck or slow
Cause: Large files in skills directory.
Solution: Add ignore patterns:
# ~/.config/skillshare/config.yaml
ignore:
- "**/.DS_Store"
- "**/.git/**"
- "**/node_modules/**"
no space left on device / ENOSPC during sync
Cause: Something is filling the volume. Check the backup directory first, then your source.
Solution:
df -h ~ # Confirm the volume is full
du -sh ~/.local/share/skillshare/backups # Backup usage
du -sh ~/.config/skillshare/skills # Source usage
If backups are large, prune them — retention runs automatically after each sync, but a directory grown before that can be cleared on demand:
skillshare backup --cleanup --dry-run # Preview
skillshare backup --cleanup
If a volume is pinned at 100%, rm can fail with "Permission denied" until a little space is freed. Free one large file first, then prune.
If the source is large, the artifacts are inside your skills. Backups do not copy them (symlinked skills are skipped), but every target in copy mode does. Move runtime caches, model weights, and browser profiles outside the skill tree, or exclude them with ignore:.
See Backups & Disk Space for how backup scope differs from .gitignore and ignore:.
Extras Errors
These come from single-file extras in prepend or append mode, which keep the source's content in a managed block of the target file. See single-file extras.
the managed block of <source> in <target> was edited by hand
Cause: The text between the block's markers no longer matches what skillshare wrote. Sync does not overwrite it.
Solution: On the dashboard's AGENTS.md tab, use Collect block into to keep the edit in the shared file, or Rewrite block from to drop it (it is kept as a drift backup). For other single-file extras, copy the edit back to the source file, or delete the block from the target, then sync again.
<target> has a damaged managed block
Cause: A block marker was removed or changed by hand, for example the <!-- /skillshare:extra --> end marker was deleted. skillshare cannot tell the block from your own lines, so sync, mode changes and restore all stop for that target.
Solution: Put the missing marker back, or delete the whole block including its begin marker, then sync again.
<target> ends inside an open code fence
Cause: The target file ends inside a Markdown code block that was never closed (a ``` line without its closing pair). A block appended after it would read as code.
Solution: Close the code block in the target file, or use prepend for that target.
<source> has lines that read as skillshare block markers
Cause: The source file has a line that looks like a block marker, such as <!-- /skillshare:extra --> outside a code block. Written into a block, it would end the block early.
Solution: Put the example inside a fenced code block, or change the line.
Git Errors
Could not read from remote repository
Cause: SSH key not set up, or the remote URL is wrong.
Solution:
# Check SSH access
ssh -T git@github.com
# If SSH isn't set up, use HTTPS instead
git -C ~/.config/skillshare/skills remote set-url origin https://github.com/you/my-skills.git
# Or set up SSH keys
ssh-keygen -t ed25519 -C "you@example.com"
# Then add the public key to GitHub → Settings → SSH keys
push: remote has changes
Cause: Remote repository is ahead of local.
Solution:
skillshare pull # Get remote changes first
skillshare push # Now push works
pull: local has uncommitted changes
Cause: You have local changes that haven't been pushed.
Solution:
# Option 1: Push your changes first
skillshare push -m "Local changes"
skillshare pull
# Option 2: Discard local changes
cd ~/.config/skillshare/skills
git checkout -- .
skillshare pull
pull stopped: this machine and the remote both changed ...
Cause: The same file was edited on two machines. pull undid the merge, so the repository is unchanged. Conflicts in .metadata.json alone never cause this; they are resolved automatically.
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
Git had no identity
Cause: Git had no user.name / user.email when skillshare init created the source repo. skillshare wrote a fallback (skillshare@local) into that repo's own config so its commits work. The repo setting outranks git config --global, so setting a global identity later does not replace it.
A repo you created yourself is left alone: skillshare uses the fallback only for its one initial commit.
Solution: set your identity in the repo (the path the message prints; this is the default):
git -C ~/.config/skillshare/skills config user.name "Your Name"
git -C ~/.config/skillshare/skills config user.email "you@example.com"
Or remove the repo setting so your global identity applies: git -C ~/.config/skillshare/skills config --unset user.name (and user.email).
Git root mismatch
Cause: git_root in config.yaml points to a scope directory that has no git repo, but another scope directory does. This happens when you change git_root without relocating the repository — switching scope means "start versioning a different directory", not "move the existing history". See git_root.
Solution: Pick one of the three options the error prints:
# Start a fresh repo at the configured scope (no history)
skillshare init --git-root <scope>
# Move the existing repo over, keeping history
mv <old-scope>/.git <new-scope>/.git
# Or keep using the existing repo: set git_root back in config.yaml
# git_root: <scope-that-has-the-repo>
tracked repository clone is missing
Cause: A tracked repo is declared in .metadata.json, but the clone directory (for example skills/_team-skills/) is missing locally. This often happens after cloning your skillshare source repo on a new machine because tracked repo directories are intentionally listed in the managed .gitignore block.
Solution: Rehydrate the missing tracked repo clones from metadata:
skillshare install
skillshare sync
For project mode:
skillshare install -p
skillshare sync -p
status, check, update --all, and doctor report this state and suggest skillshare install.
nested git repositories must be disabled first
Cause: With git_root: root, a subdirectory (e.g. a tracked skill repo under skills/_org/) has its own .git. Git would upload it as an empty submodule, silently dropping its files, so commit/push abort until each nested repo is disabled.
Solution:
# Disable each reported nested repo (reversible — just rename back to re-enable)
mv ~/.config/skillshare/<dir>/.git ~/.config/skillshare/<dir>/.git.disabled
Or use the one-click disable on the web UI Git Sync page. skillshare also keeps config.yaml out of a root-scope repo automatically (it holds machine-specific paths).
Invalid git_root
Cause: git_root in config.yaml is set to an unrecognized value (e.g. a typo).
Solution: Use one of skills, agents, extras, or root — or leave it empty (defaults to skills).
Install Errors
skill already exists
Cause: A skill with the same name is already installed.
Solution:
# Update the existing skill
skillshare install <source> --update
# Or force overwrite
skillshare install <source> --force
git failed (exit 128): repository not found or authentication required
Cause: The repository URL is wrong, the repo doesn't exist, or authentication is missing.
skillshare now provides actionable error messages for common git failures instead of raw exit codes. The error message includes suggestions:
Error: git failed (exit 128): repository not found or authentication required
If a token was used but rejected:
Error: git failed (exit 128): authentication token was rejected — check permissions and expiry
Solution: See the authentication options below.
Authentication failed / Access denied
Cause: HTTPS credentials are missing, expired, or wrong token type.
Solution — Option 1: Set a token env var:
# GitHub
export GITHUB_TOKEN=ghp_xxxx
# GitLab (must be a Personal Access Token, prefix glpat-)
export GITLAB_TOKEN=glpat-xxxx
# Bitbucket
export BITBUCKET_TOKEN=your_app_password
Windows (PowerShell):
$env:GITLAB_TOKEN = "glpat-xxxx"
# Permanent (survives restarts)
[Environment]::SetEnvironmentVariable("GITLAB_TOKEN", "glpat-xxxx", "User")
Solution — Option 2: Use SSH URL:
skillshare install git@github.com:team/private-skills.git
skillshare install git@gitlab.com:team/skills.git
skillshare install git@bitbucket.org:team/skills.git
Solution — Option 3: Git credential helper:
gh auth login # GitHub CLI
git credential approve # or platform-specific credential manager
Required token permissions:
| Platform | Token type | Scopes / Permissions |
|---|---|---|
| GitHub | Personal Access Token (ghp_) |
repo (private repos), none (public) |
| GitLab | Personal Access Token (glpat-) |
read_repository + write_repository |
| Bitbucket | Repository Access Token | Read + Write |
| Bitbucket | App Password + BITBUCKET_USERNAME |
Repositories: Read + Write |
:::warning GitLab token types
Only Personal Access Token (glpat-) works for git operations. Feed Tokens (glft-) do not have git access.
:::
See Environment Variables and Private Repositories.
SSL certificate problem / certificate verification failed
Cause: The Git server uses a self-signed certificate or an internal CA that your system doesn't trust. Common with self-hosted GitLab, Gitea, or Gogs instances.
Solution — Option 1: Custom CA bundle (recommended):
export GIT_SSL_CAINFO=/path/to/company-ca-bundle.crt
skillshare install https://gitlab.internal.company.com/team/skills.git --track
Solution — Option 2: Use SSH instead (avoids SSL entirely):
skillshare install git@gitlab.internal.company.com:team/skills.git --track
Solution — Option 3: Disable SSL verification (not recommended):
GIT_SSL_NO_VERIFY=true skillshare install https://gitlab.internal.company.com/team/skills.git --track
:::warning Disabling SSL verification is a security risk. Prefer Option 1 or 2. :::
See Environment Variables — Git SSL / TLS.
invalid skill: SKILL.md not found
Cause: The source doesn't have a valid SKILL.md file.
Solution: Check the source path is correct and points to a skill directory.
"<path>" is in git submodule "<submodule>" ..., and skillshare does not fetch submodules
Cause: The path you asked for is a git submodule in the repository, or sits inside one. skillshare does not fetch submodules, so the directory would be empty.
Solution: Install from the upstream repository named in the error. If you maintain the hub, copy the skill files into it instead of mounting them as a submodule.
Update Errors
pull stopped: this machine and the remote both changed ... (tracked repository)
Cause: A tracked repository has local commits that conflict with the remote. update merges diverged history, but a conflicting file stops it and the merge is undone.
Solution:
# Force update (replaces local with remote)
skillshare update --force
# Or manually resolve
cd ~/.config/skillshare/skills/_repo-name
git pull --no-rebase
# Edit the conflicted files, then
git add . && git commit --no-edit
:::tip
skillshare update and skillshare install now show actionable error messages for git failures (authentication, SSL, divergent branches) instead of raw exit codes.
:::
Audit Errors
security audit failed — critical threats detected
Cause: The skill contains patterns matching critical security threats (prompt injection, data exfiltration, credential access).
Solution:
# Review the findings
skillshare audit <skill-name>
# If you trust the source, force install
skillshare install <source> --force
audit HIGH: Hidden zero-width Unicode characters detected
Cause: The skill contains invisible Unicode characters, which may be a copy-paste artifact or intentional obfuscation.
Solution: Open the file in an editor that shows hidden characters and remove them, or force install if you trust the source.
Upgrade Errors
GitHub API rate limit exceeded
Cause: Too many unauthenticated API requests.
Solution:
# Option 1: Set a GitHub token (recommended)
export GITHUB_TOKEN=ghp_your_token_here
skillshare upgrade
# Option 2: Force upgrade
skillshare upgrade --cli --force
Create a token at: https://github.com/settings/tokens (no scopes needed for public repos)
Skill Errors
skill not appearing in AI CLI
Causes:
- Skill not synced
- Invalid SKILL.md format
- AI CLI caching
Solutions:
# 1. Sync
skillshare sync
# 2. Check format
skillshare doctor
# 3. Restart AI CLI
Antigravity does not load synced skills
Cause: The Antigravity app's skill scanner only discovers real directories — it skips symlinks. skillshare's default merge mode creates one symlink per skill (an NTFS junction on Windows), so none of them are picked up. On Windows this surfaces as an Incorrect function error; on macOS and Linux the skills are silently absent.
This is an Antigravity-side limitation, not a skillshare bug. It applies to the antigravity target (the app, ~/.gemini/config/skills); the standalone agy CLI is a separate antigravity-cli target reading ~/.gemini/antigravity-cli/skills. Two workarounds:
Option 1 — switch the target to copy mode
skillshare target antigravity --mode copy
skillshare sync --force
Real directories are written instead of symlinks. Trade-off: re-run skillshare sync after editing a source skill.
Option 2 — point Antigravity at your source directory
In Antigravity: Settings → Customizations → Skill Custom Paths → "+ Add", then enter the absolute path to your skillshare source (e.g. /Users/you/.config/skillshare/skills). The ~ shorthand is not expanded, so a full path is required.
Either way, restart Antigravity to reload skills.
skill name 'X' is defined in multiple places
Cause: Multiple skills have the same name field and land on the same target.
Solution: Rename one in SKILL.md or use include/exclude filters to route them to different targets:
# Option 1: Namespace in SKILL.md
name: team-a-skill-name
# Option 2: Route with filters (global config)
targets:
codex:
path: ~/.codex/skills
include: [_team-a__*]
claude:
path: ~/.claude/skills
include: [_team-b__*]
# Option 2: Route with filters (project config)
targets:
- name: claude
exclude: [codex-*]
- name: codex
include: [codex-*]
:::tip If filters already isolate the duplicates, sync prints nothing about them — no action needed. See Target Filters for full syntax. :::
Agent Errors
Warning: No agents folder: <targets>
Cause: You ran skillshare sync (or skillshare sync agents) and one or more configured targets don't define an agents directory. Only Claude, Cursor, Augment, and OpenCode have built-in agent paths; other targets are silently skipped.
Solutions:
- Ignore the warning if those targets don't need agents.
- Add an
agents:sub-key to the target inconfig.yamlto enable agent sync for it:
targets:
myapp:
path: ~/myapp/skills
agents:
path: ~/myapp/agents
Then re-run skillshare sync agents.
backup is not supported in project mode (except for agents)
Cause: You ran skillshare backup -p (or skillshare backup -p <target>) without the agents filter. In project mode, only agent backups are supported — skill backups are global-only.
Solution: Add the agents positional argument or use --all:
skillshare backup -p agents # Project agent targets
skillshare backup -p agents claude # Specific target
skillshare backup -p --all # Same as above (narrows to agents)
The same rule applies to restore: restore is not supported in project mode (except for agents).
agent name 'X' has invalid characters
Cause: An agent filename or name: frontmatter field contains characters outside the allowed set.
Solution: Agent names must use only a-z, 0-9, _, -, .. Rename the file (and update its name: field to match) so they share the same canonical name.
.agentignore patterns not taking effect
Causes:
- The file is in the wrong location. It must live at the agents source root:
~/.config/skillshare/agents/.agentignore(global) or.skillshare/agents/.agentignore(project). - Your pattern matches a different segment than you expect — the file uses gitignore syntax.
Solution: Confirm the file path with skillshare doctor and re-check the pattern. Agents are matched by basename (without .md), so draft-* matches draft-experiment.md. Use skillshare disable <agent> --kind agent to let the CLI write the entry for you.
Plugin Errors
<agent> CLI is not installed or not on PATH
Cause: Plugin commands run the Agent's native CLI (claude, codex, and so on) on the machine running Skillshare, and that CLI was not found. A scheduled job or a dashboard started from a service often has a shorter PATH than your terminal.
Solutions:
- Install the Agent's CLI on that machine.
- If it is installed, add its directory to the
PATHof whatever starts Skillshare, such as the scheduled job's environment. - For an account target, you can set
clito the executable's absolute path instead.
Codex CLI not found on the machine running Skillshare
Cause: Skillshare looked for the Codex CLI on PATH, in the Homebrew folders, and inside the Codex desktop app, and found none. The message lists every place it looked.
Solutions:
- Install the Codex app or the Codex CLI on that machine.
- If Codex is somewhere else, set
SKILLSHARE_CODEX_CLIto its path in the environment that starts Skillshare, such as the scheduled job. It stays on that machine, so a config shared with another OS is not affected.
The native marketplace X is gone
Cause: This machine has a local import receipt, but its native marketplace is no longer registered. Skillshare skips the operation; a receipt is not a reviewed reinstall source.
Solutions:
- Restore the marketplace and install or update the plugin in the native client. Import its local ID into the declared package if it needs rebinding.
- Or remove that Agent from the plugin and add the plugin again from its source. See Cross-Machine Sync — Plugins.
A second machine without a receipt instead shows Import required on this machine and skips that target. Install natively there, then import its local ID with the declared package name.
Binary Errors
integration tests cannot find the binary
Cause: Binary not built or wrong path.
Solution:
go build -o bin/skillshare ./cmd/skillshare
# Or set
export SKILLSHARE_TEST_BINARY=/path/to/skillshare
Still Having Issues?
See Troubleshooting Workflow for a systematic debugging approach.