/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 や OS をアップグレードした後
• すべての Target、git、シンボリックリンクが健全かを確認したいとき
• バグ報告をする前の最初の診断ステップとして

チェック内容

skillshare doctor

Checking environment
✓ Config: ~/.config/skillshare/config.yaml
→ Config directory: ~/.config/skillshare
→ Data directory:   ~/.local/share/skillshare
→ State directory:  ~/.local/state/skillshare

✓ Source: ~/.config/skillshare/skills (12 skills)
✓ Agents source: ~/.config/skillshare/agents (8 agents)
✓ Skillignore: 2 patterns, 1 skills ignored
✓ Link support: OK
✓ Git: initialized with remote

✓ Skill integrity: 12/12 verified

Checking targets
claude
  skills   [merge] merged (8 shared, 2 local)
  agents   [merge] merged (8/8 linked)
cursor
  skills   [copy] copied (8 managed, 0 local)
  agents   [merge] merged (8/8 linked)
codex
  skills   [merge] needs sync

Extras
✓ rules: 4 files, 1/1 targets OK
✓ commands: 3 files, 1/1 targets OK

Version
✓ CLI: 0.17.0
✓ Skill: 0.17.0

Summary
✓ All checks passed!

実行されるチェック

環境

| チェック項目 | 検証内容 | |-------|-----------------| | Config | 設定ファイルが存在し、有効であること | | Source | Source ディレクトリが存在し、読み取り可能であること | | Agents source | Agents source ディレクトリが存在すること（設定されている場合） | | Skillignore | `.skillignore`（および `.skillignore.local`）の有効なパターンと、無視されている Skill 数 | | Link support | システムがシンボリックリンクを作成できること | | Git | リポジトリの状態と remote の設定 |

Targets

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

• Skills: パス、sync モード、sync 状態、共有/ローカルの件数
• Agents: リンク済み件数、drift の検出
• 壊れたシンボリックリンクがないこと
• 意図しないローカルの衝突を検出する Skill 重複チェック:
• `merge` モード: スキップ（ローカルの Skill は想定内のため）
• `copy` モード: マニフェストで管理されているコピーは無視され、ローカルで衝突しているコピーのみ警告
• 有効な include/exclude glob パターン
• 該当する場合、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>` で別のパスを設定してください。

**`cross_target_discovery`** — ある有効な Target のランタイムが、別の有効な Target が書き込むディレクトリもスキャンすると文書化されている場合に発生します。例えば、以前のセットアップから残った設定では `codex` がレガシーな `~/.codex/skills` を指したままになっている一方、`universal` は `~/.agents/skills` に書き込みます — このディレクトリは Codex も読み込みます。両方を有効にすると、Codex は自身のコンテンツに加えて universal のコンテンツも見ることになります。

! codex will see content from: universal
    ~/.agents/skills ← universal

解決方法: まずスキャンする側の Target（上の例では `codex`）を削除してください。そのランタイムは共有ディレクトリをすでに読み込んでおり、他のツールには影響しません。`skillshare target remove codex --dry-run` でプレビューできます。代わりに書き込み元（`universal`）を削除すると、`~/.agents/skills` を読み込む他のツールからもそれらの skill が見えなくなります。スキャンする側の Target が、書き込み元でフィルタされている skill を持つ場合に限り両方を残し、ランタイムのピッカーでの重複表示を受け入れてください。

どちらのチェックも純粋なメタデータのみを扱います — 設定済みのパスと組み込みの `also_scans` テーブルを読み取るだけで、ファイルシステムへの実際の探査は行いません。

バージョン

• CLI のバージョン
• skillshare skill のバージョン
• 利用可能な更新のチェック

Skill の整合性

ファイルハッシュのメタデータを持つインストール済み Skill について、doctor はインストール以降にファイルが改ざんされていないかを検証します。

• 現在の SHA-256 ハッシュを保存されているハッシュと比較
• Skill ごとに変更・欠落・追加されたファイルを報告
• `.metadata.json` に含まれないローカルの Skill は静かにスキップされます — これは想定内の挙動です
• メタデータはあるが `file_hashes` が欠落しているインストール済み Skill は、その名前とともにフラグ付けされます

⚠ _team-repo__api-helper: 1 modified, 1 missing
✓ Skill integrity: 5/6 verified
⚠ Skill integrity: 1 skill(s) missing file hashes: _old-repo__legacy-skill

Extras

Extras が設定されている場合、以下を検証します。

• 各 Extras の Source ディレクトリが存在すること
• Target ディレクトリに到達可能であること
• 存在しない Source ディレクトリや到達不能な Target を報告

その他

• `SKILL.md` ファイルがない Skill
• Skill レベルの `targets:` フィールド検証（未知の Target 名について警告）
• 最後のバックアップのタイムスタンプ（グローバルモード）
• Trash の状態（アイテム数、合計サイズ、最も古いアイテムの経過日数）
• Target 内の壊れたシンボリックリンク

:::note Project mode プロジェクトに `.skillshare/config.yaml` がある場合、`skillshare doctor` は自動的に Project mode で実行されます。

Project mode では:

• Config/Source のチェックには `.skillshare/config.yaml` と `.skillshare/skills` が使用されます
• Trash の状態には `.skillshare/trash` が使用されます
• バックアップは `not used in project mode` と表示されます

:::

よくある問題

"Needs sync"

Target のモードは変更されたものの、まだ適用されていません。

skillshare sync

"Not synced"

Target のリンク済み Skill が Source より少ない状態です（新しい Skill をインストールした後など）。

skillshare sync

"Has uncommitted changes"

トラッキング対象のリポジトリにローカルの変更があります。

cd ~/.config/skillshare/skills/_team-repo
git status
# 変更をコミットするか破棄する

"Broken symlink"

Skill が Source から削除されたのに、シンボリックリンクが残っています。

skillshare sync  # 孤立したシンボリックリンクを削除します

"Skills without SKILL.md"

必須ファイルがない Skill フォルダです。

# 各 Skill に SKILL.md を追加するか、フォルダを削除する
skillshare new my-skill  # 正しい構造を作成

"Link not supported"

Developer Mode が無効な Windows 環境の場合:

1. 設定で Developer Mode を有効にする 2. または管理者として実行する

問題がある場合の出力例

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

⚠ Skills without SKILL.md: test-dir, temp
⚠ _team-repo__api-helper: 1 modified
✓ Skill integrity: 5/6 verified

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

Version
✓ CLI: 0.17.0
⚠ Skill: 0.16.0 (update available: 0.17.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)

ℹ Updat