Files
skillshare/docs/faq.md
T
Willie Hung 08de85e390 docs: restructure README and add comprehensive docs/
- 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
2026-01-20 22:50:52 +08:00

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)