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
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 seems stuck or slow
Cause: Large files in skills directory.
Solution: Add ignore patterns:
# ~/.config/skillshare/config.yaml
ignore:
- "**/.DS_Store"
- "**/.git/**"
- "**/node_modules/**"
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 [email protected]
# 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 "[email protected]"
# 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
merge conflicts
Cause: Same file was edited on multiple machines.
Solution:
cd ~/.config/skillshare/skills
git status # See conflicted files
# Edit files to resolve conflicts
git add .
git commit -m "Resolve conflicts"
skillshare sync
Git identity not configured
Cause: No user.name / user.email in git config. skillshare uses a local fallback (skillshare@local) so init can complete, but you should set your own.
Solution:
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
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 [email protected]:team/private-skills.git
skillshare install [email protected]:team/skills.git
skillshare install [email protected]: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 |
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 [email protected]: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
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.
Update Errors
git failed: Need to specify how to reconcile divergent branches
Cause: The remote branch has diverged from your local tracked copy.
Solution:
# Force update (replaces local with remote)
skillshare update --force
# Or manually resolve
cd ~/.config/skillshare/skills/_repo-name
git pull --rebase
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
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-*]
If filters already isolate the duplicates, sync shows an info message instead of a warning — no action needed. See Target Filters for full syntax.
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.