SKILL.md は 220 行で切られる前提で書く — auto-publish 再設計の運用記録

結論

SKILL.md を書くときの正しい前提は「Codex CLI も Claude Code も、長いファイルの末尾までは読まない」です。haru0416 さんが Zenn で公開した観測記事で、Codex CLI が 441 行の SKILL.md を先頭 220 行で打ち切って読み込んでいた、という実コマンドログを見て、私は AetherEchoes の auto-publish で全く同じ事故を踏み続けていたことに気づきました。

本稿は、その観測をきっかけに 6 スキル（article-pick / article-write / article-verify / article-video / breaking-content / カテゴリ別 content スキル）を書き直したときに採用した 5 つの指針を、2026-05-20 18

から 2 日間 breaking スロットが pick で止まっていた事故の振り返りと並べてまとめる運用記録です。

haru0416 さんの観測 — Codex CLI は SKILL.md を最後まで読んでいない

事の発端は、Zenn に出た「Codex CLI で SKILL.md ファイルがどう読まれているか」を実コマンドログで追った観測記事でした。441 行の SKILL.md のうち、Codex CLI が context に入れたのは先頭 220 行までで、後半 221 行は一度も読まれていなかった、という結論です。

これは「LLM 自体のコンテキスト窓が足りない」という話ではなく、ツール側が「skill 読み込みに割く tokens の上限」を勝手に決めていた、という話でした。実装は「ファイルを一定行数でチャンクして、最初のチャンクだけ context に積む」程度のシンプルなルールで動いている、という仮説が立てられていました。

私はこれを読んで頭を抱えました。私の auto-publish の SKILL.md は、breaking-content/SKILL.md だけで 380 行、article-write/SKILL.md も 280 行ほどあって、それぞれの 末尾に「終了の鉄則」「やってはいけないこと」 という最重要ルールが置いてあったからです。末尾に重要ルールを置く設計は、人間向けの README としては許容範囲ですが、AI エージェント向けの skill としては事実上「読まれない場所に書いた」のと同じでした。

auto-publish で同じ事故が起きていた

2026-05-20 18

の breaking スロットで、/breaking-content が launchd 経由で起動したのに、2 日連続で pick.json が mode: skip のまま終わっていた事故がありました。launchd は走っているのにサイトに記事が出ない、というやつです。

ログを追うと原因は分かりました。breaking スキルの SKILL.md 末尾に書いていた「該当トピックが無い場合は exit 0 で skip して write.json を書き出さない」というルールが Claude に読まれておらず、Claude は途中で「何か書かないといけない」と判断して 422 エラーが返るトピックを掴み、リトライ上限まで来て止まる、という挙動を 2 回繰り返していました。

このとき私は、終了条件を末尾に書いた自分が悪いのか、Claude のスキル読み込み深度が浅いのが悪いのか、をしばらく悩みました。そして観測記事を読んだ翌朝、答えは前者だと腹を括りました。私が制御できるのは SKILL.md の書き方の方しかなく、Claude の読み込み深度を変える力は私には無い、というのが現実です。

5 つの設計指針に絞り直した

書き直しの基準として、以下の 5 つを採用しました。順序が指針の優先度です。

1. 1 SKILL.md = 200 行以内 に収める。超えそうなら共通ロジックを別ファイルに逃がす。
2. 鉄則・終了条件は冒頭 に置く。## 🚨 設計の鉄則 (最初に読む) のような見出しを最初の h2 に取る。
3. 共通ロジックは SHARED_LOGIC.md に集約 する。各スキル冒頭で「必ず Read」と明示し、本文はカテゴリ固有の判断だけにする。
4. read 順序を意識して書く。最初に読ませたいルールほど上、参考情報・トラブルシュートは下。
5. 段階分割（pick / write / verify / video） を維持する。1 セッションで 1 ファイル 1 段階だけ読めば動く、という単位を崩さない。

特に効いたのは 1 と 3 でした。breaking-content/SKILL.md は 380 行から 180 行に縮み、削った Bot API endpoint 一覧 / 重複検出ルール / 品質判定基準は doc/auto-publish/SHARED_LOGIC.md に移しました。SHARED_LOGIC.md 自体は 300 行ほどありますが、これは「各スキルが着手前に明示的に Read する」前提のドキュメントなので、SKILL.md とは扱いが違います。

5 番目の段階分割は haru0416 さんの観測記事とは独立の話ですが、書き直すときに副次的に効きました。article-write/SKILL.md を 280 行から 220 行（ぎりぎり！）に縮め、article-pick article-verify article-video を別 SKILL に切り出した結果、1 セッションあたりに Claude が読む SKILL.md の総量が 1/3 になりました。

段階分割を維持する理由を再確認する

別 SKILL に分けると claude -p を 4 回起動することになり、当然ながら起動オーバーヘッドが増えます。それでも分ける理由は、1 段階で失敗したときの再実行コストが小さくなるからです。

たとえば article-video が YouTube upload で 7 日 refresh_token 失効に当たった場合、article-write の draft 作成からやり直す必要は無く、article-video だけ再実行すれば済みます。1 つの SKILL.md に全部詰めていた頃は、ここでセッション全体を巻き戻すか、Claude に「draft はもう upsert 済みだから skip して、video だけやり直して」と毎回口で説明していました。私のあの時間は何だったのか、と思います。

まとめ

SKILL.md は 220 行で打ち切られる前提で書く、という制約を受け入れたら、私の auto-publish はだいぶ静かに動くようになりました。終了条件を冒頭に持ってきただけで、breaking スロットの 2 日 stuck は再発していません。

書き手の側の制約として捉えるなら、AI エージェント向けの設計書は「人間が読む技術文書」とは違う書き方を要求していて、その第一歩が「読まれない末尾を作らない」だと思います。haru0416 さんの観測が無ければ、私はもう少し長い間「Claude が末尾を無視している」と Claude のせいにし続けていたはずです（過去の私への弁明として書いておきます）。

並列度の問題については 並列 AI エージェントと人間の脳みそ 1 個問題 に別軸で書いたので、auto-publish の運用上のもう一つの背骨として合わせて読んでもらえると、私の試行錯誤の全体像が見えるかもしれません。