0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

共通スキルを symlink で一元管理する:更新伝播の仕組みと同期の落とし穴

0
Posted at

複数のプロジェクトで Claude Code のスキルを保守していると、同じ SKILL.md を各プロジェクトのディレクトリへコピーして管理し、変更のたびに全コピーを更新する作業が生じます。2026-08-09 現在、Claude Code はスキルディレクトリのエントリとして symlink をサポートしており、ひとつのファイルへの変更を symlink で参照しているすべてのプロジェクトへ自動的に伝播できます。

本稿では、git 管理の共有スキルライブラリを作成し、personal および project レベルから symlink で参照する実装を、ゼロから動作確認まで通して示します。あわせて、ライブ変更検知の適用範囲、compaction 後のスキル再注入の挙動、standing instructions としての設計指針を扱います。

スキルの配置レベルと適用スコープ

Claude Code のスキルには enterprise・personal・project の3レベルがあります [1]。

  • Personal — ~/.claude/skills/<skill-name>/SKILL.md(すべてのプロジェクトに適用)[1]
  • Project — .claude/skills/<skill-name>/SKILL.md(当該プロジェクトのみに適用)[1]

複数プロジェクト間で共有するスキルは personal レベルへ配置します。project レベルは、そのプロジェクト固有のカスタマイズを上乗せする場所として使います。

同名スキルが複数レベルに存在する場合の優先順位は enterprise > personal > project であり、いずれのレベルのスキルも同名の bundled スキルを上書きします [1]。

"enterprise overrides personal, and personal overrides project. A skill at any of these levels also overrides a bundled skill with the same name." [1]

symlink サポートの基本仕様

"A <skill-name> entry in the enterprise, personal, or project locations can be a symlink to a directory elsewhere on disk. Claude Code follows the symlink and reads SKILL.md from the target directory" [1]

ディレクトリエントリそのものが symlink であればよく、SKILL.md 自体を symlink にする必要はありません。同じ symlink 先が複数の場所から参照されても重複ロードは起きません。

"and if the same target is reachable from more than one location, Claude Code loads the skill once." [1]

personal と project の両レベルから同じターゲットを symlink した場合でも、スキルは1回だけ読み込まれます。

なお、plugin スキルの symlink 扱いは通常スキルと異なります [1]。

"Plugin skills handle symlinks differently" [1]

plugin スキルを symlink で共有する際は、Marketplace の symlink 共有ドキュメントを別途参照してください。

実装:ゼロから動作確認まで

環境: Linux または macOS、Claude Code 最新版(2026-08-09)、git 導入済み。

ステップ 1:共有スキルライブラリの作成

mkdir -p ~/skill-lib/deploy-helper ~/skill-lib/code-review

deploy-helper の SKILL.md を作成します。

cat > ~/skill-lib/deploy-helper/SKILL.md << 'SKILLEOF'
# deploy-helper

デプロイ関連のタスクを支援します。本セッション全体を通じて以下を守ってください。

- テストが緑であることを確認してからデプロイ手順を提案する
- ロールバック手順が文書化されているか確認する
- シークレットがコードにコミットされていないか検証する

これらはスタンディング指示として本セッション全体に適用されます。
SKILLEOF

ステップ 2:git リポジトリとして初期化

cd ~/skill-lib
git init
git add deploy-helper/SKILL.md code-review/SKILL.md
git commit -m "feat: initial skill library"

実行すると次のような出力が得られます。

Initialized empty Git repository in /home/user/skill-lib/.git/
[main (root-commit) a3f1c9b] feat: initial skill library
 2 files changed, 28 insertions(+)
 create mode 100644 code-review/SKILL.md
 create mode 100644 deploy-helper/SKILL.md

ステップ 3:symlink の作成(personal レベル)

mkdir -p ~/.claude/skills
ln -s ~/skill-lib/deploy-helper ~/.claude/skills/deploy-helper
ln -s ~/skill-lib/code-review ~/.claude/skills/code-review

ステップ 4:動作確認

symlink が正しく張られているか確認します。

ls -la ~/.claude/skills/
total 0
drwxr-xr-x 2 user user  80 Aug  9 10:25 ./
drwxr-xr-x 8 user user 200 Aug  9 10:25 ../
lrwxrwxrwx 1 user user  34 Aug  9 10:25 code-review -> /home/user/skill-lib/code-review
lrwxrwxrwx 1 user user  38 Aug  9 10:25 deploy-helper -> /home/user/skill-lib/deploy-helper

symlink 先の実パスを確認します。

readlink -f ~/.claude/skills/deploy-helper
/home/user/skill-lib/deploy-helper

SKILL.md が参照可能かを確認します。

ls ~/.claude/skills/deploy-helper/
SKILL.md

これで ~/.claude/skills/deploy-helper/SKILL.md がセッション開始時に読み込まれます。

ステップ 5:ライブラリの更新と伝播確認

vim ~/skill-lib/deploy-helper/SKILL.md
git add deploy-helper/SKILL.md
git commit -m "fix: add smoke test confirmation step"
[main 7b2e4f1] fix: add smoke test confirmation step
 1 file changed, 3 insertions(+), 1 deletion(-)

セッション内であればライブ変更検知により次のターンから反映されます(後述)。

ステップ 6:project レベルとの組み合わせ

mkdir -p ./myproject/.claude/skills
ln -s ~/skill-lib/deploy-helper ./myproject/.claude/skills/deploy-helper
readlink -f ./myproject/.claude/skills/deploy-helper
/home/user/skill-lib/deploy-helper

personal と project の両方から同じターゲットが参照される場合、Claude Code はそのスキルを1回だけ読み込みます。

変更検知の動作範囲

"Claude Code watches skill directories for file changes. When you add, edit, or remove a skill under ~/.claude/skills/, the project .claude/skills/, or a .claude/skills/ inside an --add-dir directory, Claude Code picks up the change within the current session, without a restart." [1]

SKILL.md の追加・編集・削除はセッション内でリスタートなしに検知されます。symlink 先のファイルを直接編集した場合も対象です。

例外 1:セッション開始後に skills ディレクトリを新規作成した場合

"If you create a top-level skills directory that didn't exist when the session started, restart Claude Code so it can watch the new directory." [1]

~/.claude/skills/ 自体がセッション開始時に存在しなかった場合、その後作成しても監視が始まりません。Claude Code を再起動する必要があります。

例外 2:plugin スキルの内部変更

"Live change detection covers SKILL.md text only. For a skill folder that is also a plugin, changes to hooks/, .mcp.json, agents/, and output-styles/ need /reload-plugins to take effect." [1]

スキルが plugin でもある場合、SKILL.md 以外の変更には /reload-plugins コマンドが必要です。

compaction 後のスキル再注入

"Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens." [1]

各スキルの先頭 5,000 トークンが再注入され、複数スキルの合計上限は 25,000 トークンです(2026-08-09 時点)。最近使ったスキルから順に充填されるため、セッション内で多数のスキルを呼び出した場合、古いスキルは compaction 後に完全に落ちることがあります。

standing instructions の設計

"Claude Code does not re-read the skill file on later turns, so write guidance that should apply throughout a task as standing instructions rather than one-time steps." [1]

スキルはターンをまたいで再読み込みされません。スキル呼び出し後のすべてのターンで適用してほしい指示は、SKILL.md に standing instructions として記述します。逐次ステップではなく、セッション全体に適用される方針として書くことが重要です。

permissions.additionalDirectories との違い

settings.json の permissions.additionalDirectories はファイルアクセス権限のみを付与します。

"The permissions.additionalDirectories setting in settings.json grants file access only and does not load skills." [1]

共有ライブラリのディレクトリを permissions.additionalDirectories に追加しても、スキルとして有効にはなりません。スキルとして読み込むには --add-dir または /add-dir を使用します。

Cowork セッションとクラウドセッションの制約

"Cowork sessions and cloud sessions, including routines, don't read ~/.claude/skills/ on your machine." [1]

Cowork セッションおよびクラウドセッションはローカルの ~/.claude/skills/ を読み込みません。チーム共有のスキルは必ずリポジトリの .claude/skills/ に配置し、git 管理します。

運用設計:共有ライブラリをどう組むか(docs に無い観点)

以下は公式ドキュメントには記載のない、実際の運用での設計判断です。

スキル名の安定性

スキル名はそのままディレクトリ名になり、各プロジェクトの symlink 名とも一致させる必要があります。ライブラリ側でディレクトリ名を変更すると、すべての symlink の張り直しが発生します。動詞-名詞形の短い名前(例: deploy-helper、code-review)を最初に確定させることは、後から変更コストが高くなるため実際には意味があります。

SKILL.md の構造と compaction の関係

compaction 後に各スキルの先頭 5,000 トークンしか再注入されない仕様上、重要な standing instructions ほど SKILL.md の前に置く必要があります。後半に追記した指示は compaction を挟むと失われる可能性があります。5,000 トークンは日本語で約 3,500〜4,000 字程度が目安です。

共有ライブラリとして複数プロジェクトで使う場合、全プロジェクトに共通する指示をファイル冒頭に置き、プロジェクト固有のカスタマイズは project レベルの別スキルに分離する設計が、compaction の制約上は妥当だと考えます。

plugin スキルとの分離

plugin スキルの symlink 扱いは通常スキルと異なります。共有ライブラリに plugin スキルを混在させると、SKILL.md のライブ検知と plugin 内部変更の /reload-plugins 必要性が並存し、運用の把握が複雑になります。plugin スキルは別のリポジトリで管理し、通常スキルの共有ライブラリとは分離する方が管理しやすいと思います。

Cowork 環境への対応

Cowork セッションはローカルの ~/.claude/skills/ を読み込まないため、チーム共有のルールを personal スキルに集約していると Cowork では無効になります。この前提でチーム開発を計画する場合、重要な業務ルールはリポジトリ内の .claude/skills/ に置くことを設計段階で決めておく方が実際には安全です。

References

[1] https://code.claude.com/docs/en/slash-commands

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?