BREAKING CHANGE: Command restructure for clearer symmetry - Local sync: sync/collect (Source ↔ Targets) - Remote sync: push/pull (Source ↔ Git Remote) Changes: - Add `collect` command (was `pull <target>`) - Simplify `pull` to git remote only (was `pull --remote`) - Add spinner effects to pull and push commands - Update all documentation and skill references - Add CHANGELOG.md - Update help examples with practical workflows Migration: pull claude → collect claude pull --all → collect --all pull --remote → pull
5.6 KiB
FAQ & Troubleshooting
Doctor
Diagnose configuration issues.
skillshare doctor
What it checks:
- Source directory exists and is valid
- Config file is properly formatted
- All targets are accessible
- Symlinks are not broken
- Git repository status (if initialized)
Example output:
Skillshare Doctor
─────────────────────────────────────────
✓ Config file valid
✓ Source directory exists (5 skills)
✓ Git initialized (clean, remote: origin)
Targets:
✓ claude ~/.claude/skills 5/5 synced
✓ cursor ~/.cursor/skills 5/5 synced
✗ codex ~/.codex/skills 2 broken symlinks
Issues found: 1
→ Run 'skillshare sync' to fix broken symlinks
Frequently Asked Questions
Isn't this just ln -s?
Yes, at its core. But skillshare handles multi-target detection, backup/restore, merge mode, cross-device sync, and broken symlink recovery — so you don't have to.
Can I sync skills to a custom or uncommon tool?
Yes. Use skillshare target add <name> <path> with the tool's skills directory.
How do I sync across multiple machines?
Use git-based cross-machine sync:
# Machine A: push changes
skillshare push -m "Add new skill"
# Machine B: pull and sync
skillshare pull
See cross-machine.md for full setup.
What happens if I modify a skill in the target directory?
Since targets are symlinks, changes are made directly to the source. All targets see the change immediately.
How do I keep a CLI-specific skill?
Use merge mode. Local skills in the target won't be overwritten.
What if I accidentally delete a skill through a symlink?
If you have git initialized (recommended), recover with:
cd ~/.config/skillshare/skills
git checkout -- deleted-skill/
How does target remove work? Is it safe?
Yes, it's safe:
- Backup — Creates backup of the target
- Detect mode — Checks if symlink or merge mode
- Unlink — Removes symlinks, copies source content back
- Update config — Removes target from config.yaml
This is why skillshare target remove is safe, while rm -rf ~/.claude/skills would delete your source files.
Can I use skillshare with a private git repo?
Yes. Use SSH URLs when initializing:
skillshare init --remote git@github.com:you/private-skills.git
How do tracked repos differ from regular skills?
| Aspect | Regular Skill | Tracked Repo |
|---|---|---|
| Source | Copied to source | Cloned with .git |
| Update | install --update |
update <name> (git pull) |
| Prefix | None | _ prefix |
| Nested | Flattened | Flattened with __ |
Common Issues
config not found: run 'skillshare init' first
Run skillshare init to create the configuration. Add --source if you want a custom path.
Integration tests cannot find the binary
Run go build -o bin/skillshare ./cmd/skillshare or set SKILLSHARE_TEST_BINARY.
Deleting a symlinked target removed source files
Use skillshare target remove <name> to unlink targets safely. Recover via git if needed:
cd ~/.config/skillshare/skills
git checkout -- .
Target directory already exists with files
Run skillshare backup before skillshare sync to migrate safely.
Target path does not end with skills
Verify the path and prefer .../skills as the suffix.
target add fails with "path does not exist"
Create the directory first:
mkdir -p ~/.myapp/skills
skillshare target add myapp ~/.myapp/skills
Sync seems stuck or slow
Check for large files in your skills directory. Use .gitignore patterns in config:
ignore:
- "**/.DS_Store"
- "**/.git/**"
- "**/node_modules/**"
Pull conflicts with local changes
If pull fails due to local changes:
# 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
Skill not appearing in AI CLI
- Check if skill has valid
SKILL.mdwithnamefield - Run
skillshare syncto ensure symlinks are created - Run
skillshare doctorto diagnose issues - Restart your AI CLI (some cache skill lists)
Upgrade fails with "GitHub API rate limit exceeded"
GitHub limits unauthenticated API requests to 60/hour. Solutions:
Option 1: Set a GitHub token (recommended)
# Windows PowerShell
$env:GITHUB_TOKEN = "ghp_your_token_here"
skillshare upgrade
# macOS/Linux
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)
Windows-Specific
How do I install on Windows?
Use PowerShell:
irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex
Or download the .zip from releases.
Does skillshare need admin privileges on Windows?
No. Skillshare uses NTFS junctions instead of symlinks, which don't require admin privileges.
Where are config files on Windows?
%USERPROFILE%\.config\skillshare\config.yaml
%USERPROFILE%\.config\skillshare\skills\
How do I set GITHUB_TOKEN permanently on Windows?
# Current session only
$env:GITHUB_TOKEN = "ghp_your_token"
# Permanent (user-level)
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token", "User")