前半は、Gemini CLI をこれから使う人向けに、設定・指示ファイル・スキルの置き場と呼び方を淡々とまとめます。基本を押さえたいだけなら、ここまで読めば十分です。

後半は、Claude Code と設定を1か所に統一しようとして私がハマった話です。同じことをやろうとしている人や、興味のある人は続けて読んでみてください。

対象は Gemini CLI v0.42 時点。仕様はバージョンで変わるので、最終的には手元でも確認してください。

前半：Gemini CLI の設定・スキルの基本

「設定はどこに書くの」「指示ファイルは GEMINI.md？どこに置くの」「自作スキルはどう呼ぶの」で迷うところを、最小限にまとめます。

全体像

置き場	役割
`~/.gemini/settings.json`	ユーザー設定（ネスト JSON）
`~/.gemini/GEMINI.md`	グローバルな指示ファイル
`~/.agents/skills/<name>/SKILL.md`	自作スキル（`~/.gemini/skills/` でも可）

プロジェクト側に <project>/.gemini/settings.json、リポジトリルートの GEMINI.md、<project>/.agents/skills/ を置けば、そのプロジェクトだけ上書き・追加できます（同名はプロジェクト優先）。

1. 設定ファイル `settings.json`

場所は ~/.gemini/settings.json（ユーザー）と <project>/.gemini/settings.json（プロジェクト）。ドット記法でネストした JSON です。対話中に /settings でも編集できます。よく触るのはこのあたり：

キー	用途
`context.fileName`	読み込む指示ファイル名（後述）
`mcpServers`	MCP サーバー定義
`general.defaultApprovalMode`	`default` / `auto_edit` / `plan`（`yolo` は CLI 専用）
`security.folderTrust.enabled`	フォルダ信頼チェック（オプトイン。既定では無効、`true` で有効化）

2. 指示ファイル（`GEMINI.md`）

AI への恒常的な指示を書くファイルです。既定のファイル名は GEMINI.md。置き場が2種類あり、ここを混同しがちです。

グローバル（全プロジェクト共通）：~/.gemini/GEMINI.md。~/GEMINI.md（ホーム直下）ではありません。
プロジェクト共通：そのプロジェクトのルートディレクトリに置く GEMINI.md（.gemini/ の中ではない）。実行ディレクトリとその親をさかのぼって読まれます。

両方あれば連結され、毎プロンプト送られます。AGENTS.md（複数ツール共通の指示仕様）も使いたいなら settings.json に足します。

{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

注意点：Gemini の上方向スキャンは「信頼ルート」で止まるため、ホーム直下の ~/AGENTS.md は実行ディレクトリによっては読み込まれないことがあります（git リポジトリ内などスキャンが手前で止まるケース）。全プロジェクトで確実に効かせたいなら ~/.gemini/ 直下に置くのが安全です。具体的には ~/.gemini/AGENTS.md を用意し、context.fileName に AGENTS.md を含めておくと、グローバルで確実に読まれます。実際に何が読み込まれているかは /memory show で確認できます（この罠は後半で詳しく書きます）。

3. スキル（自作コマンドのように使える）

たぶん一番知りたいところ。結論から言うと、Gemini CLI のスキルは Claude Code とほぼ同じ感覚で使えます。

実体は SKILL.md 1枚。置き場は ~/.agents/skills/<name>/SKILL.md（または ~/.gemini/skills/<name>/SKILL.md）。frontmatter は最低これだけ：

---
name: my-skill          # ディレクトリ名と合わせる
description: いつ発動してほしいかを具体的に書く（発動トリガになる）
---
本文（やってほしい手順・指示）

呼び方：

/my-skill 引数 と打つと補完に出てきて、実行するとそのスキルが起動し、SKILL.md の内容に沿って引数つきで動きます。
「〜して」と自然言語で頼んでも、description に合致すればモデルが自動でそのスキルを使います。
認識されているかは gemini skills list か /skills list で確認できます（一覧に出て有効状態になっていれば OK。無効化されていたら /skills enable <名前> で戻せます）。

Claude Code で ~/.claude/skills/ に SKILL.md を置くと /名前 で呼べるのと、ほぼ同じ体験です。スキルをスラッシュで呼ぶために特別な変換やコマンド定義を別途用意する必要はありません。SKILL.md を置くだけです。

4. つまずきやすい点

Folder Trust はオプトイン（既定では無効）。settings.json に security.folderTrust.enabled: true を書いて初めて有効になります。なお公式ドキュメント内でも記述が割れていて、設定リファレンスは既定 true、機能解説の trusted-folders ページは「既定で無効・明示的に有効化が必要」。挙動解説側（オプトイン）に従うのが安全です。有効にした状態で信頼していないフォルダを開くと、プロジェクト設定・MCP・指示ファイルの自動読み込みなどがまとめて無効化されます。/permissions で信頼するか、必要なら起動時に --skip-trust。
スキルが出てこないとき：~/.agents/skills/<name>/SKILL.md があるか、gemini skills list（または /skills list）で一覧に出て有効になっているか、Gemini CLI を再起動、を順に確認。
description が薄いと自然言語からの発動精度が落ちます。「どんなときに使うか」を具体的に書くと安定します。

早見表

やりたいこと	置き場	呼び方
共通の指示を持たせる	グローバル＝`~/.gemini/GEMINI.md` ／プロジェクト＝ルートの `GEMINI.md`	毎回自動で読まれる
自作スキルを持たせる	`~/.agents/skills/<name>/SKILL.md`	`/名前` or 自然言語
設定を変える	`~/.gemini/settings.json`	`/settings` でも可

ここまでが基本。Gemini CLI を使うだけならこれで十分です。

後半：Claude Code と設定を統一しようとして苦戦した話

ここからは、Claude Code と Gemini CLI を併用していて「同じ指示・スキルを2回書くのをやめたい」と思った人向けの実録です。

私は仕事で Claude Code、個人開発で Gemini CLI を使っています。同じ共通ルールを CLAUDE.md と GEMINI.md の両方に、便利な自作スキルも両方に……と二重管理していました。これをやめたくて、設定とスキルを ai-config という1つのリポジトリにまとめ、両ツールから symlink で同じファイルを読ませる構成にしました。

考え方自体はうまくいったのですが、見えていなかった落とし穴が2つありました。

つまずき1：「スキル」と「コマンド」を混同していた

私は Claude Code の感覚で、「Gemini もスキルを置けば /名前 で呼べるようにするには、何か変換がいるはずだ」と思い込んでいました。そこで SKILL.md から Gemini 用のコマンド定義（TOML）を自動生成するスクリプトまで自作しました。ところが「いや自動でやってくれるのでは」と思って消し、また戻し……と判断が一周回る無駄をやりました。

実機（対話モード）で確かめて、ようやく腑に落ちました。Gemini CLI には Agent Skill（SKILL.md） と Custom Command（TOML） という別々の機能があり、私はその2つを混同していたのです。そして肝心の結論はシンプルで、Gemini も SKILL.md を ~/.agents/skills/ に置くだけで /名前 で呼べる（Claude とほぼ同じ）。変換スクリプトは丸ごと不要でした。自作した分は全部捨てました。

ちなみに、この2つの使い分けは公式ドキュメントにも明示されていません。だから混同しても無理はない、とは思います（前半に書いたとおり、普通に使うぶんにはスキルだけ覚えれば十分です）。

つまずき2：共通の指示が、たまに効いていなかった

共通ルールは AGENTS.md 1枚にまとめ、Gemini にも読ませているつもりでした。ところが「今日の Gemini、なんか私のルール理解してないな」と感じることが時々ありました。

調べたら、原因がはっきりしました。ホーム直下に置いた ~/AGENTS.md は、Gemini の上方向スキャンが「信頼ルート」で止まる仕様のせいで、git リポジトリの中で起動すると読み込まれていなかったのです（/memory show で実際に確認しました）。Claude 側は仕組み上 cwd に関係なく確実に読めていたので、なかなか気づけませんでした。

解決策は、前半で書いたとおりです。同じ実体を指す ~/.gemini/AGENTS.md の symlink を置いたら、グローバルで確実に読まれるようになりました。/memory show で読み込まれていることも確認済みです。

同じことをやる人へ（教訓）

「スキル」と「コマンド」は別物。混同すると私のように回り道します。普通に使うならスキル（SKILL.md）だけで十分です。
共通指示は ~/.gemini/ 直下に置く。ホーム直下に置くと、起動ディレクトリ次第でサイレントに無視されます。
そして一番効いた教訓。ドキュメントにも AI 本人にも聞くだけで終わらせず、対話モードで実機確認すること。 私は非対話モードで試して結論を間違えました。仕様は古かったり食い違ったりするので、最後は自分の手元で確かめるしかありませんでした。

いま落ち着いた形

最終的に、共有するのは AGENTS.md（指示）と SKILL.md（スキル）の2種類だけ、と線を引きました。この2つを1か所直せば、Claude Code でも Gemini CLI でも効きます。設定ファイル本体（settings.json）はツールごとにスキーマが違うので、ここは共有せず別管理です。

二重管理の不毛さは消えました。ただ、ここに辿り着くまでの回り道のほとんどは、「片方のツールの感覚で、もう片方を推測してしまった」ことが原因でした。2つを1つにまとめる作業は、最後は地味な実機確認の積み重ねだった、というのが正直なところです。

出典は公式 gemini-cli ドキュメント＋自環境（Gemini CLI v0.42）での確認。仕様はバージョン依存です。

Gemini CLIの基本と、Claude Codeと設定を統一して苦戦した話