Skip to main content

Troubleshooting Workflow

Systematic approach to diagnosing and fixing issues.

Overview​

┌─────────────────────────────────────────────────────────────┐
│                 TROUBLESHOOTING FLOW                        │
│                                                             │
│   DIAGNOSE ──► IDENTIFY ──► FIX ──► VERIFY                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Step 1: Diagnose​

Run the doctor command:

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)
  • Skill format validity

Step 2: Identify the Issue​

Common symptoms and causes​

SymptomLikely CauseQuick Fix
Skill not showing in AI CLINot syncedskillshare sync
Symlink brokenSource deletedRestore or reinstall
Config errorsInvalid YAMLskillshare doctor shows details
Can't push/pullGit issuesCheck git status manually
Permission deniedWrong ownershipCheck file permissions

Step 3: Fix​

Sync issues​

# Re-sync all targets
skillshare sync

# Force sync (recreate symlinks)
skillshare sync --force
# Check status
skillshare status

# Sync to recreate
skillshare sync

Config issues​

# View current config
cat ~/.config/skillshare/config.yaml

# Reset config
rm ~/.config/skillshare/config.yaml
skillshare init

Git issues​

cd ~/.config/skillshare/skills

# Check status
git status

# Pull fails (local changes)
git stash
git pull
git stash pop

# Push fails (remote ahead)
git pull
git push

Target issues​

# Remove and re-add
skillshare target remove claude
skillshare target add claude ~/.claude/skills
skillshare sync

Step 4: Verify​

# Check status
skillshare status

# Run doctor again
skillshare doctor

# Test in AI CLI
# (invoke a skill)

Recovery Options​

Light recovery​

# Just resync
skillshare sync

Medium recovery​

# Restore from backup
skillshare restore claude
skillshare sync

Heavy recovery (start fresh)​

# Backup current state
skillshare backup

# Remove config (preserves skills)
rm ~/.config/skillshare/config.yaml

# Re-initialize
skillshare init

# Sync
skillshare sync

Getting Help​

If you can't resolve the issue:

  1. Gather information:

    skillshare doctor > doctor-output.txt
    skillshare status >> doctor-output.txt

  2. Check the FAQ: Common Errors

  3. Report the issue: GitHub Issues

    • Include doctor output
    • Include error messages
    • Describe what you were trying to do