additionalDirectoriesは権限だけ拡張する

Claude Codeが扱うディレクトリを増やす方法は3つあります。3つとも「ディレクトリを追加する」という見た目は同じですが、効果は同じではありません。additionalDirectoriesで追加したディレクトリはファイルの読み書きが許可されるだけで、そこに置いたSkillsやhooks、subagentsは読み込まれません。共有ディレクトリをsettings.jsonに登録して安心していたら、設定が一つも効いていなかった、という事故がここから生まれます。

Skillsやhooksが動かないとき、まず疑う場所

「共有ディレクトリに置いたSkillが呼び出せない」という症状は、追加した方法によっては、置き場が正しくても起きます。次の順に確認すると、原因を絞れます。

additionalDirectoriesは権限だけ拡張する

デフォルトでは、プロンプトなしで読み書きできるのは起動したディレクトリの中だけです。この範囲を広げる永続的な入り口がsettings.jsonのpermissions.additionalDirectoriesです。

{
  "permissions": {
    "additionalDirectories": ["../shared-lib/"]
  }
}

このキーで追加したディレクトリは、元の作業ディレクトリと同じ権限ルールに従います。読み取りはプロンプトなしで通り、書き込みや編集は現在の権限モードがそのまま適用されます。acceptEditsモードなら、作業ディレクトリと同じようにadditionalDirectories内のパスへの編集も自動承認の対象です。ここまでは直感通りです。なお、UNC共有(\\server\share)のようなネットワークパスの多くは追加ディレクトリにできません。Windowsではドライブ文字に割り当て、起動時に--add-dirで渡します。

問題はその先です。公式ドキュメントの見出しは「Additional directories grant file access, not configuration」です。追加ディレクトリはフル設定ルートにならない、という意味です。settingsファイルのadditionalDirectories経由で追加したディレクトリからは、追加先の.claude/配下にあるSkills・commands・subagents・hooks・CLAUDE.md、それにenabledPluginsとextraKnownMarketplacesも、すべて読み込まれません。

--add-dirとadditionalDirectoriesの挙動の違い

紛らわしいのは、--add-dirフラグと/add-dirコマンドがadditionalDirectoriesキーより多くの設定を読み込む点です。

claude --add-dir ../shared-lib

CLAUDE.mdの行だけ条件付きです。CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1を設定した場合に限り、--add-dir配下のCLAUDE.mdと.claude/rules/が読み込まれます。CLAUDE.local.mdはさらに、デフォルトで有効なlocal設定ソースが必要です。追加ディレクトリのcommandsとプロジェクト側のcommandsで同名のファイルがある場合は、プロジェクト側のコマンドが優先して実行されます。

表の「読み込む」にも条件が付きます。フォルダを信頼していない状態(親フォルダだけを信頼している場合や-p実行)では、--add-dir由来のextraKnownMarketplacesと、subagentのfrontmatterに書いたインラインのmcpServersは使われません。

実機のヘルプ出力で見える「アクセス」という言い方

v2.1.285のclaude --help(ヘルプ表示だけで、ログインやモデル呼び出しは伴いません)は、--add-dirをこう説明しています。

claude --help

  --add-dir <directories...>            Additional directories to allow tool
                                        access to

説明文は「ツールのアクセスを許可する追加ディレクトリ」で、Skillsやsubagentsを読み込むとはどこにも書かれていません。--bareの説明には、明示的に渡すコンテキストの一つとして--add-dir (CLAUDE.md dirs)が挙がっています。--setting-sourcesはuser, project, localのカンマ区切りで、SDKのsettingSourcesと対応するCLI側のオプションです。ヘルプの一行説明だけでは、SkillsやCLAUDE.mdの読み込み条件まで読み取れません。そこは公式のPermissionsページで確認します。

Bashサンドボックスの書き込み許可には含まれる

Bashサンドボックスを有効にしている場合、サンドボックス内のコマンドがデフォルトで書き込めるのは、作業ディレクトリ、ユーザーごとの一時ディレクトリ、そして追加したディレクトリです。Sandboxingページの記述では、この追加ディレクトリに--add-dir、/add-dir、permissions.additionalDirectoriesの3つがすべて含まれます。

Skillsやhooksと違って、サンドボックスの書き込み範囲ではsettings.jsonのキーも--add-dirと同列に扱われます。共有ディレクトリ以外の場所にもビルド成果物を書かせたい場合(kubectl、terraform、npmなどが別の場所へ書くとき)だけ、sandbox.filesystem.allowWriteに個別のパスを足します。

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/work/build-output"]
    }
  }
}

Agent SDKのadditionalDirectoriesはさらに紛らわしい

名前の一致がもう一段ややこしくなるのがAgent SDKです。TypeScript版のオプション名はadditionalDirectoriesで、settings.jsonのキーと同じ名前です。しかし挙動は--add-dir側の例外扱いを受け継ぎます。SDKは指定した各ディレクトリを内部的に--add-dirとしてClaude Codeへ渡すため、フラグで追加した場合と同じくSkillsやcommands、subagentsが読み込まれます。Python版のオプション名はadd_dirsで、こちらも同じ扱いです。

--add-dir扱いを受けるからといって、無条件に読み込まれるわけではありません。追加ディレクトリのSkills・commands・subagentsはproject設定ソース経由で読み込まれるため、CLIの--setting-sourcesやSDKのsettingSourcesからprojectを外すと、追加ディレクトリの分も読み込まれなくなります。--bareモードではcommandsとsubagentsが読み込まれません。

Skillsやhooksを複数プロジェクトで共有する方法

additionalDirectoriesでは共有できないと分かったうえで、選べる方法は3つあります。

作業ディレクトリを増やさずにSkillsだけ足したいときは、/add-dirに主作業ディレクトリ配下のサブディレクトリを渡す手もあります。Skills・commands・subagentsだけが読み込まれます(v2.1.257以降)。

信頼ダイアログを承認するまで反映されない

プロジェクトの.claude/settings.jsonに書いたadditionalDirectoriesは、ワークスペースの信頼ダイアログを承認するまで適用されません。permissions.allowルールと同じ扱いで、フォルダを信頼していない間はダイアログに追加先ディレクトリの一覧が表示されるだけで、実際のアクセス許可は発動しません。

claude -pやAgent SDKのセッションでは、この信頼ダイアログ自体が表示されません。公式のエラーページによると、警告は次の形でstderrに出て、追加ディレクトリの設定は無効のままになります(件数・設定名・ファイル名は状況で変わります。この例はpermissions.allowの場合です)。

Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

エラーページによると、この警告は.claude/settings.jsonと.claude/settings.local.jsonのどちらから読んだ場合にも出ます。一方でsettings.local.jsonは、通常あなた自身のファイルとして扱われるため、信頼ステップなしでadditionalDirectoriesが即座に適用されます。ただしこのファイルがgit管理下にあったり、.claudeがシンボリックリンクだったりする場合は、リポジトリ提供の設定として扱われ、通常のプロジェクト設定と同じく信頼を待ちます。この判定にはgitコマンドの実行が要るため、フォルダを信頼するまでは判定自体が保留されます。ホームディレクトリなど「設定ホーム」から起動したセッションだけは、git判定なしで即座にsettings.local.jsonを適用します。

信頼の範囲も押さえておきたい点です。リポジトリ内で信頼すると、その信頼はgitリポジトリのルートに紐づき、ネストしたサブモジュールなど別リポジトリを除くリポジトリ全体に及びます。worktreeではメインのチェックアウトのルートが基準です。リポジトリの外で起動した場合は起動したディレクトリに信頼が紐づき、配下のサブディレクトリ(ネストした別リポジトリを除く)まで及びます。ホームディレクトリで起動したときだけは例外で、信頼は現在のセッション限りとなり、ディスクには保存されません。

よくある質問

/cdでプロジェクトを移動するとadditionalDirectoriesはどうなりますか

/cdで別ディレクトリへ移動すると、settingsのadditionalDirectoriesは移動先の設定値に置き換わります。一方--add-dirや/add-dirで追加したディレクトリは、移動後も保持されます。この挙動はv2.1.246以降のものです。それより前は、/cdしても移動先の設定・hooks・MCPサーバー・Skillsはセッションを再開するまで適用されず、信頼プロンプトにも何が有効化されるかが表示されていませんでした。移動と同時に、移動前のディレクトリのプロジェクトMCPサーバーとローカルスコープMCPサーバーは切断されます。

macOSで~/Desktopなどを追加したときの注意点はありますか

バックグラウンドセッションでは、~/Desktop・~/Documents・~/Downloadsのような保護フォルダへのアクセスを、ターミナルとは別にOSへ要求する必要があります。読み取りがOperation not permittedで失敗する場合は、この権限設定を見直します。

まとめ

Skillsやsubagentsを使い回したいなら、--add-dir・ユーザーレベル設定・プラグインのどれかを選びます。Skillが動かないときは、追加方法と信頼状態から疑います。settings.jsonの全体像はClaude Code settings.json完全ガイド、権限ルールの一覧操作は/permissionsコマンド、フィールドごとの実戦レシピはClaude Code設定ガイドにあります。