自分で書いた SKILL.md を、エージェントは本当に最後まで読んでいるのか。これは私もずっと曖昧にしていた問いでした。4 つの技術ブログの記事生成スキルを書いていると、SKILL.md がどんどん長くなります。注意事項、禁止パターン、品質ゲートの説明、他スキルとの連携手順。気づけば 1,000 行を超えていました。そこに、ある観測記事が刺さりました。
Codex CLI が SKILL.md を読むとき、ログを追うと sed -n '1,220p' という形のコマンドが並んでいた、という観測です。441 行のスキルなら、後半の 221 行は出力に含まれません。しかも複数タスクを通すと、読み取りの最も深い行がきっかり 220 前後に揃っていた、という再現性のある話でした。これは「自分が書いたつもりの SKILL.md と、エージェントが実際に読む SKILL.md は別物かもしれない」という、運用者には無視できない指摘です。
なぜ220行で止まるのか
最初は CLI のバグを疑いたくなります。でも観測の結論はそうではありませんでした。Codex CLI にはファイル読み取り専用のツールがなく、ファイルを読むことはシェルコマンドを生成して実行することと同義です。だから自然言語でスキルを選ばせた経路では、「SKILL.md の本文を読む」が「sed を打つ」になります。そして sed -n '1,220p' という文字列は、ハーネスではなくモデルが組み立てたものでした。
ではなぜ毎回 220 付近なのか。観測者の見立ては「220 はモデルが想定している SKILL.md の長さ」というものです。一般のコードファイルを読むときは行数がばらつきますが、スキルを読むときのモデルの状況は一種類しかありません。Agent Skills の標準は本文を短く保つ設計で、長い仕様やサンプルは references/ に逃がし、SKILL.md 本体には「いつ使うか」「どう進めるか」だけを書きます。仕様どおりに書かれた SKILL.md はだいたい 200 行に収まる。だから「まともなスキルの長さ + 少しの余白」が 220 あたりに出てくる、という解釈です。
重要なのは、これが「220 行で打ち切れ」という上限の指示ではなく、モデルにとっての「SKILL.md を 1 本まるごと読む」イディオムだという点です。仕様どおりに短く書かれていれば、220 行でも全文読めています。問題が出るのは、想定の長さを超えたスキルだけです。
ハーネスによって挙動が変わる
ここは誤解しやすいので補足します。この打ち切りは、すべての環境で起きるわけではありません。skill ツール呼び出し型のハーネス、つまり Claude Code のように本文をハーネス側が事前に丸ごと読み込んでモデルに渡す経路では、sed の出番がないため、この上限が表に出ません。観測でも、Claude Code 経路では 441 行のスキルが毎回 441 行で配信されていた、とされています。
つまり問題の核は「Codex というツール」ではなく、「ファイルを読むならモデル自身がシェルコマンドを書く」というアーキの形にあります。自分のスキルを Codex を含む複数のエージェントに横断利用させたいなら、最も保守的な前提に合わせて書くのが安全です。そしてその保守的な前提とは、結局「SKILL.md は短く」という、もともとの仕様が言っていたことそのものでした。
何が後半に置かれがちか
私が自分の SKILL.md を見直して冷や汗をかいたのは、まさに後半に置いていた内容です。観測記事でも、220 行より後ろに置かれていたのは anti-patterns、想定される逸脱（drift）のパターン、stop condition、他スキルとの連携手順だった、と指摘されています。要するに「こう雑になるな」「ここまで来たら止まれ」という、いちばん指示の強い部分です。
これは皮肉な構造です。エージェントを止めたり軌道修正させたりするための記述ほど、安全のために後ろにまとめたくなります。でもその「止めろ」の側こそ、後半に置くと読まれない。私の記事生成スキルでも、品質ゲートの禁止パターンや push 直前チェックを末尾に固めていたので、横断利用の文脈では同じ穴に落ちていた可能性があります。
200行以内に収める書き方
直す方向は、ツールを変えることではなく、モデルの前提に合わせることです。観測値そのものは 220 でしたが、マージン込みの数字なので、自分で上限を引くなら 200 に取るのが安全だと私も考えています。具体的には次の 3 点です。
- SKILL.md 本体は 200 行以内に収める
- Iron Law（絶対則）・使う場面・コア手順・最小限の例は、最初の 200 行に必ず入れる
- 長い例・anti-patterns・参照ドキュメントは references/ に退避する
references/ への退避は、単に行数を削るためではありません。progressive disclosure（段階的開示）の考え方そのものです。起動時に読み込まれるのは各スキルの名前・説明・パスだけで、本文はそのスキルを使うと決めたときに読まれます。さらに細かい仕様は、必要になったエージェントが references/ を個別に読みにいきます。本体に「いつ・どう」を、references/ に「詳細」を置くと、この開示の流れに自然に乗ります。
私自身、個人開発で 4 つの技術ブログを一人で回す中で、運用スキルを「本体は判断と手順、詳細ドキュメントは別ファイル」に分け直しました。すると、スキルが意図どおりに発火しやすくなった実感があります。2014年からアプリを作り続けてきた感覚として、ドキュメントは育てるほど長くなるものですが、1,000 行の本体に全部を詰め込んでいた頃は、肝心の禁止パターンが効いていない記事が混ざることがありました。
今日できる確認
もし手元に長い SKILL.md があるなら、まず本体の行数を数え、200 行を超えているなら「最初の 200 行に Iron Law と stop condition が入っているか」を確認してみてください。入っていなければ、その部分を冒頭へ繰り上げ、長い例や anti-patterns を references/ に移すところから始められます。
書いた SKILL.md と、エージェントが実際に読む SKILL.md が同じ長さでないかぎり、両者は別の文書です。この前提を踏まえて、テンプレートと判断基準で出力を安定させる具体的な設計は、効くスキルの設計 — テンプレート固定と判断基準で出力を安定させるで掘り下げました。スキルではなくスクリプトでオーケストレーションする選択肢については、Dynamic Workflow を動かして掴んだサブエージェント並列実行の勘所が参考になるはずです。
最後までお読みいただき、ありがとうございました。