Rules と Skills のどちらに書くか迷ったとき — 指示の置き場所を決め直しました

受託でお預かりしているサイトのレビューを見返していた夜、エージェントが色の直値をそのまま書き込んでいるのに気づきました。ワークスペースの規約には「色はトークンを参照する」と書いてあります。

探してみますと、同じ注意書きが二か所にありました。ひとつは規約のファイル、もうひとつは納品前チェックの手順書です。少し前に規約のほうだけを書き直しており、手順書には古い文言が残っておりました。

エージェントが読んだのは、古いほうでした。

原因は指示の中身ではありませんでした。置き場所を決めていなかったことに気づいたのは、二つのファイルを並べて見比べたあとでした。Antigravity には「毎回効かせたい指示」と「呼んだときだけ辿らせたい指示」とで、別々の入れ物が用意されています——そして二つは、載るタイミングがまったく違うのです。

二つの入れ物は、載るタイミングが違います

Rules は、エージェントに守らせる制約を書く場所です。グローバルのものは ~/.gemini/GEMINI.md に置き、すべてのワークスペースへ適用されます。ワークスペース固有のものは、ワークスペースまたは git のルートにある .agents/rules フォルダへ置きます。1 ファイルあたり 12,000 文字が上限です。

Rules には活性化の指定があり、四つから選べます。手動（入力欄で @ を使って呼ぶ）、常時オン、モデル判断（自然言語の説明を読んでモデルが適用を決める）、そして glob（*.js や src/**/*.ts に一致するファイルへ適用）です。

Skills は、手順や知識をひとまとまりの資産として置く場所です。ワークスペースなら .agents/skills/<名前>/SKILL.md、グローバルなら ~/.gemini/config/skills/<名前>/SKILL.md に置きます。1 枚のファイルではなくフォルダですので、scripts/ や examples/ を隣に並べられます。

いちばん効いてくる違いは、読み込まれ方です。Skills は段階的な開示という仕組みで動きます。会話が始まった時点でエージェントが見るのは、名前と説明だけです。関係がありそうだと判断したときに初めて、本文が読まれます。

項目	Rules	Skills
ワークスペースの置き場所	`.agents/rules/<名前>.md`	`.agents/skills/<名前>/SKILL.md`
グローバルの置き場所	`~/.gemini/GEMINI.md`	`~/.gemini/config/skills/<名前>/SKILL.md`
形	1 枚の Markdown	フォルダ（`SKILL.md` ＋付属物）
読み込まれ方	有効なら毎ターン全文	見出しが先・本文は必要になってから
呼び出し	@ 参照／常時オン／モデル判断／glob	`/名前` またはエージェントの判断
大きさの制約	1 ファイル 12,000 文字	分割できるため実質の上限なし

置き場所について、ひとつ補足がございます。いまの既定は .agents ですが、旧来の .agent も後方互換として読まれます。両方が残っているワークスペースでは、どちらが読まれているのかを一度確かめておくと安心です。

破られたら困るものと、忘れられたら困るもの

仕分けの問いは、私の場合ひとつに落ち着きました。

破られたら困るものは Rules に、忘れられたら困るものは Skills に。

破られたら困るものというのは、順番を持たない禁止や約束です。「本番のデータベースに接続する設定を新しく足さない」「色の直値を書かない」「git push --force は実行せず提案までにとどめる」——いずれも「いつ」ではなく「常に」の話ですので、常時オンの Rules が合います。

忘れられたら困るものは、手順のほうです。納品前にリンク切れを洗い、画像の幅と高さを確かめ、書き出したレポートを所定の場所へ置く。順番があり、抜けると困り、けれども毎回必要なわけではありません。こちらは Skills です。

判断に迷うものも、もちろんあります。たとえば「CSS を触るときだけ効かせたい表記規則」がそうです。常時オンにすると関係のない作業にも載りますし、Skills にすると呼ばれないことがあります。

ここは Rules の glob 活性化がちょうど間に立ってくれます。*.css に一致したときだけ適用されますので、持ち出しを増やさずに済みます。Rules か Skills かの二択ではなく、活性化の指定まで含めて三段で考えるようにしてから、迷う時間がはっきり減りました。

毎ターンの持ち出しを、一度測っていただきたいのです

頭で分かっていても、実際にどれだけ載っているのかは数えないと見えません。手元で走らせる小さなスクリプトを書きました。

#!/usr/bin/env bash
# instruction-budget.sh — 毎ターン載る指示と、必要になったときだけ載る指示の量を並べます。
# 使い方: ./instruction-budget.sh [ワークスペースのルート]
set -euo pipefail
ROOT="${1:-.}"
RULES_DIR="$ROOT/.agents/rules"
SKILLS_DIR="$ROOT/.agents/skills"
 
# .agents が無いワークスペースでは、後方互換の .agent を見に行きます。
[ -d "$RULES_DIR" ]  || RULES_DIR="$ROOT/.agent/rules"
[ -d "$SKILLS_DIR" ] || SKILLS_DIR="$ROOT/.agent/skills"
 
rules_total=0
echo "== Rules（有効なものは毎ターン載ります） =="
while IFS= read -r -d '' f; do
  n=$(wc -m < "$f" | tr -d ' ')
  printf '  %-28s %6s 文字\n' "$(basename "$f")" "$n"
  rules_total=$((rules_total + n))
  # 1 ファイル 12,000 文字が上限です。超えた分は読まれない可能性があります。
  [ "$n" -gt 12000 ] && echo "     ⚠ 12,000 文字の上限を超えています"
done < <(find "$RULES_DIR" -maxdepth 1 -name '*.md' -print0 2>/dev/null | sort -z)
 
meta_total=0
body_total=0
echo "== Skills（先に載るのは見出しだけです） =="
while IFS= read -r -d '' f; do
  body=$(wc -m < "$f" | tr -d ' ')
  # 先頭の --- から次の --- までが、会話開始時に索引される部分です。
  meta=$(awk '/^---[[:space:]]*$/{c++; next} c==1{print} c>1{exit}' "$f" | wc -m | tr -d ' ')
  printf '  %-28s 見出し %4s 文字 / 本文 %6s 文字\n' \
    "$(basename "$(dirname "$f")")" "$meta" "$body"
  meta_total=$((meta_total + meta))
  body_total=$((body_total + body))
done < <(find "$SKILLS_DIR" -mindepth 2 -maxdepth 2 -name 'SKILL.md' -print0 2>/dev/null | sort -z)
 
echo "---"
echo "毎ターンの持ち出し : Rules ${rules_total} 文字 ＋ Skills の見出し ${meta_total} 文字"
echo "呼ばれたときだけ   : Skills の本文 ${body_total} 文字"

規約 2 枚と Skills 2 つだけを置いた小さなワークスペースで走らせますと、次のように出ます。

== Rules（有効なものは毎ターン載ります） ==
  house-style.md                  156 文字
  no-destructive-ops.md           104 文字
== Skills（先に載るのは見出しだけです） ==
  imageset-build               見出し  101 文字 / 本文    266 文字
  release-check                見出し  101 文字 / 本文    313 文字
---
毎ターンの持ち出し : Rules 260 文字 ＋ Skills の見出し 202 文字
呼ばれたときだけ   : Skills の本文 579 文字

この規模では差はほとんどありません。ここだけを見て「たいした話ではない」と思われるかもしれません。大事なのは数字そのものではなく、毎ターンの持ち出しと呼ばれたときだけの二段に分かれて見えることです。Rules を一枚足すと前者がまるごと増えます。Skills を一つ足しても、増えるのは見出しの分だけです。この非対称は、ファイルが育つほど効いてきます。

私自身、最初のうちは何でも Rules に書き足しておりました。確実に効かせたかったからです。結果は芳しくありませんでした。関係のない作業にも規約が全部載り、いちばん守ってほしい一行が埋もれてしまったのです。

なお、規約ファイルそのものを分割すれば済むと考えたこともあります。ただ、分割で減るものと減らないものは別でした。そのあたりは@ 取り込みで規約ファイルを分けたとき、何が減って何が減らないかに実測とともに書いております。

Workflows は 11 月 1 日で終わります

いま仕分けを見直しておきたい理由が、もうひとつございます。従来の Workflows が非推奨となり、2026 年 11 月 1 日に廃止されることが公式ドキュメントに明記されました。それまでは動きますが、以後はスラッシュコマンドからも索引からも外れます。

移行そのものは重くありません。Antigravity 2.0 で次のコマンドを実行しますと、グローバル（~/.gemini/config/workflows/）とワークスペース（.agents/workflows/）の両方が走査されます。

/migrate-workflows

それぞれが .agents/skills/<名前>/SKILL.md として作り直され、元のファイルには .bak が付いて退避されます。同じ名前の Workflow と Skill が並んだ場合は、Skill のほうが優先されます。

ただ、機械的に移すだけですと、ひとつ取りこぼします。説明文です。

Workflows には 12,000 文字の上限がありましたので、私は説明を削って手順を詰め込んでおりました。ところが Skills では、その説明こそがエージェントの判断材料になります。会話の冒頭で読まれるのは名前と説明だけですので、説明が薄いと呼ばれないのです。

移行したあとは、説明を書き直してください。「何をするか」と「いつ使うか」を、三人称で具体的に書きます。

# 呼ばれにくい説明
description: リリースの確認をします。
 
# 呼ばれる説明
description: 納品前のサイトを検査して、リンク切れ・画像の欠落・メタタグの不足を一覧にします。受託サイトを引き渡す前や、本番へ反映する前に使います。

移行の直後にひとつだけ確かめるとすれば、.bak の付いた元ファイルが残っているかどうかです。残っていれば、書き直しに失敗しても戻せます。

迷ったときの三つの問い

いま私は、指示をひとつ書くたびに三つだけ自分に尋ねております。

これは順番のある話でしょうか。順番があるなら Skills です。
破られたときに、作業をやり直すことになるでしょうか。なるなら Rules の常時オンです。
特定の種類のファイルを触るときだけの話でしょうか。そうなら Rules の glob です。

三つとも当てはまらないものは、振り返ってみますと、たいていどこにも書かなくてよい指示でした。個人開発で壁紙の素材処理を回している側でも同じで、置き場所を決めないまま書き足した注意書きは、半年後にはほとんど読まれておりませんでした。

まずは .agents/rules のファイルを数えるところから始めていただければと思います。上のスクリプトでも、wc -m .agents/rules/*.md の一行でも構いません。数字が見えてくると、どれを Skills へ移すかは自然と決まってきます。

置き場所を決めてから、指示を書く。 指示が増えるほど、この順番のほうが効いてくると感じております。お読みいただきありがとうございました。