Files
skillshare/website/docs/reference/commands/doctor.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

4.3 KiB
Raw Blame History

sidebar_position
sidebar_position
1

doctor

Check environment and diagnose issues with your skillshare setup.

skillshare doctor
skillshare doctor -p     # Project mode (.skillshare/config.yaml)
skillshare doctor -g     # Force global mode

doctor demo

When to Use

  • Something isn't working and you don't know why
  • After upgrading skillshare or your OS
  • Verify all targets, git, and symlinks are healthy
  • First diagnostic step before filing a bug report

What It Checks

skillshare doctor

Checking environment
  ✓ Config: ~/.config/skillshare/config.yaml
  ✓ Source: ~/.config/skillshare/skills (12 skills)
  ✓ Link support: OK
  ✓ Git: initialized with remote

Checking targets
  ✓ claude    [merge]: merged (8 shared, 2 local)
  ✓ cursor    [copy]: copied (8 managed, 0 local)
  ⚠ codex     [merge]: needs sync

Version
  ✓ CLI: 1.2.0
  ✓ Skill: 1.1.0

Summary
  ✓ All checks passed!

Checks Performed

Environment

Check What It Verifies
Config Config file exists and is valid
Source Source directory exists and is readable
Link support System can create symlinks
Git Repository status and remote configuration

Targets

For each target:

  • Path exists and is writable
  • Sync mode matches actual state
  • Sync drift (linked/managed count vs target expected count after include/exclude)
  • No broken symlinks
  • Duplicate-skill checks for unintended local collisions:
    • merge mode: skipped (local skills are expected)
    • copy mode: manifest-managed copies are ignored; only local colliding copies are warned
  • Valid include/exclude glob patterns
  • Info-level per-target compatibility hint when applicable (example target priority: cursor → antigravity → copilot → opencode; no hint when these targets are absent)

Version

  • CLI version
  • skillshare skill version
  • Checks for available updates

Other

  • Skills without SKILL.md files
  • Last backup timestamp (global mode)
  • Trash status (item count, total size, oldest item age)
  • Broken symlinks in targets

:::note Project Mode When a project has .skillshare/config.yaml, skillshare doctor auto-runs in project mode.

In project mode:

  • Config/source checks use .skillshare/config.yaml and .skillshare/skills
  • Trash status uses .skillshare/trash
  • Backups show not used in project mode :::

Common Issues

"Needs sync"

Target mode was changed but not applied:

skillshare sync

"Not synced"

Target has fewer linked skills than source (e.g. after installing new skills):

skillshare sync

"Has uncommitted changes"

Tracked repo has local changes:

cd ~/.config/skillshare/skills/_team-repo
git status
# Commit or discard changes

A skill was removed from source but symlink remains:

skillshare sync  # Will prune orphaned symlinks

"Skills without SKILL.md"

Skill folders missing required file:

# Add SKILL.md to each skill, or remove the folder
skillshare new my-skill  # Creates proper structure

On Windows without Developer Mode:

  1. Enable Developer Mode in Settings
  2. Or run as Administrator

Example Output with Issues

Checking environment
  ✓ Config: ~/.config/skillshare/config.yaml
  ✓ Source: ~/.config/skillshare/skills (12 skills)
  ✓ Link support: OK
  ⚠ Git: 3 uncommitted change(s)

Checking targets
  ✓ claude    [merge]: merged (8 shared, 2 local)
  ✗ cursor    [merge]: 2 broken symlink(s): old-skill, removed-skill
  ⚠ codex     [merge->needs sync]: linked (needs sync to apply merge mode)
  ⚠ claude: 1 skill(s) not synced (2/3 linked)

⚠ Skills without SKILL.md: test-dir, temp

Version
  ✓ CLI: 1.2.0
  ⚠ Skill: 1.0.0 (update available: 1.1.0)
    Run: skillshare upgrade --skill && skillshare sync

Backups: last backup 2026-01-18_09-00-00 (3 days ago)
ℹ Trash: 2 item(s) (45.2 KB), oldest 3 day(s)

ℹ Update available: 1.2.0 -> 1.3.0
  brew upgrade skillshare  OR  curl -fsSL .../install.sh | sh

Summary
  ✗ 1 error(s), 4 warning(s)

See Also

  • status — Quick status check
  • sync — Fix sync issues
  • upgrade — Update CLI and skill