mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 12:23:22 +00:00
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)
3.0 KiB
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
Broken symlinks
# 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:
-
Gather information:
skillshare doctor > doctor-output.txt skillshare status >> doctor-output.txt -
Check the FAQ: Common Errors
-
Report the issue: GitHub Issues
- Include doctor output
- Include error messages
- Describe what you were trying to do
Related
- Common Errors — Error messages and solutions
- Windows Issues — Windows-specific problems
- FAQ — Frequently asked questions
- Commands: doctor — Doctor command