Codex Skills：作成、実行、コードレビュータスクでの検証

CodexにおけるSkillsの仕組み

公式ドキュメントに記載されているスキル（skills）の仕組みは、システムコンテキストに負荷をかけることなく、特定タスク向けの指示やテンプレートをエージェントに適用するものです。

スキルは、必須ファイルである SKILL.md を含むディレクトリとして構成されます。そのYAML frontmatterには name と description フィールドが必須であり、本文にはモデルに対するルールを記述します。

.agents/skills/boundary-review/
└── SKILL.md

Codexは段階的開示（progressive disclosure）を採用しています。起動時には利用可能なスキルのコンパクトなインデックスのみが構築され、エージェントが特定のスキルを適用すると判断した瞬間に初めて SKILL.md の全文が読み込まれます。

スキルの検出（discovery）は、以下の4つの階層で行われます。

1. リポジトリ（REPO）：カレントディレクトリ内の .agents/skills、およびGitルートまでの上位ディレクトリ。
2. ユーザー（USER）：$HOME/.agents/skills。
3. 管理者（ADMIN）：/etc/codex/skills。
4. システム（SYSTEM）：環境のシステムディレクトリ（bundled）。

呼び出しは、明示的（プレフィックス $name を使用）または暗黙的（プロンプトと description のセマンティックな一致に基づく）に行われます。利用可否や競合の管理は config.toml ファイルで行われます。

前提条件と環境の分離

本シナリオを再現するには、以下が必要です。

• Python 3
• インストールおよび認証済みのCodex CLIコマンドラインインターフェース

テストデータは、2026-09-16にCodex CLIバージョン0.153.3を使用して記録されました。

すべてのコマンドは、Gitリポジトリ外に用意したローカルディレクトリで実行します。SKILL.md 内のテキスト指示はモデルの振る舞いを制御するものの、オペレーティングシステムの分離を保証するものではないため、実行時には以下のフラグを指定します。

• --ephemeral：セッション状態の永続化を防止する
• --skip-git-repo-check：Git管理外の独立したフォルダでの実行を許可する
• --sandbox read-only：実行環境レベルでプロセスの書き込みアクセスを制限する

CLIはグローバル設定を継承し、サードパーティ製フックに関するシステム警告を出力する可能性があるため、実際の検証は対象スキルの読み込みイベントのみを根拠として判定します。

boundary-reviewスキルの作成

カレントディレクトリにスキルのディレクトリを作成します。

mkdir -p .agents/skills/boundary-review

.agents/skills/boundary-review/SKILL.md に以下の内容を保存します。

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

このテキスト指示により、モデルによるファイルの変更を禁止し、1つの失敗する入力値を報告した上で、回答をシグナルマーカー BOUNDARY_REVIEW で開始することを義務付けています。

欠陥のあるテストファイルの作成

ページ数計算において典型的なオフバイワンエラーを含む pages.py ファイルを作成します。

def page_count(total, size):
    return total // size + 1

size > 0 かつ total >= 0 の条件下において、この関数は境界値で破綻します。total = 1 かつ size = 1 の場合、期待値の 1 ではなく 2 を返します。さらに、空のリストを想定した total = 0 の場合にも 1 を返してしまいます。

実行と呼び出しの検証

コマンドプロセッサが $ 記号を環境変数として解釈するのを防ぐため、クエリはシングルクォートで囲んで渡します。

1. 名前による明示的な呼び出し

スキルを直接指定して明示的な検証を実行します。

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

モデルは以下の結果を返します。

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

マーカー文字列はプロンプトの文脈から生成される可能性もあるため、BOUNDARY_REVIEW マーカーの存在単体では SKILL.md が読み込まれたことの証明にはなりません。2026-09-16の実際の実行において、システムログは .agents/skills/boundary-review/SKILL.md ファイルの読み取りコマンドイベントを記録していました。ログ内のファイル読み取りイベント、BOUNDARY_REVIEW プレフィックス、そして反例 page_count(1, 1) の組み合わせが揃って初めて、対象の指示が実行されたことが確認されます。

2. 説明文による暗黙的な呼び出し

$boundary-review という識別子を含めずに、自然言語でタスクを指定します。

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

この実行のログでも、クエリのフレーズと description フィールドのセマンティックな一致によって .agents/skills/boundary-review/SKILL.md が読み込まれたことが記録されました。エージェントは同様に BOUNDARY_REVIEW マーカーを含む構造化された回答を出力し、入力 (1, 1) での失敗を分析しました。

ロジックの検証と読者向け手順

ローカルのPythonインタープリタを使用して、元の関数の挙動を確認します。

python3 -c "from pages import page_count; print(page_count(1, 1))"

このコマンドは 2 を出力し、バグの存在が確認できます。

2026-09-16のベンチマーク実行では、元の pages.py ファイルは変更されないまま維持されており、修正済みファイルに対するCLIの再実行は行われていません。提案された計算式 (total + size - 1) // size が total >= 0 かつ size > 0 において数学的に正しいことは、以下の境界値セットで検証されています。

• (0, 10) -> 0;
• (1, 1) -> 1;
• (10, 10) -> 1;
• (11, 10) -> 2。

手動で修正を適用する場合、読者は pages.py を以下のように更新できます。

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

変更を保存した後、読者はアサーションチェックを実行できます。

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

ファイルの手動編集後、コマンドの期待される実行結果は OK です。

トラブルシューティング

スキルが検出されない、または自動的に呼び出されない場合は、以下を確認してください。

1. ファイルパス：作業ディレクトリからの相対パスが厳密に .agents/skills/<skill-name>/SKILL.md となっているか確認します。
2. レジストリの再読み込み：アクティブなセッション中にファイルを追加した場合は、CLIプロセスを再起動してディレクトリを再スキャンします。
3. 設定によるブロック：~/.codex/config.toml を確認します。スキルが無効化されていた場合、以下のようなエントリによって読み込みがブロックされます。

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   該当ブロックを削除するか、enabled = true に設定してください。
4. 名前の競合：リポジトリレベルとユーザーレベルに同一の name が存在する場合、優先順位規則によって意図しない優先度（曖昧さ）が生じる可能性があります。
5. descriptionの精度：暗黙的な呼び出しを行う場合、主要なトリガー（「pagination boundaries」、「boundary errors」）は説明文の先頭付近に配置する必要があります。
6. サードパーティ製スキル：外部パッケージを読み込む必要がある場合のエントリポイントは $skill-installer ユーティリティです。いかなるサードパーティ製スキルであっても、実行前に SKILL.md ファイルおよび scripts/ ディレクトリの手動監査が必須です。なお、本記事で説明したシナリオでは、サードパーティ製コンポーネントはインストールしていません。