グローバルインストール vs プロジェクトローカルインストール

学習後の到達目標

OpenSkills の 2 つのインストール場所（グローバル vs プロジェクトローカル）の違いを理解する
シーンに合わせて適切なインストール場所を選択できる
--global フラグの使用方法を習得する
スキルの検索優先順位ルールを理解する
よくあるインストール場所設定ミスを回避できる

前提知識

本チュートリアルでは、すでに初めてのスキルをインストールとインストール元の詳細を完了していることを前提に、基本的なスキルインストールフローを理解しているものとします。

現在の悩み

スキルのインストール方法は習得したかもしれませんが、以下のような問題に直面しているかもしれません：

スキルはどこにインストールされた？：openskills install を実行した後、スキルファイルがどのディレクトリにコピーされたのかわからない
新しいプロジェクトでまたインストール？：別のプロジェクトに切り替えると、以前インストールしたスキルが消えてしまう
1 回だけグローバルで使いたいスキルは？：すべてのプロジェクトで必要なスキルがあるが、各プロジェクトごとにインストールしたくない
複数のプロジェクトでスキルを共有？：チーム全体で使用するスキルがあるので、統一管理したい

実は OpenSkills には 2 つのインストール場所が用意されており、柔軟にスキルを管理できます。

いつ使うべきか

2 つのインストール場所の適用シーン：

インストール場所	適用シーン	例
プロジェクトローカル（デフォルト）	プロジェクト専用のスキル、バージョン管理が必要	チームのビジネスルール、プロジェクト固有のツール
グローバルインストール（`--global`）	すべてのプロジェクトで共通のスキル、バージョン管理不要	汎用コード生成ツール、ファイルフォーマット変換

推奨事項

デフォルトではプロジェクトローカルインストールを使用：スキルをプロジェクトに紐付けることで、チームコラボレーションとバージョン管理が容易になります
汎用ツールのみグローバルインストールを使用：git-helper、docker-generator などクロスプロジェクトツール
過度なグローバル化を避ける：グローバルインストールされたスキルはすべてのプロジェクトで共有されるため、競合やバージョンの不一致を引き起こす可能性があります

核心概念：2 つの場所、柔軟な選択

OpenSkills のスキルインストール場所は --global フラグで制御されます：

デフォルト（プロジェクトローカルインストール）：

インストール場所：./.claude/skills/（プロジェクトルートディレクトリ）
適用：単一プロジェクト専用のスキル
メリット：スキルがプロジェクトに紐付くので Git にコミットでき、チームコラボレーションが容易

グローバルインストール：

インストール場所：~/.claude/skills/（ユーザーホームディレクトリ）
適用：すべてのプロジェクトで共通のスキル
メリット：すべてのプロジェクトで共有でき、重複インストール不要

重要概念

プロジェクトローカル：スキルが現在のプロジェクトの .claude/skills/ ディレクトリにインストールされ、現在のプロジェクトにのみ表示されます。

グローバルインストール：スキルがユーザーホームディレクトリの .claude/skills/ にインストールされ、すべてのプロジェクトに表示されます。

手順に従って

ステップ 1：デフォルトのインストール動作を確認

なぜデフォルトのインストール方法を先に理解し、OpenSkills の設計思想を把握するため。

ターミナルを開き、任意のプロジェクトで以下を実行：

bash

# テスト用スキルをインストール（デフォルトはプロジェクトローカル）
npx openskills install anthropics/skills -y

# スキルリストを表示
npx openskills list

期待される結果：スキルリストの各スキルの後に (project) タグが表示されます

  codebase-reviewer         (project)
    Review code changes for issues...

Summary: 3 project, 0 global (3 total)

解説：

デフォルトでは、スキルは ./.claude/skills/ ディレクトリにインストールされます
list コマンドは (project) または (global) タグを表示します
--global フラグを使用しないデフォルトでは、スキルは現在のプロジェクトにのみ表示されます

ステップ 2：スキルのインストール場所を確認

なぜスキルファイルの実際の保存場所を確認し、後の管理に役立てるため。

プロジェクトルートディレクトリで以下を実行：

bash

# プロジェクトローカルのスキルディレクトリを表示
ls -la .claude/skills/

# スキルディレクトリの内容を表示
ls -la .claude/skills/codebase-reviewer/

期待される結果：

.claude/skills/
├── codebase-reviewer/
│   ├── SKILL.md
│   └── .openskills.json    # インストールメタデータ
├── file-writer/
│   ├── SKILL.md
│   └── .openskills.json
└── ...

解説：

各スキルには独自のディレクトリがあります
SKILL.md はスキルの核心内容です
.openskills.json はインストール元とメタデータを記録（更新に使用）

ステップ 3：グローバルにスキルをインストール

なぜグローバルインストールのコマンドと効果を理解するため。

以下を実行：

bash

# スキルをグローバルインストール
npx openskills install anthropics/skills --global -y

# 再度スキルリストを表示
npx openskills list

期待される結果：

  codebase-reviewer         (project)
    Review code changes for issues...
  file-writer              (global)
    Write files with format...

Summary: 1 project, 2 global (3 total)

解説：

--global フラグを使用すると、スキルは ~/.claude/skills/ にインストールされます
list コマンドは (global) タグを表示します
同名のスキルがある場合、プロジェクトローカルのバージョンが優先されます（検索優先順位）

ステップ 4：2 つのインストール場所を比較

なぜ実際の比較を通じて、2 つのインストール場所の違いを理解するため。

以下のコマンドを実行：

bash

# グローバルインストールされたスキルディレクトリを表示
ls -la ~/.claude/skills/

# プロジェクトローカルとグローバルインストールされたスキルを比較
echo "=== Project Skills ==="
ls .claude/skills/

echo "=== Global Skills ==="
ls ~/.claude/skills/

期待される結果：

=== Project Skills ===
codebase-reviewer
file-writer

=== Global Skills ===
codebase-reviewer
file-writer
test-generator

解説：

プロジェクトローカルスキル：./.claude/skills/
グローバルスキル：~/.claude/skills/
2 つのディレクトリに同名スキルが存在できますが、プロジェクトローカルの優先順位が高いです

ステップ 5：検索優先順位を確認

なぜ OpenSkills が複数の場所でスキルを検索する方法を理解するため。

以下を実行：

bash

# 2 つの場所に同名スキルをインストール
npx openskills install anthropics/skills -y  # プロジェクトローカル
npx openskills install anthropics/skills --global -y  # グローバル

# スキルを読み込み（プロジェクトローカルバージョンが優先されます）
npx openskills read codebase-reviewer | head -5

期待される結果：出力はプロジェクトローカルバージョンのスキル内容です。

検索優先順位ルール（ソースコード dirs.ts:18-24）：

typescript

export function getSearchDirs(): string[] {
  return [
    join(process.cwd(), '.claude/skills'),   // 1. プロジェクトローカル（最高優先順位）
    join(homedir(), '.claude/skills'),       // 2. グローバル
  ];
}

解説：

プロジェクトローカルのスキルはグローバルより優先順位が高い
同名スキルが同時に存在する場合、プロジェクトローカルバージョンが優先されます
これにより「プロジェクトがグローバルを上書き」という柔軟な設定が可能になります

チェックポイント ✅

以下のチェックを完了し、本レッスンの内容を習得したことを確認：

[ ] プロジェクトローカルインストールとグローバルインストールを区別できる
[ ] --global フラグの役割を知っている
[ ] スキルの検索優先順位ルールを理解している
[ ] シーンに合わせて適切なインストール場所を選択できる
[ ] インストール済みスキルの場所タグを確認する方法を知っている

落とし穴の警告

よくあるエラー 1：グローバルインストールの誤用

エラーシーン：プロジェクト専用スキルをグローバルインストール

bash

# ❌ エラー：チームのビジネスルールをグローバルインストールすべきではない
npx openskills install my-company/rules --global

問題：

チームの他のメンバーがそのスキルを取得できません
スキルがバージョン管理されません
他のプロジェクトのスキルと競合する可能性があります

正しい方法：

bash

# ✅ 正しい：プロジェクト専用スキルはデフォルトインストール（プロジェクトローカル）を使用
npx openskills install my-company/rules

よくあるエラー 2：`--global` フラグを忘れる

エラーシーン：すべてのプロジェクトでスキルを共有したいが、--global を追加し忘れた

bash

# ❌ エラー：デフォルトでプロジェクトローカルにインストールされ、他のプロジェクトで使用できない
npx openskills install universal-tool

問題：

スキルは現在のプロジェクトの ./.claude/skills/ にのみインストールされます
別のプロジェクトに切り替えると、再インストールが必要です

正しい方法：

bash

# ✅ 正しい：汎用ツールはグローバルインストールを使用
npx openskills install universal-tool --global

よくあるエラー 3：同名スキルの競合

エラーシーン：プロジェクトローカルとグローバルに同名スキルがインストールされているが、グローバルバージョンを使用したい

bash

# プロジェクトローカルとグローバルの両方に codebase-reviewer がある
# しかしグローバルバージョン（新しい）を使いたい
npx openskills install codebase-reviewer --global  # 新しいバージョンをインストール
npx openskills read codebase-reviewer  # ❌ まだ古いバージョンが読み込まれる

問題：

プロジェクトローカルバージョンの優先順位が高い
グローバルに新しいバージョンをインストールしても、まだプロジェクトローカルの古いバージョンが読み込まれます

正しい方法：

bash

# 方案 1：プロジェクトローカルバージョンを削除
npx openskills remove codebase-reviewer  # プロジェクトローカルを削除
npx openskills read codebase-reviewer  # ✅ 今はグローバルバージョンが読み込まれる

# 方案 2：プロジェクトローカルを更新
npx openskills update codebase-reviewer  # プロジェクトローカルバージョンを更新

まとめ

重要ポイント：

デフォルトはプロジェクトローカルにインストール：スキルは ./.claude/skills/ にインストールされ、現在のプロジェクトにのみ表示されます
グローバルインストールには --global を使用：スキルは ~/.claude/skills/ にインストールされ、すべてのプロジェクトで共有されます
検索優先順位：プロジェクトローカル > グローバル
推奨原則：プロジェクト専用はローカル、汎用ツールはグローバル

意思決定フロー：

[スキルをインストールする必要がある] → [プロジェクト専用か？]
                      ↓ はい
              [プロジェクトローカルインストール（デフォルト）]
                      ↓ いいえ
              [バージョン管理が必要か？]
                      ↓ はい
              [プロジェクトローカルインストール（Git にコミット可能）]
                      ↓ いいえ
              [グローバルインストール（--global）]

覚え書き：

プロジェクトローカル：スキルがプロジェクトに紐付く、チームコラボレーションで悩みなし
グローバルインストール：汎用ツールはグローバルに、すべてのプロジェクトで使用可能

次回の予告

次回のレッスンでは インストール済みスキルの一覧表示 を学びます。
学ぶ内容：
すべてのインストール済みスキルを表示する方法
スキルの場所タグの意味を理解する
プロジェクトスキルとグローバルスキルの数を統計する方法
場所に基づいてスキルをフィルタリングする方法

付録：ソースコード参考

クリックしてソースコードの場所を表示

更新日時：2026-01-24

機能	ファイルパス	行番号
インストール場所判断	`src/commands/install.ts`	84-92
ディレクトリパスユーティリティ	`src/utils/dirs.ts`	7-25
スキルリスト表示	`src/commands/list.ts`	20-43

重要定数：

.claude/skills：デフォルトスキルディレクトリ（Claude Code 互換）
.agent/skills：汎用スキルディレクトリ（マルチエージェント環境）

重要関数：

getSkillsDir(projectLocal, universal)：フラグに基づいてスキルディレクトリパスを返す
getSearchDirs()：スキル検索ディレクトリリストを返す（優先順位順）
listSkills()：すべてのインストール済みスキルをリスト表示し、場所タグを表示

ビジネスルール：

デフォルトはプロジェクトローカルにインストール（!options.global）
スキル検索優先順位：プロジェクトローカル > グローバル
list コマンドは (project) と (global) タグを表示

グローバルインストール vs プロジェクトローカルインストール ​

学習後の到達目標 ​

現在の悩み ​

いつ使うべきか ​

核心概念：2 つの場所、柔軟な選択 ​

手順に従って ​

ステップ 1：デフォルトのインストール動作を確認 ​

ステップ 2：スキルのインストール場所を確認 ​

ステップ 3：グローバルにスキルをインストール ​

ステップ 4：2 つのインストール場所を比較 ​

ステップ 5：検索優先順位を確認 ​

チェックポイント ✅ ​

落とし穴の警告 ​

よくあるエラー 1：グローバルインストールの誤用 ​

よくあるエラー 2：--global フラグを忘れる ​

よくあるエラー 3：同名スキルの競合 ​

まとめ ​

次回の予告 ​

付録：ソースコード参考 ​

グローバルインストール vs プロジェクトローカルインストール

学習後の到達目標

現在の悩み

いつ使うべきか

核心概念：2 つの場所、柔軟な選択

手順に従って

ステップ 1：デフォルトのインストール動作を確認

ステップ 2：スキルのインストール場所を確認

ステップ 3：グローバルにスキルをインストール

ステップ 4：2 つのインストール場所を比較

ステップ 5：検索優先順位を確認

チェックポイント ✅

落とし穴の警告

よくあるエラー 1：グローバルインストールの誤用

よくあるエラー 2：`--global` フラグを忘れる

よくあるエラー 3：同名スキルの競合

まとめ

次回の予告

付録：ソースコード参考