mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
* feat(sync): make prefixed target naming misconfigurations visible Prefixed naming (#497) works, but several of its failure modes only showed up at sync time or gave advice that cannot be followed: - A collision that only prefixing creates told the user to "rename one in SKILL.md", which a tracked skill cannot do, and never said the prefix caused it. The hint now names the prefixing and points at renaming the other skill or re-tracking the repo with --name. - `target add` silently wrote mode: copy when the inherited naming is prefixed. The CLI now says so. - A target that resolves to prefixed outside copy mode was reported only by sync. status, doctor and target list (plain and JSON) now flag it, and the sync/validation and `--skills=true` errors say how to fix it. - The dim "duplicate skill names (isolated by ...)" line printed on every sync even when nothing was wrong, and before a failing sync. Isolated duplicates are not a problem, so it is dropped; the website docs still showed an outdated form of this output and are corrected in all locales. * fix(status): flag prefixed-outside-copy in the TUI list and status --json Codex review of #503 found two surfaces the new check missed: - The interactive `target list` (the default on a terminal) never read the item's naming error, so a prefixed + merge target looked healthy there. The list row now marks the mode with "!" and the detail panel shows the fix. - `status --json` (global and project) builds its target entries directly, so scripts got no signal. Each target now carries a `warning` string, matching `target list --json`. * docs(troubleshooting): sync no longer prints a message for isolated duplicates The collision troubleshooting tip still said sync shows an info message when filters isolate duplicate skill names. That line was dropped, so the tip now says sync prints nothing about them. Codex review of #503 flagged the stale English page and its four translations. * fix(config): point managed-project naming errors at the project settings The "set mode: copy on the target" hint is wrong for a target a global `projects:` entry expands into: it cannot be edited with `target` or under `targets:`, and the mode lives in the project's skills settings. The hint now depends on whether the target belongs to a managed project (Codex review of #503). The naming/mode check becomes a TargetConfig method so status, doctor and target list share it, which also lets the hint see the project root. Along the way: doctor reuses it, the TUI list renders the mode once, and reportTargetAdded takes a flag instead of comparing a mode string. * fix(config): hint the project settings for managed-project naming errors ProjectNamingError (the config-load check for a global `projects:` entry) still returned the bare naming error, so a project that inherits prefixed with a non-copy mode got no fix. It now names the project's skills settings, like the expanded targets do. The built-in skill's sync reference also mentions that status, doctor and target list flag the misconfiguration before sync. Found by the second /code-review pass on #503. * fix(sync): detect prefix collisions from the colliding paths reportCollisions decided a collision came from prefixing when its name was not also a duplicate in the source. A tracked skill that joined two ordinary skills already sharing the name was therefore sent to the "rename one in SKILL.md" hint, which a tracked skill cannot follow (Codex review of #503). A collision on a prefixed target that includes a tracked path now gets the tracked-skill hint, whatever else shares the name. The wording no longer claims prefixing renamed the skill, since a name that already starts with the repo name is unchanged. * fix(sync): use discovered repo metadata for the tracked-skill hint The collision hint treated any path segment starting with "_" as a tracked repo, so an ordinary skill under a folder such as org/_drafts (no .git) was told it could not be renamed and to re-track a repo that does not exist. It now uses DiscoveredSkill.IsInRepo, the same signal prefixed naming uses. The prefixed docs also gain the fix for a target a global `projects:` entry expands into (projects.<root>.skills.mode: copy), since `target` cannot edit those. Both from Codex review of #503. * fix(sync): keep both collision hints when targets disagree The same name can clash on a prefixed target with a tracked skill and on another target between ordinary skills only. The prefixed flag was OR-ed across targets, so the second case lost its rename/filter hint. Track both kinds separately while grouping, and print each hint that applies (Codex review of #503). * fix(sync): keep the rename hint inside a mixed collision group When a tracked skill and two ordinary skills share a prefixed name, re-tracking the repo fixes only the tracked one; the ordinary pair still clashes and is excluded. The group now also shows the rename/filter hint when at least two of its participants are not tracked (Codex review of #503). * fix(sync): offer filters in the tracked-skill collision hint Two tracked skills of the same repo with the same name collide after prefixing, and neither renaming a tracked skill nor re-tracking the repo separates them. The hint now also names include/exclude filters, so every collision on a prefixed target has an actionable remedy (Codex review of #503). * docs(sync-modes): limit the target list claim to targets under targets target list builds from the config without project expansion, so it cannot flag a target a `projects:` entry expands into; status and doctor can. The prefixed paragraph and the built-in skill reference said all three flag it (Codex review of #503).
707 lines
24 KiB
Markdown
707 lines
24 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.
|
|
|
|
### `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`.
|
|
|
|
### `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:**
|
|
```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.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
### `.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:** The plugin was imported, so Skillshare reinstalls it from the native marketplace it came from, and that marketplace is not registered in the Agent. This is common on a second machine: the import was recorded on the first machine only.
|
|
|
|
**Solutions:**
|
|
|
|
1. Add the marketplace again in the Agent, then run `skillshare sync plugins`.
|
|
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).
|
|
|
|
---
|
|
|
|
## 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.
|