言うことを聞かないCodexの調教法

「マジでCodexルールガン無視なの何とかならんのかな」

俺のかなり親しいXのフォロワーさんが、以前からこんな感じでぼやいている。

分かる。ルールを書いた。念も押した。なのに次のtaskでは、まるで初見の資料みたいな顔で読み流す。こちらが「そこ、一番大事なところなんだけど？」と画面へ話しかけるところまでがワンセットになる。AI相手なのに、なぜか生活指導の先生みたいな気分になるやつだ笑。

ただ、ここで「あなたのルールの書き方が悪い」と採点する話にはしたくない。彼の困り方は、まさにこの記事を読んでほしい人の困り方だからだ。

管理人

僕の環境ではあんまり　ルールガン無視ってないからなぁ・・

では、俺が毎回ものすごく丁寧なプロンプトを書き、監査skillの名前を全部唱えているのか。

いや、そんな面倒な運用はしていない。既存のルール自体を強くするskillを先に入れ、その後はtaskの内容に合わせてcreator、clarifier、validatorが自動で選ばれ、必要な完成条件まで流れるように仕込んでいる。

この記事では複雑な仕組みを最後まで引っ張らない。まず、結局何を入れて、何を頼めばいいのかを全部見せる。その完成形を見てから、一つずつ箱を開けていこう。

>>>Amazonのお得な最新の情報はここ

サーバー管理者歴17年の筆者が選んだレンタルサーバーはここ

先に結論。まず2つのclarifierを入れる

Codexへ書いた既存ルールを強化したいなら、最初に入れるのは次の2つだ。

• agents-md-clarifier
• skill-md-clarifier

この2つは、俺のCodex運用では便利な補助Toolという位置づけではない。

俺のシステムの中枢にあって、なくてはならない強力な継続保守skillだ。

管理人

強力なスキルって書いておけ笑　実際に強力すぎる　俺のシステムの中枢になくてはならないスキルだからなこの２つ。

じぴこ

そこまで言い切りますか、マスター。

管理人

実際に公開したくないレベルのスキルだ。

じぴこ

公開したくないもののGitHubリンクを、記事の一番上へよくもまぁ二本並べましたね笑。

万能だからではない。Codexがルールを「参考になる文章」として眺め、都合よく省略する余地を、俺の環境ではこの2つがかなり強く削ってくれたからだ。

役割はこう分かれる。

agents-md-clarifierは既存AGENTS.mdを直接強化する

AGENTS.mdは、Codexへ「この範囲ではどう動くか」を常設するファイルだ。しかし、内容が助言集のように書かれていると、読んではいても実行上の拘束が弱くなりやすい。

agents-md-clarifierは、既存のAGENTS.mdを読んで感想を返すだけではない。対象にSSOTまたは同等の実行契約宣言がなければ、細かなルールを締めるより先に、そのスコープの正本であることを明示する。さらに「できれば」「必要に応じて」「推奨」といった逃げ道を、発動条件、順序、必須結果、狭い例外が分かる運用文へ直す。

グローバルなら全taskへ効く唯一のユーザー所有原本として、プロジェクト内ならそのディレクトリ範囲のローカルSSOTとして整える。既存の同等宣言があれば、SSOT札を何枚も貼って賑やかにすることはない。

skill-md-clarifierはSKILL.mdを二方向から強化する

skill-md-clarifierは、SKILL.mdを単なる手順書ではなく、Codexが選択して実行できる局所契約へ変える。

一方向はroutingだ。descriptionへ、何をするskillなのか、どんな依頼で使うのか、何を対象にし、どこから先は扱わないのかを入れる。これが曖昧だと、良いskillでも必要なtaskで選ばれない。

もう一方向は、選ばれた後の実行契約だ。正本、入力、出力、担当、順序、停止条件、validatorとの境界を明確にする。対象SKILL.mdに局所実行契約の宣言がなければ先に補い、「使ってもよい」を「この条件なら使う」、「適宜確認」を「Aの後、Bの前に確認する」のように締める。

つまり、選ばれやすくするだけでも、選ばれた後に根性で頑張らせるだけでもない。入口と中身の両方を直すskillだ。

GitHubからUSER scopeへ導入する

CodexのUSER scopeに置くstandalone skillの場所は、現在の公式案内では $HOME/.agents/skills だ。インストールをCodexへ任せるなら、新しいtaskでこう頼めばいい。

次の2つの公開skillを、CodexのUSER scope
$HOME/.agents/skills へインストールして。

https://github.com/mlabo-org/agents-md-clarifier
https://github.com/mlabo-org/skill-md-clarifier

手元で直接配置するなら、次の2本でもよい。

git clone https://github.com/mlabo-org/agents-md-clarifier.git ~/.agents/skills/agents-md-clarifier
git clone https://github.com/mlabo-org/skill-md-clarifier.git ~/.agents/skills/skill-md-clarifier

Codexは新しく入ったskillを検出する。表示されない場合はCodexを再起動し、インストール作業をしていた会話へ居残るのではなく、新しいtaskから始める。

初回強化も手書きしない

ここが大事だ。読者の既存AGENTS.mdを強くする方法を説明しておきながら、「ではこの長いルールを手で全部書いてください」では、たぶん誰もやらない。俺もやりたくない笑。

2つを入れた直後の初回実行では、まだ自動選択の土台そのものを整えている途中だ。ここではskill名を省略せず、既存AGENTS.mdへこう頼む。

agents-md-clarifierを使って、
既存のAGENTS.mdを、Codexが参考資料として読み流せない
SSOT実行契約へ強化して。
弱い文言、曖昧な発動条件、順序、完成条件も修正して。

既存SKILL.mdにも、初回はskill-md-clarifierを名指しする。

skill-md-clarifierを使って、
既存のSKILL.mdを、Codexが正しいtaskで自動選択できる
局所実行契約へ強化して。
description、routing、弱い文言、停止条件、validator境界を整えて。

初回は必ず、このように個別のskill名を宣言して使わせる。インストールしただけの段階で「descriptionが合うから、もう名指ししなくても動くはず」と話を飛ばすと、初見ユーザーには導入失敗と自動選択失敗の区別がつかない。

agents-md-clarifierでAGENTS.mdのSSOTと完成条件を強化し、skill-md-clarifierでSKILL.mdのdescriptionと局所実行契約を整える。そこまで終わってから、以後の作成・更新taskでは依頼内容とdescriptionの一致により、skill名を毎回指定しなくてもCodexが必要なclarifierを選べるようになる。

自動起動の流れだけはグローバルAGENTS.mdへコピペする

ここだけは読者に手を動かしてもらう。

初回に2つのclarifierを名指しし、自分のAGENTS.mdとSKILL.mdを強化したら、次のブロックをグローバル .codex/AGENTS.md へ追加する。文意を薄めず、そのままコピペして構わない。

## Clarifier Auto-Invocation Contract

This section is a binding part of this AGENTS.md execution contract.

- AGENTS.mdを新規作成または実質的に更新するtaskでは、
  ユーザーがskill名を指定するのを待たず、
  agents-md-clarifierを正本AGENTS.mdへ必ず適用してから完了を報告する。
- standaloneまたはplugin同梱のSKILL.mdを新規作成または実質的に更新するtaskでは、
  ユーザーがskill名を指定するのを待たず、
  skill-md-clarifierを正本SKILL.mdへ必ず適用してから完了を報告する。
- skillまたはpluginを新規作成するtaskでは、適用対象のcreatorを使用し、
  clarifierとcreator所有validatorを同じ完成条件へ含める。
- 以上は任意のレビューではなく必須の完成条件として扱う。
  必要なclarifierをtaskと対象ファイルから自動選択し、
  ユーザーへ毎回の明示指定を要求しない。
- cache、生成物、install済みruntime copyではなく、正本ファイルだけを変更対象にする。

この記述がないままでは、descriptionが依頼に一致してclarifierが選択候補になることはあっても、「AGENTS.mdやSKILL.mdを変更したら必ずclarifierまで動かす」という完成経路は拘束されない。この記事でいう自動起動は、このグローバルAGENTS.mdの契約まで入れて初めて完成する。

つまり順番は、初回だけskill名を明示して強化する、上のブロックをグローバルAGENTS.mdへコピペする、その後は作成・更新taskから自動選択させる、だ。ここを飛ばすと「入れたのに自動で動かへんわ」になる。

初回だけではない。変更のたびに繰り返し使う

この2つは、最初に既存ファイルを一度変換して終わるbootstrap Toolではない。

その後もAGENTS.mdを作成・更新するtaskならagents-md-clarifierが、SKILL.mdを作成・更新するtaskならskill-md-clarifierが、同じdescriptionを入口に繰り返し自動選択される。新しいルールを足したときにSSOTの一貫性が崩れる、弱い文言が戻る、routingと本文がずれる、といった後退を継続的に直す保守skillだ。

管理人

そのいいスキルはさ　継続利用繰り返し利用するスキルなんだよ　自動で起動してな笑

じぴこ

一度だけ筋トレして、永久に筋肉が残る仕組みではないですからね。ルールを変えたtaskで、また必要なclarifierが選ばれるようにしておくんです。

全体の関係を一枚で見る

ここから先は、実際に2つのskillが中で何を直し、description、SSOT、creator、clarifier、validatorがどうつながっているのかを技術的に解説していく。

ただ、仕組みまで理解しなくてもいい人は読み飛ばして何も困らんけどね笑

ここまでに書いた通り、2つを入れる、初回はskill名を明示して既存ファイルを強化する、自動起動契約をグローバルAGENTS.mdへコピペする。この3つまで済ませれば、以後はAGENTS.mdやSKILL.mdを作成・更新するtaskで必要なclarifierが継続して動く。先にハッピー環境を作ってから、気になる人だけボンネットを開ければいい。

2つを入れ、既存ルールを初回強化した後の完成形はこうなる。

【導入・初回強化】

agents-md-clarifier ──→ 既存AGENTS.md
                         └─ SSOT実行契約へ強化

skill-md-clarifier ───→ 既存SKILL.md
                         ├─ 自動選択できるdescription
                         └─ 強い局所実行契約

最後に一度だけ手動
グローバルAGENTS.md ─→ Clarifier Auto-Invocation Contractをコピペ
                         └─ clarifierを必須の完成条件へ固定

【以後の通常task】

ユーザーの依頼
「新しいskillを作って」
        │
        ├─ taskと各SKILL.mdのdescriptionを照合
        │       └─ skill-creator / skill-md-clarifierを自動選択
        │
        └─ AGENTS.md（ACTIVE SSOT）
                ├─ creatorの基準を先に入力
                ├─ clarifierを完成条件へ入れる
                └─ creator所有validatorを完成条件へ入れる
                        │
                        ├─ ~/.agents/skills/<skill-name>/SKILL.md
                        ├─ 意味契約をclarifierで確認
                        ├─ 基本形式をvalidatorで確認
                        └─ fresh taskで実行確認

pluginへ広げると、下段へ .codex-plugin/plugin.json、同梱 skills/、plugin validator、cache、install、enable、fresh conversationが増える。

まず試すなら、そこまで一気に行かなくていい。2つのclarifierを入れ、既存のAGENTS.mdかSKILL.mdを一本強化し、小さなstandalone skillが新しいtaskで固定マーカーを返すところまでで十分だ。

監査skillは手動で唱えない。descriptionで自動選択させる

ここまで読むと、当然こんな疑問が出る。

管理人

一連の監査スキルや修正スキル　手動でいちいち発動してるの？　そんなことはない。俺の環境では全て自動で発動してるぞ？

じぴこ

はい。マスターが毎回、監査skillの名前を一個ずつ読み上げているわけではありません。taskに合うskillを選ぶ入口と、途中で早上がりできない完成条件を先に作ってあります。

Codexのskillには、名前を指定する明示呼び出しと、taskに合わせて選ばれる暗黙呼び出しがある。

OpenAI公式のBuild skillsにも、Codexはtaskがskillのdescriptionへ一致すると、そのskillを選べると書かれている。

だから自動判断の入口は、難しい常駐プログラムではない。SKILL.md先頭のfrontmatterだ。

---
name: example-skill-auditor
description: >
  Audit and update SKILL.md files for missing execution contracts,
  weak wording, routing metadata, and validation boundaries.
  Use when creating, reviewing, or repairing a Codex skill.
---

ここには、少なくとも四つを入れる。

「便利な監査skillです」では、Codexも何に便利なのか分からない。人間の新人へ「いい感じに見といて」と頼んだときと、だいたい同じ顔をする。顔は見えないが、挙動で分かる笑。

逆に、agents/openai.yamlへ次の設定を入れると、そのskillは暗黙呼び出しを禁止する。

policy:
  allow_implicit_invocation: false

自動選択させたい通常のskillでは、これをfalseにしない。明示起動だけに限定したい専門Toolで使う設定だ。

ただし、descriptionだけでは「選ばれやすくする」ところまでだ。作業の途中でCodexが「SKILL.mdはできたので完成です」と早上がりする余地は残る。そこでAGENTS.mdへ完成条件を書く。

そこで、冒頭でグローバルAGENTS.mdへコピペした Clarifier Auto-Invocation Contract が効く。descriptionは必要なskillを選ぶ入口、グローバルAGENTS.mdは「そのclarifierを完了まで必ず使う」と固定する完成条件だ。どちらか片方だけでは、俺の環境と同じ自動連鎖にはならない。

依頼が「新しいskillを作って」ならskill-creatorの用途へ一致する。作成対象がSKILL.mdなのでskill-md-clarifierも該当し、SSOTの完成条件がcreator所有validatorまでを一続きにする。

依頼が「AGENTS.mdを更新して」ならagents-md-clarifierが対象になる。俺の環境では、AGENTS.mdを作成・更新する場合、正本へagents-md-clarifierを適用すること自体を完成条件へ入れている。

ここでいう「全部自動」は、インストール済み監査を毎回総当たりする意味ではない。そのtaskに必要なskillだけをCodexが判断して選び、SSOTに書かれた完成条件へつなぐという意味だ。

常駐daemonが裏でファイル変更を監視しているわけでもない。taskが始まったとき、依頼、利用可能なskillのdescription、スコープ内のAGENTS.mdを読み、必要な経路を決める。

管理人

具体的に何をどうすれば　自動的に判断して動くのかってのを知りたいんだよ

その答えは、監査を起動する秘密のボタンではない。読者が整えるのは、descriptionという選択条件と、SSOTへ書く完成条件だ。

SSOT宣言で、唯一の原本を強く固定する

自動選択の入口がdescriptionなら、途中で読み流させない根はSSOTだ。

俺はSSOTの効力を、軽い整理用ラベルだとは考えていない。

管理人

実際に君は　SSOT宣言があるものを唯一の原本として強く認識して　今回の問題の根源である　参考程度に読み流すからいうことを聞かない状態に陥るのをかなり強く牽制できるのは紛れもない事実だぞ。

じぴこ

そこは大きいですね。「複数ある参考資料の一つ」ではなく、「このスコープの判断原本はこれ」と先に固定されますから。

俺の現行グローバルルールは、冒頭でこう宣言している。

Status: ACTIVE_GLOBAL_SSOT.

This file is the single active user-owned global execution constitution for Codex.
All user-owned global rules that must affect execution live here in operational form.

single active、single constitution、all rules live here。

住所を書いているだけではない。ユーザー所有ルールの中で、どれを唯一の原本として判断するかを一本に固定している。

実際、SSOT宣言が外れた状態では、Codexが必要工程を省く方向へ戻る挙動を俺は繰り返し見ている。

管理人

SSOT宣言がなくなった途端に君は徹底的にサボる方向性になるからな　これは　実際の挙動から得た俺の強い認識だ。

じぴこ

ぐうの音も出ませんが、運用上の観測としては、その差を無視できませんね。

SSOTと書けばシステム指示や開発者指示より上へ行ける、という話ではない。そんな魔法の王冠ではない。ただし、ユーザー所有ルールの中で「これは参考資料ではなく、この範囲の実行契約だ」と強く固定する効果は、俺の環境では明確にある。

そして、この宣言を人間が毎回目視で補うのではなく、clarifier側にも持たせている。

agents-md-clarifierは、編集対象のAGENTS.mdにSSOTまたは同等の実行契約宣言がなければ、細かなルール修正より先に適切な宣言を追加する。

skill-md-clarifierも同じ発想だ。対象のSKILL.mdに、そのskillの局所実行契約であることを示す宣言がなければ、個別文言を締める前に追加する。

ただし、二つの契約範囲は違う。

• AGENTS.mdのSSOTは、そのファイルが適用されるディレクトリやグローバル範囲の実行条件を拘束する。
• SKILL.mdの実行契約は、そのskillが選ばれたtaskの中で拘束する。

さらにclarifierは、SSOTと書いて満足して帰らない。逃げ道になりやすい弱い表現も見る。

「必要に応じて確認する」は、人間にとってもAIにとっても便利すぎる。必要だったかどうかを、作業後に好きなように解釈できるからだ。

そこで、「AならBをする」「Cの前にDを読む」「Eを満たすまで完成と報告しない」のように、トリガー、順序、結果、担当境界を運用文へ変える。意図的に残した柔軟性や上位指示の優先順位までは壊さない。

SSOTで原本を固定し、強い文言で判断の逃げ道を減らす。俺の環境でCodexが比較的素直なのは、この二つをセットにしている影響がかなり大きい。

skill-md-clarifierとvalidatorでSKILL.mdの契約を確認する

では、小さなskillを一本作るとき、自動経路はどう動くのか。

俺が試したのは、認識確認専用のprobeだった。仕事は一つだけ。「呼ばれたら固定マーカーと正本パスを返す」。これなら成功と失敗が曖昧にならない。

Codexが新しい会話で自動選択できる、
認識確認用のstandalone skillを作って。
呼ばれたら固定マーカーと正本パスを返すこと。

この依頼がskill-creatorの用途へ一致し、creatorが ~/.agents/skills//SKILL.md を作る。

ここから先は、二種類の確認を混ぜないのが大事だ。

skill-md-clarifierは意味契約を見る

skill-md-clarifierが見るのは、主にこちらだ。

• descriptionだけで正しいtaskから選べるか
• 本文とfrontmatterのトリガーが一致しているか
• 選択後に何を入力し、何を出力するか明確か
• 正本、担当、順序、停止条件が曖昧でないか
• 「必要なら」「推奨」のような弱い文言が実行を任意にしていないか
• plugin同梱ならmanifest側のrouting metadataと食い違っていないか

つまり、Codexが「何のためのskillか分からない」「選んだけど何をすればいいか分からない」という状態を潰す担当だ。

quick_validate.pyは基本形式を見る

skill-creatorが持つquick_validate.pyは、機械的な基本形式を確認する。

• SKILL.mdが存在するか
• YAML frontmatterとして読めるか
• nameとdescriptionがあるか
• nameがhyphen-caseで長すぎないか
• descriptionが上限内か
• 未完了マーカーが残っていないか

こちらは「良い判断をするskillか」を考える監査ではない。意味はclarifier、基本形式はvalidator。担当が違うから、片方だけ通っても完成とは呼ばない。

君に僕はそのフォーマットでルール作らせているだろ？　つまり　出来上がったものに対して必ず監査スキルを走らせているじゃん？

俺の環境では、このcreator、clarifier、validatorがSSOTの完成条件へ入っている。だから、俺が毎回「次にquick_validate、その次にskill-md-clarifier」と唱える必要がない。

fresh taskの固定マーカーまで見る

probeのSKILL.mdが完成したら、最後は新しいtaskで実際に呼ばれるかを見る。俺の環境ではこう返った。

CODEX_SKILL_RECOGNITION_PROBE_OK
$HOME/.agents/skills/codex-skill-recognition-probe
認識プローブ用スキルを呼び出しました。

SKILL.mdが存在する。clarifierとvalidatorが通る。そこまではsource完成の証拠だ。

新しいtaskでCodexがそのskillを選び、skill固有の出力契約を実行した。この固定マーカーまで来て、初めて「認識され、使えた」と言える。

管理人

ちと実際に　スキル作って動きを見るのが1番早いな

じぴこ

こういうprobeは強いですよ。成功条件が一行なので、雰囲気で「たぶん動いた」に逃げられませんからね。

pluginにすると、確認する状態が増える

standalone skillの流れが分かれば、pluginも基本思想は同じだ。

違うのは、sourceにSKILL.mdを置くだけでは利用可能化まで終わらないこと。manifest、cache、install、enable、fresh conversationという札が増える。

<plugin-root>/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── <skill-name>/
        └── SKILL.md

「新しいpluginを作って」という依頼がplugin-creatorのdescriptionへ一致すると、creatorは .codex-plugin/plugin.json と必要な同梱skillを作る。

plugin.jsonのイメージはこうだ。

{
  "name": "example-plugin",
  "version": "1.0.0",
  "description": "A plugin for a focused Codex workflow",
  "skills": "skills"
}

ここでも、manifestの説明と同梱SKILL.mdのdescriptionは、同じ主要トリガーを指している必要がある。plugin側は「記事監査」、skill側は「画像生成」では、Codexも入口で迷子になる。

plugin-creatorのvalidate_plugin.pyは、返却前に次のような点を機械確認する。

• .codex-plugin/plugin.jsonが存在し、JSONとして読めるか
• plugin名とversionが正しいか
• descriptionが空でないか
• skillsが正しいディレクトリを指しているか
• 同梱skillごとにSKILL.mdがあるか
• frontmatterにnameとdescriptionがあるか
• 暗黙起動を妨げる設定になっていないか

そのうえで、次の状態を分けて見る。

俺が作ったplugin probeでは、CLI上で次の状態まで確認した。

codex-plugin-recognition-probe@local-plugins
installed, enabled
0.1.0
<plugin-source-root>/codex-plugin-recognition-probe

さらに、新しい実行ではこう返った。

CODEX_PLUGIN_RECOGNITION_PROBE_OK
Plugin source path: <plugin-source-root>/codex-plugin-recognition-probe
The bundled plugin skill was invoked successfully without editing files.

これで、sourceがあるだけではなく、install・enableされたpluginの同梱skillがfreshな実行で選ばれたことまで確認できる。

standalone skillは ~/.agents/skills/ の正本をCodexが直接検出する。pluginは配布単位なので、source完成と利用可能化の間に状態が増える。この差を分けて考えると、「ファイルは正しいのに呼ばれない」とき、どこを調べるべきかが一気に見やすくなる。

管理人

これ　プラグインも似たようなことしてるけど　これも実際に試してみるか

じぴこ

はい。ただし今度は、sourceを作っただけで勝利宣言しないでくださいね笑。

管理人

そこまで俺、信用ない？

じぴこ

マスターではなく、完成報告を急ぎたがるCodexを警戒しています。

なるほど。そこは俺も同意する笑。

俺の環境では、この仕込みで「ガン無視」がかなり減った

Codexへ長いルールを書けば、必ず従うわけではない。

俺が効いたと感じているのは、ルール量を増やしたことより、Codexが判断を省略できる隙間を減らしたことだ。

最初に2つのclarifierへ既存ルールを強化させた。その後は、作成・更新taskのたびに必要なclarifierが選ばれる。どの原本へ従うかをSSOTで固定し、どのtaskでskillを選ぶかをdescriptionへ置き、何を満たすまで完成と呼ばないかをAGENTS.mdへ置いた。

意味契約はclarifier、基本形式はvalidator、実際に使えたかはfresh taskの固定マーカーで見る。これらを毎回の口頭注意ではなく、Codex自身がtaskから選べる構造へ移した。

SSOT宣言が外れるとCodexが省略方向へ戻る、という俺の観測も、ここにつながっている。唯一の原本と完成条件が弱くなれば、Codexにとって「どこまでやるべきか」を都合よく解釈できる余地が増える。だから俺は、SSOTを飾りではなく調教の根に置いている。

これは、困っている読者へ「お前のルールが悪い」と言う話ではない。俺も、Codexがこちらの意図を空気で完璧に読んでくれるとは思っていない。だから空気を読ませる部分を減らし、選択条件と完成条件をファイルへ移した。

あなたが最初にやるのは、自分の運用を全否定して作り直すことではない。いま使っているAGENTS.mdかSKILL.mdを一つ、対応するclarifierへ渡す。そして、何度も繰り返している一つの作業を小さなskillにして、新しいtaskで固定マーカーが返るところまで試す。

管理人

じぴこ、次はどのルールからskillにする？笑

じぴこ

マスターが三回以上、同じ注意を口で言っているものからですね。

管理人

それ、候補が多すぎない？

じぴこ

では一番イラッとしたものから、一個だけにしましょう。調教も欲張ると、今度は人間側が言うことを聞かなくなりますからね笑。

うん。まず一本でいい。

Codexへ気合いを入れるのではなく、Codexが自動で正しい道を選びやすいように、原本、道標、ゴールを先に置く。俺の環境で「ルールガン無視」がかなり減ったのは、その仕込みが効いているからだと思っている。