/doctor

sidebar_position: 1

doctor

環境をチェックし、skillshare のセットアップに関する問題を診断します。

skillshare doctor
skillshare doctor -p        # Project mode（.skillshare/config.yaml）
skillshare doctor -g        # グローバルモードを強制
skillshare doctor --json    # CI 向けの構造化された JSON 出力

skillshare doctor

Environment
✓ Config       ~/.config/skillshare/config.yaml
  Config dir   ~/.config/skillshare
  Data         ~/.local/share/skillshare
  State        ~/.local/state/skillshare
✓ Source       ~/.config/skillshare/skills · 43 skills
✓ Agents       ~/.config/skillshare/agents · 2 agents
  Skillignore  not configured
✓ Links        supported
! Git          not initialized (recommended for backup)
✓ Integrity    27/27 skills verified

Targets
✓ claude    skills  merged · merge · 43 shared
✓           agents  synced · merge · 2/2 linked
✓ cursor    skills  merged · merge · 43 shared, 1 local
✓           agents  synced · merge · 2/2 linked
✓ gemini    skills  merged · merge · 43 shared
…
! gemini will see content from: universal
  ~/.agents/skills ← universal
  suggestion: …
…
✗ claude: 1 broken symlink: frontend__css-review
…

Extras
✓ rules     2 files · 2/2 targets OK
✓ commands  1 file · 1/1 targets OK
✓ team      1 file · 4/4 targets OK

Storage
  Backups      last 2026-09-28_12-41-50 · 10m ago
  Trash        1 item, 247 B · oldest under a day

✗ 6 errors, 4 warnings · 1.2s

Next
  skillshare sync  bring the targets up to date

エージェント別バリアントを含む追跡リポジトリでは、Source 行に `N skills, M variants`（論理スキル数と物理コピー数）が表示されます。`variant_routing` チェックは、symlink モードがエージェント別に選択せず全バリアントを公開する場合に警告します。選択的なルーティングには merge または copy モードを使用してください。

バンドル参照は両モードで audit の構造チェックを使用します。不在・未完了は警告、ルート外への脱出はエラーです。グローバル／プロジェクトの `audit-rules.yaml` による無効化も適用されます。JSON の `bundled_references` にはルール ID、ファイル、行番号、スニペットを含みます。[参照チェック](../../understand/audit-engine.md)を参照してください。

使うタイミング

• 何かがうまく動かないが、原因がわからないとき
• skillshare や OS をアップグレードした後
• すべての Target、git、シンボリックリンクが健全かを確認したいとき
• バグ報告をする前の最初の診断ステップとして

チェック内容

skillshare doctor

Environment
✓ Config       ~/.config/skillshare/config.yaml
  Config dir   ~/.config/skillshare
  Data         ~/.local/share/skillshare
  State        ~/.local/state/skillshare
✓ Source       ~/.config/skillshare/skills · 12 skills
✓ Agents       ~/.config/skillshare/agents · 8 agents
✓ Skillignore  2 patterns, 1 skill ignored
✓ Links        supported
✓ Git          initialized with remote
✓ Integrity    12/12 skills verified

Targets
✓ claude    skills  merged · merge · 8 shared, 2 local
✓           agents  synced · merge · 8/8 linked
✓ codex     skills  merged · merge · 8 shared
✓ cursor    skills  copied · copy · 8 managed
✓           agents  synced · merge · 8/8 linked

Extras
✓ commands  3 files · 1/1 targets OK
✓ rules     4 files · 1/1 targets OK

MCP, hooks and plugins
✓ MCP          all 2 servers OK
✓ Hooks        all 1 hook in sync
  Plugins      none configured

Storage
  Backups      last 2026-01-18_09-00-00 · 3d ago
  Trash        empty

Version
✓ CLI          0.23.5
✓ Skill        0.23.5

✓ All checks passed · 0.4s

実行されるチェック

環境

| チェック項目 | 検証内容 | |-------|-----------------| | Config | 設定ファイルが存在し、有効であること | | Source | Source ディレクトリが存在し、読み取り可能であること | | Agents | Agents source ディレクトリが存在すること（設定されている場合） | | Skillignore | `.skillignore`（および `.skillignore.local`）の有効なパターンと、無視されている Skill 数 | | Source link | skills source 直下にあるシンボリックリンクまたは Windows ジャンクションごとに 1 行。[`follow_source_links`](../targets/configuration.md#follow_source_links) がオフ（デフォルト）の場合: info として `not followed by discovery; its contents are invisible to skillshare. Set follow_source_links: true to follow it`。オンの場合: info として `followed as a directory (follow_source_links)`、または警告として `not followed: <reason>`（リンク先がない、source のルートまたはその親、sync target との重なり） | | Links | システムがシンボリックリンクを作成できること | | Git | リポジトリの状態と remote の設定 |

Source link の確認はグローバルモードとプロジェクトモードの両方で行われます。source のルートは discovery と同じ方法で解決され、直下のエントリだけを確認します。該当するリンクがなければ出力は追加されません。各リンクは `doctor --json` では `undeclared_source_links` チェックとしても現れ、status は `info`、ポリシーによってスキップされたリンクでは `warning` になります。

Targets

各 Target には **skills** と **agents**（Agent が設定されている場合）のサブ項目が表示されます。

• Skills: パス、sync モード、sync 状態、共有/ローカルの件数
• 「N skills not synced」には `sync` が配置する skill だけを数えます。`sync` が意図的にスキップするもの（`standard` / `prefixed` naming での無効な名前、または名前の衝突）は含みません
• Agents: sync モード、リンク済み件数、drift の検出。Developer Mode がオフの Windows では `merge` が `copy` と表示され、最新の管理対象コピーはリンク済みとして数えられます。skillshare が所有していない、内容が同じローカルファイルは保持されます。copy fallback では agent の件数に `local preserved` として別に表示されます（例：`0/1 linked, 1 local preserved`）。
• 壊れたシンボリックリンクがないこと
• 意図しないローカルの衝突を検出する Skill 重複チェック:
• `merge` モード: スキップ（ローカルの Skill は想定内のため）
• `copy` モード: マニフェストで管理されているコピーは無視され、ローカルで衝突しているコピーのみ警告
• 有効な include/exclude glob パターン
• Naming と mode：copy 以外の mode で `prefixed` に解決される Target はエラーになります。sync がスキップするためです
• 該当する場合、Target ごとの情報レベルの互換性ヒント（Target の優先順位の例: `cursor` → `antigravity` → `copilot` → `opencode`。これらの Target が存在しない場合はヒントなし）

パスの重複

Doctor は、ランタイムのピッカーに到達する前に、Skill 重複のリスクを 2 種類のクラスとしてフラグ付けします。

**`shared_target_paths`** — 2 つ以上の有効な Target が同じプライマリパスに解決される場合に発生します。よくある原因: `universal` と、`~/.agents/skills` に書き込むツール（例: `warp`、`witsy`）の両方を有効にしている場合。

! Shared path ~/.agents/skills ← universal, warp

解決方法: 重複している Target のいずれかを無効化するか、`skillshare target <name> --path <dir>` で別のパスを設定してください。

パスを共有する Target 同士で `include`、`exclude` のフィルター、`mode`、`target_naming` のいずれかが異なる場合（両方の Target が `symlink` モードの場合はフォルダ全体をリンクするため、フィルターと命名は影響しません）、同期のたびに一方の Target の設定どおりにフォルダが書き直され、もう一方の結果が打ち消されます。そのためフォルダが落ち着かず、`sync` には同じ保留中の変更が表示され続けます。Doctor はこのケースを示し、Target を削除する代わりに 1 つ（`universal` が含まれていればそれ）を残して残りの Skills 同期をオフにするよう提案します:

! Shared path ~/.agents/skills ← codex, universal (different settings, so they undo each other on every sync)
  suggestion: Keep universal syncing skills to ~/.agents/skills and stop the rest with `skillshare target codex --skills=false`.

`sync` も同じ Target と実行すべきコマンドを表示し、ダッシュボードの同期ページには外す