Files
skillshare/website/docs/troubleshooting/troubleshooting-workflow.md
T
Willie caa525b8aa feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
Restructure the entire documentation site following the Diátaxis framework
(Learn / How-to / Understand / Reference) with new content across 110 files.

## Information Architecture (M1)
- Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/)
- Add client-redirects plugin for old URL compatibility
- Rewrite sidebar, navbar, and footer to match new IA
- Update all internal cross-references

## Homepage + Quickstarts (M2)
- Add scenario entry cards to homepage with hand-drawn design
- 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation),
  Codex, Multiple Tools, Dev Containers, Playground

## Blog + Changelog (M3)
- Enable Docusaurus blog plugin with authors.yml
- 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills
  comparison, team sharing patterns, write your first skill
- Static /changelog page from CHANGELOG.md

## Recipes + Philosophy (M4)
- 5 recipe pages: CI/CD validation, enterprise skills, project setup,
  cross-machine sync, team onboarding
- 3 philosophy pages: why-local-first, security-first, sync-modes-explained

## Content Polish
- Cross-validate all content against CLI source (19 inaccuracies fixed)
- Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.)
- Add registry.yaml to file structure and Key Paths docs
- Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea,
  Azure DevOps, AtomGit, Codeberg)
- Standardize brew install command
- Add AsciinemaPlayer component (cast recordings pending)
2026-02-26 22:27:23 +08:00

3.0 KiB

sidebar_position
sidebar_position
2

Troubleshooting Workflow

Systematic approach to diagnosing and fixing issues.

Overview

flowchart LR
    DIAGNOSE["DIAGNOSE"] --> IDENTIFY["IDENTIFY"] --> FIX["FIX"] --> VERIFY["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

Symptom Likely Cause Quick Fix
Skill not showing in AI CLI Not synced skillshare sync
Symlink broken Source deleted Restore or reinstall
Config errors Invalid YAML skillshare doctor shows details
Can't push/pull Git issues Check git status manually
Permission denied Wrong ownership Check 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