やりたいこと
月次の売上集計、請求書の突き合わせ、議事録の整形——毎月ほぼ同じことを頼んでいる。そのたびにプロンプトを書き直すのをやめたい。
書き直しをやめたい理由は手間だけではありません。毎回文言が違うと、毎回結果が違います。 そして担当者が変わると、その人が何をどう頼んでいたのかが誰にも分かりません。定型業務のプロンプトは、口頭のノウハウではなくファイルにすべきものです。
素朴にやると穴が空く
穴1: 呼んだターンしか許可が効かない
いちばん最初にぶつかるのがこれです。コマンドに allowed-tools を書くと、そのツールを確認なしで使えます。ただし解除されるのが早い。
列挙したツールを、その skill を呼んだターンの間だけ許可なしで使えるようにする。次のメッセージ送信で解除され、再度呼ぶとそのターンに再適用される
つまり /monthly-report を呼んだ最初の応答では確認なしに動き、続けて「じゃあ 3 月分もお願い」と言った瞬間から確認を求められます。 「1 回目は動いたのに 2 回目から止まる」の正体はこれです。
セッション全体で効かせたいなら、allowed-tools ではなく permission 設定に allow ルールを書く必要があります。
穴2: 直しても、そのセッションでは古いまま
Claude Code は後のターンで skill ファイルを再読み込みしません。 呼び出した時点の内容が会話に入り、セッションの残りの間そこに留まります。
ファイルを編集する仕組み（live change detection）はありますが、対象は SKILL.md のテキストだけです。しかも:
- セッション開始時に存在しなかったトップレベルの skills ディレクトリを新規に作った場合は再起動が必要
- 同梱の
hooks/や.mcp.jsonなどの変更は/reload-pluginsが必要
Gemini CLI は .toml を変更した後に /commands reload で反映できます。Codex は変更を自動検出しますが、反映されないときは再起動、と案内されています。
「直したのに直っていない」ときは、まず読み込み直してください。
穴3: 名前が衝突すると黙って片方が勝つ
Claude Code では custom commands が skills に統合されました。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作ります。 両方あると skill が優先されます。
エラーにはなりません。古い commands/ を残したまま skill を作ると、編集しているファイルと動いているファイルが別物になります。
穴4: description が悪いと、勝手に呼ばれるか、一度も呼ばれない
AI 側が自動で呼ぶかどうかは description の一致で決まります。ここが雑だと両方向に失敗します。
Codex にはもっと厳しい制約があります。
この初期リストはモデルのコンテキストウィンドウの最大 2%、コンテキストウィンドウが不明な場合は 8,000 文字を使う
上限に当たると description が短縮され、それでも多い場合は一部の skill が初期リストから省かれて警告が出ます。 つまり skill を増やすほど、個々の説明が削られていきます。
対策は出典に明記されています。主要なユースケースとトリガー語を先頭に置くこと。短縮されても残る位置に、判断材料を置きます。
穴5: 引数の扱いが 3 ツールでばらばら
| ツール | 記法 | 引数を書かなかった場合 |
|---|---|---|
| Claude Code | $ARGUMENTS / $1 / $name | 本文末尾に ARGUMENTS: <入力> が追記される |
| Gemini CLI | {{args}} | コマンド全体が 2 つの改行区切りでプロンプト末尾に追記される |
| Codex | SKILL.md の指示に従う | — |
Claude Code で気をつける点:
- 対応する引数が無いインデックス（引数 1 つで
$2）は、空にならず本文にそのまま残る - 対応する引数が無い名前付きプレースホルダは空文字列になる
- 金額を書くときの
\$1.00のようなリテラルの$はバックスラッシュでエスケープが要る
Gemini CLI で気をつける点:
{{args}}はプロンプト本文では生のまま、!{...}シェルブロックの内側では自動的にエスケープされてから置換される- 処理順序は
@{...}（ファイル注入）→!{...}（シェル）と{{args}}
手順
1. まず手でやって、うまくいった文面をそのまま保存する
いきなりコマンドを設計しないでください。1 回手で通して、望む結果が出た指示をそのままファイルにするのが確実です。
2. 置き場所で「誰のものか」を決める
| 範囲 | Claude Code | Gemini CLI | Codex |
|---|---|---|---|
| 自分だけ・全案件 | ~/.claude/skills/<名前>/SKILL.md | ~/.gemini/commands/<名前>.toml | user スコープ |
| チームで共有 | .claude/skills/<名前>/SKILL.md（コミットする） | <project>/.gemini/commands/<名前>.toml（コミットする） | $CWD/.agents/skills |
| 組織全体に配布 | managed settings | — | admin / system スコープ |
プロジェクト側が優先されるのは 3 ツールとも共通です（Claude Code の skill は enterprise > personal > project の順で上書きされる点だけ逆なので注意）。
Gemini CLI はサブディレクトリが名前空間になります。commands/monthly/sales.toml → /monthly:sales。定型業務が増えてきたら部署や月次・週次で切ると探しやすくなります。
3. 毎回同じ材料を自動で挟む
定型業務のプロンプトには「毎回同じ資料を見せる」部分があります。ここは手で貼らずに埋め込めます。
Gemini CLI（TOML）:
# <project>/.gemini/commands/monthly/report.toml → /monthly:reportdescription = "月次レポートの下書きを作る。数値は data/ の CSV から取る"prompt = """以下の集計ルールに従って、{{args}} 月の売上レポートを作ってください。
集計ルール:@{docs/集計ルール.md}
対象データの一覧:!{ls -la data/}"""@{...} はファイル内容を、!{...} はシェルコマンドの出力をプロンプトに差し込みます。!{...} は実行前に必ず確認ダイアログが出ます（エスケープと置換の後の最終的なコマンドが表示されます）。
Claude Code（SKILL.md）:
---description: 月次売上レポートの下書きを作る。「月次レポート」「今月の売上まとめ」と言われたときに使うargument-hint: [対象月 例:2026-08]allowed-tools: Read, Glob---
## 対象データ
!`ls -la data/`
## 手順
1. data/ 配下の $1 月分の CSV を読む2. docs/集計ルール.md に従って集計する3. 前月比を添える!`command` は内容が Claude に送られる前にシェルコマンドを実行して、出力で置き換えます。置換は 1 回だけ走り、出力はプレーンテキストとして挿入されるので、出力の中身がさらにコマンドとして解釈されることはありません。
! が認識されるのは行頭または空白の直後にあるときだけです。KEY=!`cmd` はリテラルとして残り、実行されません。
4. 事故を起こしうるコマンドは自動で呼ばせない
請求処理や公開操作のように、AI の判断で勝手に始まっては困るものがあります。
---description: 月次請求書を発行するdisable-model-invocation: true---disable-model-invocation: true を付けると、description がコンテキストに入らなくなり、AI 側からは呼べなくなります。人間が / で呼んだときだけ動きます。Claude が呼ぼうとした場合はブロックされ、手順を別の方法で再現しないよう指示されます。
逆に user-invocable: false はメニューから隠すだけで、Skill ツール経由のアクセスは止めません。 隠す ≠ 止める、を混同しないでください。
5. 長い手順書は分割する
SKILL.md は 500 行未満に保ち、詳細は補助ファイルへ移すよう案内されています。SKILL.md からは「どのファイルに何が入っていて、いつ読むか」を参照する形にします。
確認方法
# 1. 意図したファイルが動いているか（穴3）/help または /skills でコマンド一覧を出し、同名が 2 つ無いか見る
# 2. 引数が届いているか（穴5）コマンドに「受け取った引数をそのまま復唱してください」と一時的に書いて呼ぶ
# 3. 直したものが反映されているか（穴2）説明文に日付を書いて呼び、その日付が出るか見るGemini CLI には /commands list があり、全ファイルを確認できます。
残る限界
allowed-toolsはターン限定。 毎回確認を消したいなら permission 設定側の作業になり、そちらは安全性の判断を伴う- Claude Code は skill を後から再読み込みしない。 長いセッションの途中で直しても、その会話には反映されない
- Codex の初期リスト予算（2% / 8,000 文字）は skill を増やすほど厳しくなる。**「作れば作るほど呼ばれにくくなる」**という性質がある
- auto-compaction で skill が落ちることがある。再アタッチは各 skill の先頭 5,000 トークンまで、合計 25,000 トークンの予算を共有し、最近呼んだものから埋まる。長い会話では古い skill が丸ごと落ちる
根拠
facts/claude-code/skills.md— frontmatter、コマンド名の決まり方、文字列置換、allowed-toolsの有効範囲、dynamic context injection、再読み込みしない仕様facts/gemini-cli/custom-commands.md— TOML 形式、名前空間、{{args}}のエスケープ規則、!{...}と@{...}、処理順序facts/codex/skills.md—.agents/skillsの走査、初期リストのコンテキスト予算、description の書き方