Files
3217d44881 fix(reconcile): keep tracked repo declarations this machine has not cloned (#880)
* test(install): reproduce loss of pulled tracked records

Exercise the two-machine push and pull sequence and reconciliation states so
missing tracked clones cannot silently erase shared install intent.

* fix(reconcile): preserve tracked records missing local clones

Pull transfers tracked repository metadata but not ignored clones. Keep the
missing records during global reconciliation so another install and push cannot
erase shared intent or accepted audit findings on every machine.

* test(reconcile): isolate tracked record fixtures

Use the shared sandbox fixture for both reconciliation tests so their home
and configuration paths remain isolated from the invoking environment.

* fix(reconcile): retain all sourced tracked declarations

Legacy tracked members and unfollowed source links can hide declarations
from the local walk. Preserve sourced tracked records regardless of their
path so unrelated installs cannot erase them or their audit acceptances.

Document restoring a missing checkout before uninstalling it and cover
migration, link collisions, aliases, and explicit removal.

* test(reconcile): drop fixtures existing tests already pin

The tracked-record unit test also seeded a missing plain record and a
live plain record. TestReconcileGlobalSkills_PrunesStaleEntries already
pins both outcomes: a sourced plain record whose folder is gone is
pruned, and one on disk survives. The tracked record with no source
still catches a fix that keeps everything or skips the prune.

The two-machine test passed HOME and SKILLSHARE_CONFIG to RunCLIEnv,
which already sets both from the sandbox for each child process.
Separate homes, XDG paths, client overrides and git config remain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(reconcile): retain tracked entry for unavailable link

Expect sourced tracked declarations to survive reconciliation with either
source-link policy, so the test matches the cross-machine retention contract.

* fix(config): prune legacy tracked members

Retain only sourced tracked repository declarations during reconciliation.
Migrated member records are not restorable as repositories and retaining them
would leave permanent misleading install requests and audit acceptances.

* fix(reconcile): preserve tracked intent across followed links

A source link can exist before a tracked repository declaration is pulled. Preserve that declaration when the linked folder is not a checkout so later reconciliation does not discard its record and audit acceptances.

* test(reconcile): cover grouped followed declarations

A followed group can contain the path of a pulled legacy repository declaration, which must retain its tracked intent while its key migrates.

* fix(test): scope collision fixture runner correctly

Keep the isolated CLI runner in the collision subtest that uses it so the integration test package can compile.

* docs(manifest): clarify tracked checkout recovery

A retained declaration cannot restore a checkout while another folder or source link occupies its destination, and restoration requires a reachable source. State those prerequisites in each manifest translation.

* fix(config): prune members under recorded repositories

A migrated underscore-named member can otherwise survive a missing checkout as a repository declaration. Check recorded ancestor paths while preserving ambiguous grouped declarations and unrelated aliases.

* docs(manifest): restore fresh-clone project guidance

Explain that project declarations without local install records remain available so teammates can install them after cloning.

* refactor(reconcile): drop the tracked-intent walker policy

Restore baseline normalization for present paths while retaining absent
repository declarations through the shared metadata predicate. Isolate the
reconcile fixtures without building a CLI and share native-client overrides
without changing the original two-machine record and audit regression.

Validation: gofmt, git diff --check and context-router check only.
Runtime, builds and tests were not executed under the source-only gate.

* fix: forget linked checkout records and declarations without checkouts

Extend the metadata and uninstall owners to remove a declaration without
reading or moving its occupant, contacting its source, or changing trash
and gitignore. A failed metadata save makes every metadata-only result fail.

Clean up global unlink records in CLI and API, preserve existing-path name
precedence, report record-only results truthfully, and list declarations in
the dashboard API with noCheckout. Keep project removal behavior unchanged.
Remove the obsolete grouped-link walker-policy assertion while preserving
grouped absent declarations and the original record/audit A/B regression.

Validation: source-only five-pass review, gofmt, git diff --check and the
context-router check. No runtime, builds, tests or frontend tooling ran.
Stop at commit 15 for the mandatory Luna checkpoint before UI and docs work.

* fix(server): reload metadata before removing declarations

Preserve CLI records and audit acceptances written while the dashboard is open. Resolve new declarations from disk and refuse stale-cache saves after a reload failure, retaining unlink success when its link already moved.

* feat(dashboard): remove a tracked repository record without a checkout

Show declaration-only rows without checkout actions or status promises. Reuse Uninstall with record-specific confirmation and feedback, keep real-checkout force handling, and refresh the missing-entry list after repository removal or unlink.

* docs: explain kept declarations and how to remove them

Document direct global declaration removal and optional restore in English and all four translations, including occupied paths and normalization after reconcile. Keep built-in guidance accurate and use the existing API removal result for dashboard success feedback after concurrent CLI changes.

* fix(dashboard): confirm restored checkouts after forceable refusals

A tracked declaration can be restored through the CLI while its dashboard
row still says there is no checkout. Treat a forceable uninstall refusal
as evidence of the current checkout and promote the existing confirmation
to its dirty or unreadable-status warning before allowing explicit force.

Author stale-row regressions for both forceable codes before the source
repair, and retain nonforceable failure and actual-result success feedback.
Validation: five serial source review passes, git diff --check, and the
context-router check. Tests, builds, runtime and frontend tooling were not
run under the source-only gate.

* test(server): persist overview declarations before routed request

The overview fixture added declarations only to the in-memory skills store,
which the real request's config reload replaced with on-disk metadata. The
hosted unit, offline, and Nix jobs consequently returned no tracked rows.

Save the complete fixture through MetadataStore before serving the request
and fail setup on a save error. Keep the middleware, assertions, and
production behavior unchanged.

* fix(server): prefer exact declarations before checkout shorthand

Removing a missing _team declaration from the dashboard could resolve the
different org/_team checkout by basename and trash it instead.

Reload metadata before declaration lookup, give exact declarations priority,
and preserve checkout resolution before non-exact declaration fallback.
Add routed absent/occupied regressions and checkout precedence guards, and
persist existing checkout fixtures so the metadata reload keeps their state.

Validation: gofmt, git diff --check, and context-router check passed.
Tests were authored but not run under the source-only fleet restriction.

* fix: preserve removal intent and report partial failures

Bind dashboard record-only removal to its canonical declaration and refuse
restored checkouts before checkout resolution or force. Refresh the row and
require another confirmation before moving a restored checkout to trash.

Keep unresolved uninstall inputs and their reasons in JSON failed results,
including all-invalid requests, partial successes and dry runs. Report unlink
metadata cleanup failures as partial results, refresh completed unlinks and
show localized warnings. Keep CLI and dashboard guidance aligned.

Regression tests were authored before source changes and remain unrun under
the source-only task restriction. Static formatting, diff and router checks
passed; no build, product runtime, frontend tooling or test suite was run.

* fix(unlink): log partial metadata cleanup failures

Write the unlink result after global metadata cleanup so load and save
failures retain their diagnostic and report partial success. Preserve the
successful link removal, warning, target and exit policy, and the existing
link, project unlink and native removal failure behavior.

Add the corrupt-metadata regression before the fix; leave it unrun under
the source-only authorization. Formatting, diff and context-router checks
pass; runtime verification remains with the coordinator.

* fix(unlink): forget records below the removed link name

Reconcile can normalize a followed link's record to untracked, and linked
collections can retain nested repository declarations. Clean the removed
namespace through the existing metadata path owner in both unlink callers,
including audit acceptances, while keeping declaration uninstall strict.

Author CLI and route regressions before the source fix for normalized and
nested records, sibling preservation, and subsequent bare install. Tests
remain unrun under the source-only task restriction; static checks only.

* fix(uninstall): refuse a restored checkout at execution

A declaration selected while absent can become a checkout before removal
runs. Recheck the resolved source-relative name in the shared metadata-only
execution owner and refuse before touching metadata, regardless of force.

Reuse the existing dashboard conflict response and refresh/reselection flow
for this refusal, preserving the earlier record-only intent guard. CLI
results already carry shared execution failures through text and JSON.

Author restoration, force, absent/occupied control and client boundary
regressions before production edits. Correct the unlink fixture name and
response-key assertion found in serial static review. All tests remain
unrun under the source-only restriction; formatting/diff/router checks pass.

* refactor(server): consolidate repository uninstall result handling

Resolve a declaration or checkout to one item and canonical name before
using the existing uninstall, conflict, log and success response tail.
Keep metadata-only removal unforced, preserve its error and cache recovery
behavior, and report movedToTrash from the selected item.

Preserve exact declaration precedence, record-only checkout refusals,
ordinary checkout errors and project behavior without changing tests.
Five serial source review passes, gofmt, diff checks and the context-router
check completed. Tests and builds remain unrun under the source-only brief.

* fix(unlink): preserve independent records and trash undo metadata

Limit unlink's legacy group matching to members so a retained declaration
such as team/_repo survives unlinking _team. Share snapshot and removal
matching while keeping generic uninstall's legacy contract unchanged.

Save the exact removed records, audit acceptances and target overrides
through uninstall's existing trash sidecar owner before pruning metadata.
Keep metadata on sidecar failure and preserve completed-unlink warnings,
fresh reloads, cache refresh and project-mode behavior.

Author owner, CLI and API regressions for namespace collisions, undo,
partial failures and project/empty controls. Source-only verification:
gofmt, diff check and context-router check passed; runtime tests, builds,
frontend checks and final make check remain unrun for root-owned gates.

* fix(install): preserve independent tracked declarations

Limit declaration-only cleanup to the precise namespace and legacy members already used by unlink. Keep independently installed prefixed repositories, their audit acceptances, and overrides when forgetting a missing checkout.

* fix(cli): explain missing tracked repository recovery by mode

Offer global record removal when restoring an unreachable source is unwanted. Keep project recovery scoped to install -p, share the hint with doctor, and align update documentation in every existing locale.

* refactor(uninstall): share declaration and unlink operations

Keep declaration resolution and unlink metadata ordering in shared owners so CLI and API preserve the same scope and recovery behavior. Consolidate domain regressions while retaining caller translation coverage.

Distinguish record-only removals in API and CLI operation logs and CLI JSON, including mixed batches and dry runs. Document outcome fields, warning semantics, and current API error codes across existing locales.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Willie <egg358358@gmail.com>
2026-11-14 13:11:27 +08:00

739 lines
27 KiB
Markdown

---
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:**
```bash
skillshare init
```
Add `--source` if you want a custom path:
```bash
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:
```yaml
# WRONG — targets must be a list
targets: {}
# RIGHT
targets: []
```
```yaml
# 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:
```yaml
# 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:**
```bash
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:
```bash
skillshare target add myapp ~/.myapp/skills # Preferred
```
### `target directory already exists with files`
**Cause:** Target has existing files that might be overwritten.
**Solution:**
```bash
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:**
```bash
# 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 {#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:
```bash
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:
```yaml
# ~/.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:**
```bash
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:
```bash
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](/docs/reference/commands/backup#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](/docs/reference/commands/extras#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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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):
```bash
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`](/docs/reference/targets/configuration#git-root).
**Solution:** Pick one of the three options the error prints:
```bash
# 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:
```bash
skillshare install
skillshare sync
```
For project mode:
```bash
skillshare install -p
skillshare sync -p
```
`status`, `check`, `update --all`, and `doctor` report this state and suggest `skillshare install`.
Deleting a global checkout by hand leaves its declaration and audit acceptances. Restore it only if you want it back and its source is reachable and destination free. To drop the declaration instead, even when the source is unreachable:
```bash
skillshare uninstall _team-skills -g
```
Use the full canonical recorded name with `_` (for example `devops/_team-skills`) when a plain folder or link to a non-checkout occupies the path. While the tracked declaration remains, this removes only metadata; the occupant and `.gitignore` stay untouched, and there is no trash entry to restore. After `install` or another reconcile walks that folder or followed non-checkout link, it becomes an ordinary record and ordinary uninstall moves the occupant to trash. See [uninstall](../reference/commands/uninstall.md#tracked-repositories).
### `nested git repositories must be disabled first`
**Cause:** With `git_root: root`, a subdirectory that Git does not ignore (e.g. a skill you cloned by hand) 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. Tracked repositories installed with `--track` are listed in the managed `.gitignore` block, so they are skipped unless they were already committed.
**Solution:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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):**
```powershell
$env:GITLAB_TOKEN = "glpat-xxxx"
# Permanent (survives restarts)
[Environment]::SetEnvironmentVariable("GITLAB_TOKEN", "glpat-xxxx", "User")
```
**Solution — Option 2: Use SSH URL:**
```bash
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:**
```bash
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](/docs/reference/appendix/environment-variables#git-authentication) and [Private Repositories](/docs/reference/commands/install#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):**
```bash
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):**
```bash
skillshare install git@gitlab.internal.company.com:team/skills.git --track
```
**Solution — Option 3: Disable SSL verification (not recommended):**
```bash
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](/docs/reference/appendix/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:**
```bash
# 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:**
```bash
# 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.
### `audit scan failed`
**Cause:** The audit could not run, for example because `audit-rules.yaml` does not parse or one of its patterns does not compile. The error names the file. `install` refuses the skill, agent or tracked repository and removes what it installed. `update` and `upgrade --skill` keep the installed copy. `--force` does not help: it accepts findings, and a scan that did not run has none.
**Solution:** Fix the file the error names (see [audit rules](/docs/reference/commands/audit-rules)). If you trust the source, you can install without scanning:
```bash
skillshare install <source> --skip-audit
```
---
## Upgrade Errors
### `GitHub API rate limit exceeded`
**Cause:** Too many unauthenticated API requests.
**Solution:**
```bash
# 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:**
1. Skill not synced
2. Invalid SKILL.md format
3. AI CLI caching
**Solutions:**
```bash
# 1. Sync
skillshare sync
# 2. Check format
skillshare doctor
# 3. Restart AI CLI
```
### Antigravity does not load synced skills {#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**
```bash
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:
```yaml
# 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](/docs/reference/targets/configuration#include--exclude-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:**
1. Ignore the warning if those targets don't need agents.
2. Add an `agents:` sub-key to the target in `config.yaml` to enable agent sync for it:
```yaml
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`:
```bash
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.
### `source was lost by an earlier update; reinstall this agent` {#agent-source-lost}
**Cause:** Older versions of `update agents` rewrote an agent's recorded source to `/agents/<name>.md` and dropped its repository URL ([#777](https://github.com/runkids/skillshare/issues/777)). Without the repository, the agent cannot be checked or updated.
**Solution:** Install the agent again from its repository, which records the source correctly:
```bash
skillshare install <repo> --kind agent --all --force
```
### `.agentignore` patterns not taking effect
**Causes:**
1. 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).
2. Your pattern matches a different segment than you expect — the file uses [gitignore syntax](https://git-scm.com/docs/gitignore).
**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 {#plugin-errors}
### `<agent> CLI is not installed or not on PATH` {#plugin-cli-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:**
1. Install the Agent's CLI on that machine.
2. If it is installed, add its directory to the `PATH` of whatever starts Skillshare, such as the scheduled job's environment.
3. For an [account target](/docs/reference/commands/plugin#accounts), you can set `cli` to the executable's absolute path instead.
### `Codex CLI not found on the machine running Skillshare` {#plugin-codex-not-found}
**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:**
1. Install the Codex app or the Codex CLI on that machine.
2. If Codex is somewhere else, set [`SKILLSHARE_CODEX_CLI`](/docs/reference/appendix/environment-variables#skillshare_codex_cli) to 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` {#plugin-marketplace-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:**
1. 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.
2. Or remove that Agent from the plugin and add the plugin again from its source. See [Cross-Machine Sync — Plugins](/docs/how-to/sharing/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:**
```bash
go build -o bin/skillshare ./cmd/skillshare
# Or set
export SKILLSHARE_TEST_BINARY=/path/to/skillshare
```
---
## Still Having Issues?
See [Troubleshooting Workflow](./troubleshooting-workflow.md) for a systematic debugging approach.