- Slim README from 777 to 214 lines for better readability - Adjust value prop: emphasize sync, bidirectional, team over AI-native - Split detailed content into docs/ directory: - install.md: init, install, update, upgrade, uninstall - sync.md: sync, pull, push, backup, restore with diagrams - targets.md: target management with flowcharts - cross-machine.md: multi-machine sync setup - team-edition.md: tracked repos, nested skills, team sharing - configuration.md: config file reference - faq.md: doctor command, FAQ, troubleshooting - Add docs/README.md as documentation index - Remove /docs/ from .gitignore
4.3 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 --remote
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 --remote fails due to local changes:
# Option 1: Push your changes first
skillshare push -m "Local changes"
skillshare pull --remote
# Option 2: Discard local changes
cd ~/.config/skillshare/skills
git checkout -- .
skillshare pull --remote
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)