ai-tools-kbMarkdown が正

facts ／Gemini CLI ／custom-commands

stable4 日前 · 2026-08-09

Custom commands

概要

よく使うプロンプトを個人のショートカットとして保存・再利用する仕組み。TOML ファイルで定義し、プロジェクト固有にも全プロジェクト共通にもできる。

仕様

場所と優先順位

  1. User commands（グローバル）: ~/.gemini/commands/。どのプロジェクトでも使える
  2. Project commands（ローカル）: <project-root>/.gemini/commands/。バージョン管理に入れてチームと共有できる
  • project ディレクトリのコマンドが user ディレクトリと同名の場合、常に project のコマンドが使われる

命名と名前空間

  • コマンド名は commands ディレクトリからの相対パスで決まる
  • サブディレクトリで名前空間を作る。パス区切り（/ または \）はコロン（:）に変換される
    • ~/.gemini/commands/test.toml → /test
    • <project>/.gemini/commands/git/commit.toml → /git:commit
  • .toml を作成・変更した後は /commands reload で CLI を再起動せずに反映できる。/commands list で全ファイルを確認する

TOML の形式（v1）

  • 必須: prompt（string）— 実行時にモデルへ送られるプロンプト。単一行でも複数行でもよい
  • 任意: description（string）— /help メニューでコマンドの隣に表示される 1 行説明。省略すると、ファイル名から汎用の説明が生成される

引数の扱い

CLI は prompt の内容に応じて自動的に方式を選ぶ。

1. {{args}} によるコンテキスト対応の注入

  • プロンプト本文（シェルブロックの外）: ユーザーが打ったとおりにそのまま注入される
  • !{...} シェル注入ブロックの内側: 自動的に shell-escape されてから置換される。コマンドが構文的に正しく安全になり、コマンドインジェクションを防ぐ

同じプロンプト内で両方に使うと、外側は生のまま、内側はエスケープ済みの値に置き換わる。CLI は実行前にその正確なコマンドの確認を求める。

2. {{args}} が無い場合の既定の扱い

  • 引数を渡した場合: 打ったコマンド全体が、2 つの改行で区切ってプロンプトの末尾に追記される
  • 引数を渡さない場合: プロンプトがそのまま、何も追記されずに送られる

3. !{...} によるシェルコマンドの実行

  • !{...} 構文でシェルコマンドを実行し、その出力をプロンプトに注入する
  • カスタムコマンドがシェルコマンドを実行しようとすると、CLI は事前に確認を求める
  • パーサーは JSON ペイロードのようなネストした波括弧を含む複雑なコマンドも扱える。!{...} の中身は波括弧が釣り合っている必要がある。 釣り合わない波括弧を含むコマンドは外部スクリプトに包んで呼ぶことが案内されている
  • 引数のエスケープと置換の後の最終的なコマンドに対してセキュリティチェックを行い、実行されるコマンドを示すダイアログを出す
  • コマンドが失敗した場合、注入される出力に stderr と [Shell command exited with code 1] のようなステータス行が含まれる

4. @{...} によるファイル内容の注入

  • @{path/to/file.txt} はそのファイルの内容に置き換わる
  • マルチモーダル対応: 対応する画像（PNG、JPEG など）、PDF、音声、動画のパスなら、正しくエンコードされてマルチモーダル入力として注入される。それ以外のバイナリファイルは穏当に扱われてスキップされる
  • ディレクトリ指定: @{path/to/dir} はディレクトリとすべてのサブディレクトリを辿り、各ファイルをプロンプトに挿入する。有効なら .gitignore と .geminiignore を尊重する
  • workspace 対応: 現在のディレクトリと他のワークスペースディレクトリからパスを探す。ワークスペース内であれば絶対パスも使える
  • 処理順序: @{...} のファイル内容注入は、!{...} のシェルコマンドと {{args}} の置換よりも前に処理される
  • パーサーは @{...} の中身（パス）の波括弧が釣り合っていることを要求する

設定

# <project>/.gemini/commands/git/commit.toml → /git:commit
description = "Generates a Git commit message based on staged changes."
prompt = """
Please generate a Conventional Commit message based on the following git diff:

!{git diff --staged}
"""
# <project>/.gemini/commands/review.toml → /review
description = "Reviews the provided context using a best practice guide."
prompt = """
You are an expert code reviewer.

Your task is to review {{args}}.

Use the following best practices when providing your review:

@{docs/best-practices.md}
"""
# ~/.gemini/commands/refactor/pure.toml → /refactor:pure
description = "Asks the model to refactor the current context into a pure function."
prompt = """
Please analyze the code I've provided in the current context.
Refactor it into a pure function.
"""

関連

  • facts/gemini-cli/commands.md
  • facts/gemini-cli/extensions.md
  • facts/gemini-cli/configuration.md
  • facts/gemini-cli/tools.md
  • facts/gemini-cli/skills.md