Codex Skills と Plugins 実践ガイド：チームのワークフローを再利用できる形にする

同じコードレビュー用チェックリストを 5 つのリポジトリに貼り付けている。PR ごとに「失敗しているテストを先に回す」「権限境界を見る」「changelog を漏らさない」と手で念押しする。問題は prompt が短いことではありません。その手順が、まだ再利用できる形になっていないことです。

Codex の Skills と Plugins は、この繰り返しを整理するための道具です。チームの反復ワークフローを、その場限りの prompt や肥大化した AGENTS.md から取り出し、再利用できる能力として残します。Skill は再利用ワークフローの作者向け形式です。Plugin はインストールできる配布単位です。プロジェクトルールとは役割が違います。常駐ルールは AGENTS.md に置き、複数ステップの手順、例、スクリプト、長い参考資料は Skill に入れ、チーム配布が必要になったら Plugin にします。

まずは判断表で、Skill、Plugin、MCP、AGENTS.md、Subagent のどれを使うべきかを切り分けます。そのあと、最小構成の Skill ツリーから始め、role-specific plugin の分解、チーム配布、権限境界の確認まで進めます。

1. コピーされ続けるチーム手順：問題は prompt ではない

コードレビュー、リリース前チェック、テスト手順、ドキュメント更新。こうしたチェックリストは、チームの中でほぼ固定の形を持ちます。PR レビューのたびに Codex へ「changelog が漏れていないか、テストカバレッジが下がっていないか、API docs を更新すべきか確認して」と貼っているかもしれません。すぐに問題が出ます。

• メンテナンス場所が散らばる：チェックリストを更新すると、5 つのプロジェクトの .github/PULL_REQUEST_TEMPLATE.md や個別の prompt ファイルを直す必要がある
• 実行品質が安定しない：Codex は毎回ゼロから手順を理解するため、「失敗しているテストを先に回す」のような重要手順を落としやすい
• 役割の基準が混ざる：フロントエンド、QA、セキュリティ、ドキュメントの確認項目を 1 つの prompt に積むと、Codex がどの基準を使うべきか判断しにくい

これらをすべて AGENTS.md に書くチームもあります。ただし、そこにも別の問題があります。プロジェクトルールのファイルが長くなり、常駐すべきビルドコマンド、ディレクトリ規約、一時的な手順ガイドが混ざります。それは「永続的なプロジェクト制約」を置くという本来の役割を超えています。

Codex では、もっとはっきり分けられます。AGENTS.md は永続ルール、Skills は再利用ワークフロー、Plugins は配布。大事なのは、それぞれの層に何を置くかです。

2. Skill、Plugin、MCP、AGENTS.md を判断表で分ける

Skill は再利用ワークフローの作者向け形式です。通常は SKILL.md と、任意の scripts、references、assets で構成されます。Plugin は Codex にインストールできる配布単位で、Skills、app integrations、MCP servers、assets をまとめられます。MCP は外部ツールとコンテキストをつなぐプロトコルで、Codex からサードパーティのドキュメント、ブラウザ、Figma、GitHub などを扱えるようにします。AGENTS.md は永続的なプロジェクト制約、つまりビルドコマンド、ディレクトリ規約、レビュー期待値などを置く場所です。Subagent はノイズの多い専用タスクを委任するための役割です。

どれを選ぶべきか

内容タイプ	適した方式	典型例	使わないほうがよい場面
ビルドコマンド、テストスクリプトのパス、ディレクトリ規約	AGENTS.md	「新規コンポーネントは src/components/ に置く」「テストは npm run test:unit」	複数ステップの手順、例、外部ツール呼び出し
複数ステップの手順、例・スクリプト・参考資料が必要なもの	Skill	10 ステップのコードレビュー、7 項目のリリース前チェック、API docs 生成フロー	1 つのコマンドや 1 行ルールだけ
チーム配布、app/MCP 設定の同梱	Plugin	4 つのレビュー Skills と Figma connector を含むフロントエンド役割 Plugin	単一リポジトリ内で試しているだけで、共有が不要なもの
外部ツール呼び出し、サードパーティの文脈取得	MCP	Figma から設計仕様を取得、GitHub API で issue 一覧を読む	外部データが不要な純粋なワークフロー定義
ノイズの多い専用タスクの委任	Subagent	テスト診断やログ分析を専用 agent に任せる	メイン対話で十分処理できる単純な手順

AGENTS.md から Skill に切り出すタイミング

次の状態なら、手順はプロジェクトルールファイルの範囲を超えています。Skill にするほうが扱いやすいです。

• 同じチェックリストが複数の PR で繰り返し出てきて、毎回手で貼り付けている
• 手順が複数ステップあり、例、スクリプト、外部参考資料が必要
• 「リリース前に実行」「プルリクエスト時に実行」のような明確なトリガーがある
• フロントエンド、QA、セキュリティ、ドキュメントなど役割ごとに基準が違い、1 ファイルに詰めると読みづらい
• 変更履歴やバージョン管理が必要で、毎回プロジェクトルールを直接編集したくない

Skill から Plugin に上げるタイミング

単一リポジトリや個人ワークフローで試している間は Skill で十分です。次のニーズが出たら Plugin にします。

• 個人ディレクトリや単一リポジトリではなく、チーム横断で共有したい
• Figma、GitHub、CI/CD ツールのような app integration、または MCP server 設定を同梱したい
• Skill フォルダをコピーするのではなく、バージョン管理、changelog、アップグレード手順を持ちたい
• Codex App の Plugin Directory から workspace メンバーへ配布したい
• 毎日のように変わる実験手順ではなく、安定したパッケージとして公開したい

実務では、まず AGENTS.md にリポジトリ規約を固定します。合う既存 Plugin があればインストールします。なければ Skill を作り、チーム配布が必要になったら Plugin にします。外部システムが必要なときだけ MCP を接続し、ノイズの多い専用タスクは Subagent に委任します。

3. 最小構成の Skill 実践：コードレビューから始める

最小 Skill ファイルツリー

Skill に最低限必要なのは次の構成です。

.agents/skills/code-review/
├── SKILL.md
├── references/
│   └── security-checklist.md
└── scripts/
    └── run-failed-tests.sh

ディレクトリ名と SKILL.md frontmatter の name は一致している必要があります。使える文字は lowercase alphanumeric と hyphen です。

SKILL.md の例：コードレビュー Skill

---
name: code-review
description: Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs. Do not use for backend-only changes or infrastructure PRs.
---

# Code Review Checklist

## Before Starting
1. Run failed tests first: `npm run test:failed`
2. Check if PR has clear description and scope

## Review Steps
1. Changelog: Does `CHANGELOG.md` need update?
2. Test Coverage: Did coverage decrease? Check report in `coverage/`
3. Security: Review changes in `src/auth/`, `src/api/`, and `src/middleware/`
4. API Docs: If API changed, update `docs/api.md`

## Security Boundary Checks
See `references/security-checklist.md` for detailed items.

## Failed Test Runner
Use `scripts/run-failed-tests.sh` to rerun previously failed tests.

description のトリガー設計：before/after

Codex は description を見て、暗黙的に Skill を呼ぶか判断します。曖昧に書くと、誤って呼ばれたり、必要なときに呼ばれなかったりします。

Before（誤トリガーしやすい）	After（トリガーが安定しやすい）
“Code review skill for frontend projects"	"Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs."
"Help review code"	"Use when reviewing PRs with frontend changes. Do not use for backend-only changes or infrastructure PRs."
"Review checklist"	"Trigger on: PR reviews, code audit requests. Exclude: backend changes, config-only updates.”

書き方の要点は、“Use when…” と “Do not use when…” を明確にすることです。pull request、review、frontend のようなトリガー語は前半に置きます。大きい Skill 集では description が途中で切られる可能性があるためです。明示呼び出しだけにしたい場合は、allow_implicit_invocation: false を設定します。

Skill の保存場所とスコープ

位置	スコープ	適した場面	注意点
.agents/skills/（リポジトリルート）	現在のリポジトリ	チームプロジェクトのレビュー、テスト、リリース手順	Git に入れてチームで共有する
$HOME/.agents/skills/（ユーザーディレクトリ）	個人の横断利用	個人のコードスタイル、よく使うコマンド習慣	リポジトリには自動同期されない
/etc/codex/skills/（admin ディレクトリ）	組織レベル	組織共通のセキュリティレビュー、コンプライアンス確認	admin 権限が必要
System bundled	システム内蔵	Codex が標準で提供する $skill-creator、$skill-installer	変更できない

同名の Skill はマージされません。優先度は通常 repo > user > admin > system ですが、挙動が変わる可能性があるため、具体的な仕様は公式ドキュメントを優先してください。

Progressive disclosure の設計原則

すべてをメインの SKILL.md に詰め込まないほうがよいです。Codex の progressive disclosure は 3 層です。

1. Metadata：最初は name、description、file path だけを見る
2. Instructions：Skill が選ばれてから完全な SKILL.md を読む
3. Resources：必要になったときだけ references/、scripts/、assets/ を読む

設計の目安は、メインの SKILL.md を 500 行以内に抑えることです。長い参考資料は別ファイルへ。テストランナーやカバレッジ検査のような決定的チェックは scripts/ へ。詳細なチェックリスト、背景資料、過去事例は references/ へ。テンプレートや例示スクリーンショットは assets/ に置きます。

明示呼び出しと暗黙呼び出し

明示呼び出しは $code-review、または /skills から選択します。暗黙呼び出しでは、Codex が description から現在のタスクに合うか判断します。暗黙呼び出しを無効にする場合は、agents/openai.yaml に allow_implicit_invocation: false を設定します。

暗黙呼び出しは、PR レビューのように高頻度で境界がはっきりした手順に向いています。明示呼び出しは、四半期ごとのセキュリティ監査のように頻度が低く、人の判断が必要な場面に向いています。Skill に外部スクリプトや機微な操作が含まれるなら、明示呼び出しを優先します。

4. Plugin のパッケージ化とチーム配布：ローカル Skill からチーム用セットへ

Plugin の最小構造

Plugin は Skill ディレクトリの名前を変えただけのものではありません。インストール可能なパッケージであり、少なくとも .codex-plugin/plugin.json manifest が必要です。

.agents/plugins/frontend-review/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── accessibility-check/
│   │   └── SKILL.md
│   └── performance-lint/
│       └── SKILL.md
├── assets/
│   └── templates/
└── README.md

plugin.json の必須フィールド

{
  "name": "frontend-review",
  "version": "1.0.0",
  "description": "Frontend team code review and accessibility check skills",
  "skills": "./skills/",
  "assets": "./assets/",
  "author": "frontend-team",
  "repository": "https://github.com/org/frontend-review-plugin"
}

任意フィールドには、Figma 用 .app.json のような app integration を入れる apps、.mcp.json のような MCP server 設定を入れる mcpServers、権限やデータ共有ポリシーを示す policy があります。いずれも workspace admin policy の制約を受けます。

marketplace 構造：チームの Plugin ディレクトリ

Plugin marketplace は、Plugin の場所を指す JSON リストです。

.agents/plugins/marketplace.json

{
  "plugins": [
    {
      "source": "local",
      "path": "./frontend-review"
    },
    {
      "source": "github",
      "owner": "openai",
      "repo": "role-specific-plugins",
      "ref": "main",
      "path": "plugins/data-analytics"
    }
  ]
}

local は未公開の社内 Plugin 向けです。github は公開 Plugin やチーム横断で共有するパッケージに向いています。

Plugin 配布コマンドのチェックリスト

CLI のコマンドは変わりやすいため、公式ドキュメントを基準にしてください。

# 新しい Plugin を scaffold する
codex plugin create frontend-review

# Plugin を marketplace に追加する
codex plugin marketplace add owner/repo --ref main --sparse

# インストール済み Plugin を一覧する
codex plugin marketplace list

# Plugin をアップグレードする
codex plugin marketplace upgrade frontend-review

# Plugin を削除する
codex plugin marketplace remove frontend-review

Codex App では、Plugin Directory から Curated by OpenAI、Shared with you、Created by you を確認できます。Local plugin は workspace members や groups に共有できます。Workspace admins は plugin sharing を無効化したり、managed requirements を設定したりできます。

workspace へ共有することと、公開することは違います。外部 app 接続や MCP server には引き続き認可が必要で、approval settings も適用されます。

チーム marketplace の整理方法

リポジトリ専用 Plugin は $REPO_ROOT/.agents/plugins/marketplace.json に置きます。組織共通 Plugin は $HOME/.agents/plugins/marketplace.json、または GitHub organization repo に置くと扱いやすいです。バージョンは plugin manifest の version に明記します。README には changelog を置き、アップグレード前にテスト環境で確認します。セキュリティレビューやコンプライアンス確認のような機微な Plugin は組織レベルの marketplace に置き、気軽にインストールされないようにします。

最初から Plugin を作るより、まず local skill で反復し、安定してから Plugin にして配布するほうが変更しやすいです。

5. Role-specific Plugin の分け方：フロントエンド、QA、ドキュメントの役割を固定する

OpenAI の role-specific-plugins リポジトリには、Sales、Data Analytics、Product Design、Financial Markets のテンプレートがあります。開発チームが営業や金融の手順をそのまま使う必要はありません。ただし、分解方法は参考になります。1 つの役割から始め、3〜5 個の小さな Skill に分け、それらを Plugin としてまとめます。

分解フレーム：役割 → 繰り返す成果物 → データ/ツール元 → 小さな Skill → 共有方法

役割	繰り返す成果物	データ/ツール元	切り出す Skills	必要になり得る apps/MCP	受け入れ基準
フロントエンドエンジニア	コンポーネントレビュー、性能チェック、アクセシビリティ検証	Figma の設計仕様、既存 Storybook コンポーネント	component-audit、accessibility-check、performance-lint、design-system-sync	Figma connector、Storybook MCP	新規コンポーネントごとに 4 つのチェックを完了する
QA エンジニア	テストカバレッジレポート、E2E suite 診断、回帰チェックリスト	CI/CD テスト結果、過去の失敗履歴	test-coverage-check、e2e-suite-runner、flaky-test-diagnosis、regression-suite-builder	GitHub Actions/Jenkins などの CI/CD ツール接続	失敗テストを優先実行し、カバレッジを下げない
技術ドキュメントエンジニア	API docs 更新、Changelog 作成、移行ガイド	API schema、Git commit history	api-doc-generator、changelog-builder、readme-audit、migration-guide-writer	GitHub API、Schema ツール	API 変更時にドキュメントも同期更新する
セキュリティエンジニア	権限境界レビュー、secret チェック、依存関係のセキュリティスキャン	依存関係一覧、secret 保存設定	auth-boundary-check、secrets-scan、dependency-security	Snyk、Dependabot MCP	リリース前にセキュリティチェックリストを完了する

フロントエンド役割 Plugin の分解例

frontend-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── component-audit/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── component-template.md
│   ├── accessibility-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── axe-audit.sh
│   ├── performance-lint/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── lighthouse-check.sh
│   └── design-system-sync/
│       ├── SKILL.md
│       └── references/
│           └── design-tokens.md
├── assets/
│   └── templates/
│       └── component-template.tsx
└── README.md

component-audit Skill は、新規コンポーネントがチーム規約に合っているかを見ます。たとえば命名、ディレクトリ、props 型です。accessibility-check は axe-core スクリプトでアクセシビリティを確認します。performance-lint は Lighthouse で主要指標を見ます。design-system-sync は Figma の設計仕様と実装を突き合わせます。

QA 役割 Plugin の分解例

qa-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── test-coverage-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── coverage-threshold-check.sh
│   ├── e2e-suite-runner/
│   │   └── SKILL.md
│   ├── flaky-test-diagnosis/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── flaky-test-log-analysis.md
│   └── regression-suite-builder/
│       └── SKILL.md
├── .mcp.json
└── README.md

test-coverage-check はカバレッジ低下を検出し、未カバーのファイルを示します。e2e-suite-runner は優先度に従って E2E テストを実行します。flaky-test-diagnosis は過去の失敗ログから不安定なテストを探します。regression-suite-builder は変更範囲から回帰テストのチェックリストを作ります。

connector placeholder の置き換えチェックリスト

公式テンプレートの .app.json には placeholder connector id が入っていることがあります。インストール前に置き換えます。

{
  "app_id": "figma-placeholder"
}

.app.json 内のすべての placeholder id を確認し、対象 workspace で利用できる実 ID に置き換えます。別 workspace の connector id をそのままコピーしないでください。環境や権限が違うと無効です。MCP server 設定の OAuth/Bearer token も自分の環境に合わせて設定します。テンプレートの例をそのまま使うものではありません。置き換えたら、まずテスト環境で connector が使えるか検証します。

公式 role-specific-plugins README は、これらの Plugin テンプレートを利用前にカスタマイズする想定だと説明しています。connector-backed plugins には、置き換えるべき app ID や connector ID が含まれることがあります。

6. セキュリティと保守：Plugin は権限パスではない

Connector / MCP の権限境界

Plugin をインストールしても、Codex の approval settings は迂回されません。外部 app と MCP server には引き続き認可が必要で、データ共有もそれぞれのポリシーに従います。.app.json の placeholder id は置き換える必要がありますが、別 workspace の connector id をコピーしてはいけません。Figma や GitHub のような外部 app は個別に認可が必要です。Plugin は設定をまとめるだけで、認可そのものではありません。MCP server は config.toml で enabled や tool policy を引き続き制御できます。Approval mode も適用されます。“suggest-only” に設定していれば、Plugin 内のスクリプトは自動実行されません。

Plugin を権限パスとして扱わないでください。ワークフロー、設定、アセットをまとめるものですが、権限境界は残ります。

スクリプトの出所確認

Skill/Plugin の scripts/ ディレクトリには実行可能ファイルが含まれることがあります。サードパーティ Plugin やコミュニティ marketplace のスクリプトは確認が必要です。scripts 内の実行可能ファイルをすべて見て、出所を確認します。未検証リポジトリのスクリプトを直接実行しないでください。まずテスト環境で試し、production に未知の Plugin を直接入れない。バージョンは固定し、毎回 main から最新を取るのではなく、明確な tag や commit hash を使います。

過去に取り上げた第三者 Skill の悪意あるコードリスクと同じ原則が、実行可能スクリプトや第三者 Plugin にも当てはまります。出所を確認し、権限を最小化し、テスト環境で検証します。

バージョンと変更履歴

チーム運用にはバージョン管理が必要です。plugin.json に version を明記し、更新ごとに増やします。README には changelog を置き、追加された Skill、変更された Skill、廃止された Skill を記録します。アップグレード前にはテスト環境で検証し、すべての Skills を実行し、スクリプトが正常に動くことと connector がまだ利用できることを確認します。marketplace では ref を固定し、毎回 main の最新を取らないようにします。

Skill/Plugin の数が与える影響

Codex の初期 Skill 一覧にはコンテキスト予算があります。公式ドキュメントでは、初期 skills list はコンテキストのおよそ 2%、またはコンテキストサイズが不明なときに 8,000 characters 程度と説明されています。

実務上の影響はシンプルです。Skill description が長すぎると切られる可能性があるため、重要なトリガー語は前に置きます。Skills を入れすぎると、Codex がどれを使うべきか判断しにくくなります。高頻度で境界が明確な Skill は repo または user ディレクトリに向いています。低頻度の Skill は Plugin に入れ、必要なときだけインストールするほうがよいです。すべてを常駐させる必要はありません。

Codex が誤った Skill を呼ぶ、または必要な Skill を呼ばない場合は、まず description を確認します。Skill の数を増やして解決しようとしないほうが安全です。

7. 関連技術との比較

Claude Code Skills との比較

BetterLink では以前、Claude Code Skill の仕組みも扱いました。考え方は近いですが、製品は別です。どちらも Agent Skills のオープン形式と SKILL.md ファイルを使います。どちらも name、description、任意の scripts/、references/、assets/ を持ちます。metadata → instructions → resources という progressive disclosure も共通しています。

違いも重要です。パスは、Codex が .agents/skills/、Claude Code が .claude/skills/ です。呼び出しは、Codex が $skill-name または /skills、Claude Code が /skill コマンドです。Plugin 配布では、Codex Plugin に marketplace、CLI コマンド、workspace sharing があります。Claude Code には現時点で公式 Plugin marketplace はありません。内蔵ツールも違います。Codex には $skill-creator、$skill-installer、@plugin-creator があり、Claude Code には別の組み込みコマンドがあります。

Claude Code Skills を書いたことがあるなら、考え方は再利用できます。ただし、パスや呼び出し方法はコピーしないでください。それぞれの公式ドキュメントに合わせます。

MCP との分担

MCP（Model Context Protocol）は、外部ツールとコンテキストをつなぐためのものです。Skill や Plugin の代替ではありません。Skill はワークフローを定義します。MCP は Figma、GitHub、CI/CD system などの外部ツールにつなぎます。Plugin は MCP server 設定を同梱できますが、MCP server 自体は引き続き config.toml で制御されます。

例を挙げると、フロントエンドレビュー Skill は「コンポーネントが設計仕様に合っているか確認する」手順を定義します。Figma MCP server は設計ファイルへアクセスする能力を提供します。フロントエンド Plugin はレビュー Skill と Figma MCP 設定をまとめます。ただし、Figma OAuth は別途認可が必要です。

ここでは分担だけを整理しました。Codex MCP tools の実践は別の記事で詳しく扱います。

まとめ

Codex Skills と Plugins の価値は、チームの繰り返し手順をコピーした prompt や肥大化した AGENTS.md から取り出し、再利用できる能力として残せることです。目安は単純です。永続ルールは AGENTS.md、複数ステップの手順は Skill、配布とパッケージ化は Plugin、外部システム接続は MCP。description にはトリガー条件を明確に書き、まず local skill で検証してから、配布が必要になった段階で Plugin にします。第三者 Plugin の scripts、connector id、MCP 設定は引き続き確認が必要です。

最初は 1 つの最小 Skill で十分です。チームのコードレビュー手順やテスト手順を SKILL.md にし、数回実行してトリガーが安定するか確認します。フロントエンド、QA、セキュリティ、ドキュメントなどの役割があるなら、OpenAI role-specific-plugins の分解方法を参考に、役割ごとに 3〜5 個の小さな Skill を切り出し、role plugin としてまとめます。

BetterLink の関連読み物：

• Codex 入門完全ガイド
• AGENTS.md プロジェクトルール
• Codex のセキュリティ境界と権限管理
• Codex MCP tools 実践
• Claude Code Skill との比較
• MCP プロトコルの基礎