mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
- 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
176 lines
4.3 KiB
Markdown
176 lines
4.3 KiB
Markdown
# FAQ & Troubleshooting
|
|
|
|
## Doctor
|
|
|
|
Diagnose configuration issues.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# Machine A: push changes
|
|
skillshare push -m "Add new skill"
|
|
|
|
# Machine B: pull and sync
|
|
skillshare pull --remote
|
|
```
|
|
|
|
See [cross-machine.md](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:
|
|
|
|
```bash
|
|
cd ~/.config/skillshare/skills
|
|
git checkout -- deleted-skill/
|
|
```
|
|
|
|
### How does `target remove` work? Is it safe?
|
|
|
|
Yes, it's safe:
|
|
|
|
1. **Backup** — Creates backup of the target
|
|
2. **Detect mode** — Checks if symlink or merge mode
|
|
3. **Unlink** — Removes symlinks, copies source content back
|
|
4. **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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
ignore:
|
|
- "**/.DS_Store"
|
|
- "**/.git/**"
|
|
- "**/node_modules/**"
|
|
```
|
|
|
|
### Pull conflicts with local changes
|
|
|
|
If `pull --remote` fails due to local changes:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. Check if skill has valid `SKILL.md` with `name` field
|
|
2. Run `skillshare sync` to ensure symlinks are created
|
|
3. Run `skillshare doctor` to diagnose issues
|
|
4. Restart your AI CLI (some cache skill lists)
|