144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
# Skillshare Troubleshooting
|
|
|
|
Common issues, solutions, and tips for AI assistants.
|
|
|
|
## Common Issues
|
|
|
|
| Problem | Diagnosis | Solution |
|
|
|---------|-----------|----------|
|
|
| "config not found" | Config missing | Run `skillshare init` |
|
|
| Target shows differences | Files out of sync | Run `skillshare sync` |
|
|
| Lost source files | Deleted via symlink | `cd ~/.config/skillshare/skills && git checkout -- <skill>/` |
|
|
| Target has local skills | Need to preserve | Ensure `merge` mode, then `skillshare pull` before sync |
|
|
| Skill not appearing | Not synced yet | Run `skillshare sync` after install |
|
|
| Can't find installed skills | Wrong directory | Check `skillshare status` for source path |
|
|
| "permission denied" | Symlink issues | Check file ownership and permissions |
|
|
| Git remote not set | Push fails | Run `git remote add origin <url>` in source |
|
|
|
|
## Recovery Workflow
|
|
|
|
When something goes wrong:
|
|
|
|
```bash
|
|
skillshare doctor # 1. Diagnose issues
|
|
skillshare backup # 2. Create safety backup
|
|
skillshare sync --dry-run # 3. Preview fix
|
|
skillshare sync # 4. Apply fix
|
|
```
|
|
|
|
## Git Recovery
|
|
|
|
If source files were accidentally deleted:
|
|
|
|
```bash
|
|
cd ~/.config/skillshare/skills
|
|
git status # See what's missing
|
|
git checkout -- <skill-name>/ # Restore specific skill
|
|
git checkout -- . # Restore all deleted files
|
|
```
|
|
|
|
If you need to restore from backup:
|
|
|
|
```bash
|
|
skillshare backup --list # List available backups
|
|
skillshare restore claude --from <timestamp>
|
|
```
|
|
|
|
## Tips for AI Assistants
|
|
|
|
### Symlink Behavior
|
|
|
|
Understanding symlinks is critical:
|
|
|
|
1. **merge mode** (default): Each skill in target is a symlink to source
|
|
- Editing `~/.claude/skills/my-skill/SKILL.md` edits the source
|
|
- Changes are immediate and affect all targets
|
|
- Safe: `skillshare uninstall my-skill`
|
|
- **DANGEROUS**: `rm -rf ~/.claude/skills/my-skill` - deletes source!
|
|
|
|
2. **symlink mode**: Entire target directory is a symlink
|
|
- `~/.claude/skills` → `~/.config/skillshare/skills`
|
|
- All targets are identical
|
|
- No local skills possible
|
|
|
|
### When to Use --dry-run
|
|
|
|
Always use `--dry-run` in these situations:
|
|
|
|
- User is cautious or new to skillshare
|
|
- Before `sync` on first use
|
|
- Before `pull --all` to see what will be imported
|
|
- Before `install` from unknown sources
|
|
- Before `restore` to preview what will change
|
|
- Before `target remove` to understand impact
|
|
|
|
### Safe vs Dangerous Operations
|
|
|
|
**Safe operations:**
|
|
```bash
|
|
skillshare target remove <name> # Removes symlinks, keeps source
|
|
skillshare uninstall <name> # Removes skill properly
|
|
skillshare sync # Creates/updates symlinks
|
|
```
|
|
|
|
**NEVER do this:**
|
|
```bash
|
|
rm -rf ~/.claude/skills/my-skill # Deletes source via symlink!
|
|
rm -rf ~/.claude/skills # May delete entire source!
|
|
```
|
|
|
|
### Creating New Skills
|
|
|
|
Guide users to create skills in source:
|
|
|
|
1. Create directory: `~/.config/skillshare/skills/<skill-name>/`
|
|
2. Create `SKILL.md` with required frontmatter:
|
|
```yaml
|
|
---
|
|
name: skill-name
|
|
description: What this skill does
|
|
---
|
|
```
|
|
3. Run `skillshare sync` to distribute
|
|
|
|
### Git Workflow Reminders
|
|
|
|
After any skill changes, remind user to push:
|
|
|
|
```bash
|
|
skillshare push # Simple: commit + push
|
|
skillshare push -m "Add new skill" # With custom message
|
|
```
|
|
|
|
### Handling Init Prompts
|
|
|
|
AI cannot respond to CLI prompts. When user asks to initialize:
|
|
|
|
1. Ask clarifying questions in chat
|
|
2. Build the command with appropriate flags
|
|
3. Run non-interactively
|
|
|
|
Example conversation:
|
|
- AI: "Do you have existing skills to copy from Claude or another tool?"
|
|
- User: "Yes, from Claude"
|
|
- AI: "Which CLI tools should I set up as targets?"
|
|
- User: "Claude and Cursor"
|
|
- AI: "Should I initialize git for version control?"
|
|
- User: "Yes"
|
|
- AI runs: `skillshare init --copy-from claude --targets "claude,cursor" --git`
|
|
|
|
### Debugging Sync Issues
|
|
|
|
If sync seems stuck or wrong:
|
|
|
|
```bash
|
|
skillshare status # Check current state
|
|
skillshare diff # See actual differences
|
|
ls -la ~/.claude/skills # Check symlink targets
|
|
```
|
|
|
|
Look for:
|
|
- Broken symlinks (pointing to non-existent files)
|
|
- Regular files instead of symlinks
|
|
- Wrong symlink targets
|