Codex Agent Skills：再利用可能なスキルバンドルの作り方と活用パターン

この章の要点

Codex CLI の Agent Skills は、繰り返し使うワークフローを「スキル」として定義し、CLI と IDE 拡張で再利用できる仕組みです。

• スキルは SKILL.md（YAML frontmatter） とオプションの scripts/ references/ assets/ agents/openai.yaml を含むディレクトリ
• リポジトリ・ユーザー・管理者・システムの 4 スコープで .agents/skills/ を検索
• /skills 一覧表示、$skill-name で明示呼び出し、description マッチで暗黙呼び出し
• agents/openai.yaml で表示名・アイコン・ブランドカラー・暗黙呼び出しの可否などを定義できる

---

Agent Skills とは

特定の作業手順を SKILL.md にまとめてディレクトリに置くと、Codex がその手順をプロンプトの一部として読み込んで再現します。Claude Code の Skills と似た発想ですが、スクリプト・参照ファイル・アセットをバンドルできる点と、agents/openai.yaml で見た目とポリシーを定義できる点が特徴です。

---

公式仕様の範囲

公式ドキュメント /codex/skills では、ディレクトリ構造・スコープ別検索パス・SKILL.md の必須フィールド・agents/openai.yaml のスキーマ・呼び出し方法・コンテキスト予算が定義されています。

---

使い方

ディレクトリ構造

my-skill/
├── SKILL.md           ← 必須。YAML frontmatter + 本文
├── scripts/           ← 任意。決定的な処理を担うスクリプト
├── references/        ← 任意。参照させたいドキュメント
├── assets/            ← 任意。アイコン・テンプレートなど
└── agents/
    └── openai.yaml    ← 任意。表示メタデータとポリシー

検索スコープ

スコープ	パス	用途
REPO（カレント）	$CWD/.agents/skills	フォルダ固有のスキル
REPO（親）	$CWD/../.agents/skills	ネスト構造の親ディレクトリ
REPO（ルート）	$REPO_ROOT/.agents/skills	リポジトリ全体で共有
USER	$HOME/.agents/skills	ユーザー個人
ADMIN	/etc/codex/skills	管理者配布
SYSTEM	Codex 組み込み	OpenAI 提供のスキル

公式は REPO / USER / ADMIN / SYSTEM の 4 種のスコープを定義しています（REPO 内のサブパス区分は説明のための分類です）。同名スキルが複数スコープにある場合は統合されず、両方が一覧に表示されます。シンボリックリンクでの参照もできます。

SKILL.md の最小構成

---
name: run-tests
description: プロジェクトのテストスイートを実行して結果をレポートする。テストの存在を確認したいときや CI で失敗した原因を追いたいときに使う。
---

プロジェクトのテストを実行してください。

1. まず `package.json` を確認してテストコマンドを特定する
2. テストを実行する（`npm test` / `pnpm test` / `yarn test` のいずれか）
3. 失敗しているテストがあれば、原因と修正方針をレポートする
4. カバレッジレポートがあれば、低いカバレッジの箇所を報告する

name と description の 2 つだけが必須です。description には「いつ使うか／いつ使わないか」を具体的に書くことで、暗黙呼び出しの精度が上がります。

agents/openai.yaml で見た目とポリシーを定義

CLI / IDE 上の表示名・アイコン・暗黙呼び出しの可否や、依存する MCP ツールを宣言できます。

# my-skill/agents/openai.yaml
interface:
  display_name: "Run Tests"
  short_description: "リポジトリのテストを実行して結果を要約"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "失敗しているテストがあれば優先的に直して"

policy:
  allow_implicit_invocation: true   # 既定値 true。false で明示呼び出し限定

dependencies:
  tools:
    - type: "mcp"
      value: "linear"
      description: "Linear で関連 issue を補足するために使用"
      transport: "streamable_http"
      url: "https://mcp.linear.app/sse"

allow_implicit_invocation: false にすると、ユーザーが $skill-name で明示的に呼び出した時にだけ実行されます。誤呼び出しが致命的なスキル（本番デプロイ系など）に有効です。

スクリプトのバンドル

決定的な処理や外部ツールの実行が必要なときは、scripts/ 配下にスクリプトを置いて SKILL.md から参照させます。公式は「スクリプトより指示を優先し、決定的な振る舞いや外部ツールが必要な場合のみスクリプトを使う」よう推奨しています。

.agents/skills/check-deps/
├── SKILL.md
├── scripts/
│   ├── check-npm.sh
│   └── report.py
└── references/
    └── allowed-licenses.md

---
name: check-deps
description: 依存関係の脆弱性とライセンスをチェックして CRITICAL / HIGH 件数を要約する
---

依存関係チェックを実行してください。

1. `scripts/check-npm.sh` を実行して `npm audit --json` の結果を取得する
2. `scripts/report.py` で結果をフォーマットする
3. CRITICAL・HIGH の脆弱性があれば修正方法を提示する
4. ライセンス判定は `references/allowed-licenses.md` に従う

テンプレート（assets）のバンドル

ファイル雛形は assets/ または独自のディレクトリに置き、SKILL.md から相対パスで参照します。

.agents/skills/create-feature/
├── SKILL.md
└── assets/
    ├── service.ts.tmpl
    ├── controller.ts.tmpl
    ├── dto.ts.tmpl
    └── service.spec.ts.tmpl

---
name: create-feature
description: NestJS の機能モジュールを定型テンプレートから生成する
---

ユーザーから渡された機能名で NestJS モジュールを作成してください。

1. `assets/` 配下のテンプレートを使う
2. テンプレート内の `FEATURE_NAME` を機能名で置換する
3. 生成したファイルをテストして動作することを確認する

CLI での呼び出し方

# 利用可能なスキルを一覧表示
> /skills

# 明示呼び出し（$ + スキル名）
> $run-tests
> $check-deps

# OpenAI 提供のキュレートスキル
> $skill-creator           # 対話形式で新しいスキルを作成
> $skill-installer linear  # 指定されたスキルをインストール

description がマッチする場面では、$skill-name を打たなくても Codex が自発的に暗黙呼び出しを行います。抑止したい場合は agents/openai.yaml で policy.allow_implicit_invocation: false を指定します。

IDE 拡張での使い方

VS Code・Cursor・Windsurf の Codex 拡張でも /skills 一覧と $skill-name 呼び出しが使えます。リポジトリの .agents/skills/ を共有する形になるので、ターミナル・IDE で同じスキルが動きます。

実践例：コミットメッセージ生成

---
name: smart-commit
description: ステージング済みの変更から Conventional Commits 形式のメッセージを作成して、確認を取ってからコミットする
---

ステージングされている変更を分析し、適切なコミットメッセージを生成してください。

1. `git diff --staged` で変更内容を確認する
2. 種類に応じて prefix を選ぶ（feat / fix / refactor / test / docs / chore）
3. メッセージは `prefix(scope): 件名` の形式（日本語）
4. コミット前に生成したメッセージを提示し、ユーザーの確認を取る

実践例：PR サマリー生成

---
name: pr-summary
description: 現在のブランチの変更内容から PR の説明文（タイトル・概要・テスト方法）を生成する。レビューを依頼する直前に使う。
---

`git diff main...HEAD` の変更内容を分析し、PR 説明文を生成してください。

生成する項目：
- タイトル（1 行・70 文字以内）
- 変更の概要（3〜5 点の箇条書き）
- テスト方法
- スクリーンショットの要否（UI 変更がある場合）

GitHub の PR 本文として使える Markdown 形式で出力してください。

---

Claude Code Skills との比較

観点	Codex Agent Skills	Claude Code Skills
frontmatter フォーマット	YAML	YAML
ファイル名	SKILL.md	SKILL.md
スクリプトバンドル	scripts/ 配下に同梱	スキルファイル 1 枚＋同梱可
アセットバンドル	assets/ 配下に同梱	限定的（環境による）
表示メタデータ	agents/openai.yaml（display_name・アイコンなど）	限定的
暗黙呼び出し	policy.allow_implicit_invocation（既定 true）	description マッチで起動
検索スコープ	REPO 階層 / USER / ADMIN / SYSTEM の 4 種	個人・プロジェクトの 2 種

---

注意点・セキュリティ観点

description は「いつ使うか／いつ使わないか」を書く

暗黙呼び出しの精度は description で決まります。「○○のときに使い、××のときは使わない」と書くと誤起動が減ります。

致命的な操作は allow_implicit_invocation: false

本番デプロイ・データ削除・課金処理などの不可逆な操作は、明示呼び出しに限定するのが安全です。

scripts/ は最小限に

公式は「スクリプトより指示を優先する」推奨です。LLM の出力ぶれを抑えたい決定的処理だけスクリプト化し、判断系は SKILL.md 本文に書きます。

コンテキスト予算は約 2% / 8,000 文字

スキル一覧の初期読込はコンテキストウィンドウの約 2%（不明な場合 8,000 文字）に収まるよう設計されています。description は簡潔に書き、冗長にしないようにします。選択された SKILL.md 全文はその後で読み込まれます。

サンドボックス・承認モードはセッション側で管理

公式 SKILL.md frontmatter には sandbox_mode や approval_required といった項目は規定されていません。サンドボックスや承認ポリシーは、セッション起動時の --sandbox / --ask-for-approval か config.toml で制御します。

---

一次ソース

• Agent Skills — Codex Docs
• CLI Features — Codex Docs
• Configuration reference — Codex Docs