Files
skillshare/website/docs/troubleshooting/common-errors.md
T
Willie 2c3003e04f feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
Restructure the entire documentation site following the Diátaxis framework
(Learn / How-to / Understand / Reference) with new content across 110 files.

## Information Architecture (M1)
- Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/)
- Add client-redirects plugin for old URL compatibility
- Rewrite sidebar, navbar, and footer to match new IA
- Update all internal cross-references

## Homepage + Quickstarts (M2)
- Add scenario entry cards to homepage with hand-drawn design
- 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation),
  Codex, Multiple Tools, Dev Containers, Playground

## Blog + Changelog (M3)
- Enable Docusaurus blog plugin with authors.yml
- 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills
  comparison, team sharing patterns, write your first skill
- Static /changelog page from CHANGELOG.md

## Recipes + Philosophy (M4)
- 5 recipe pages: CI/CD validation, enterprise skills, project setup,
  cross-machine sync, team onboarding
- 3 philosophy pages: why-local-first, security-first, sync-modes-explained

## Content Polish
- Cross-validate all content against CLI source (19 inaccuracies fixed)
- Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.)
- Add registry.yaml to file structure and Key Paths docs
- Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea,
  Azure DevOps, AtomGit, Codeberg)
- Standardize brew install command
- Add AsciinemaPlayer component (cast recordings pending)
2026-02-26 04:52:29 +08:00

7.7 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

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 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

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 "you@example.com"

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

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.

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.


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:

  1. Skill not synced
  2. Invalid SKILL.md format
  3. 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-*]

:::tip 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.