【2026年最新】Codex Skills 完全ガイド｜自作7パターン+5ステップ

「Codexにカスタム機能を追加できるって聞いたけど、どこに何を置けばいいのか全然わからない……」

先日、ある企業の開発チームリーダーからこんな相談を受けました。OpenAIが2025年末から正式公開した「Codex Skills」という仕組みを導入しようとしたものの、配置パスの種類が複数あって迷子になった、というんです。

実はこれ、初めてSkillsに触れる人がほぼ全員つまずく場所です。ドキュメントには4種類の配置パスが並んでいますが、「どれを使えばいいのか」が書いていない。そこを正確に理解するだけで、作業の質が段違いに変わります。

この記事では、Codex Skillsの仕様と自作方法を、コピペできるSKILL.mdテンプレートつきで完全ガイドします。7つの業務パターン別Skill設計と、アップデート対応の運用フローまでカバーしているので、今日から使える状態を整えられます。

Codex Skillsとは何か：30秒でわかる概要

Codex Skillsは、指示・スクリプト・参照資料をひとつのフォルダにまとめた「再利用可能なワークフローパッケージ」です。OpenAIが2025年後半にオープンエージェントスキル標準（Open Agent Skills Standard）として公開し、2026年に入ってCLI・IDEプラグイン・Codexアプリの全プラットフォームで正式サポートされました。（参照日: 2026-06-03、出典: OpenAI Developers – Agent Skills）

簡単にいうと、「この手順に従って作業して」という指示書（SKILL.md）をCodexが認識して、毎回一定のクオリティで実行してくれる仕組みです。

SkillはどうやってCodexに認識されるか

Codexは起動時に、登録されたSkillのname・description・ファイルパスを一覧として読み込みます。タスクに応じて2つの起動方式があります。

明示的呼び出しはCLIとIDEでは$メンション方式、Codexアプリでは/skillsコマンドから選ぶ方式が使えます。

Skillの配置パス：4種類の使い分けルール

ここが最も混乱しやすいポイントです。Codexは以下の4つのパスを順番にスキャンしてSkillを探します。（出典: OpenAI Developers – Agent Skills、参照日: 2026-06-03）

実用的な使い分けの原則はシンプルです。

• 個人の定番作業（コードレビュー・コミットメッセージ生成など）→ ~/.agents/skills/
• チーム全員に使わせたい標準フロー → .agents/skills/（リポジトリルートにコミット）
• 特定プロジェクトにしか使えないロジック → .agents/skills/（プロジェクトルート）

Uravation現場メモ: 顧問先のある企業でCodex Skillsを導入した際、最初に「全員共有のリポジトリ用」と「個人の作業効率用」を分けて設計しました。コードレビュー基準はリポジトリ側、個人の定型コミット文生成はホーム側。この分け方で「誰かのSkillが他の人の環境に影響する」問題が消えました。

Codexはシンボリックリンクをサポートしています。複数のプロジェクトで同一Skillを共有したい場合、一箇所に実体を置いてシンボリックリンクを張る方式が使えます。またSkillの変更は自動検出されるため、再起動なしに即反映されます（新規Skill追加時のみ再起動が必要）。

SKILL.mdの書き方：最小構成から完全版まで

Skillのディレクトリ構造は以下の通りです。必須なのはSKILL.mdだけです。

my-skill/
├── SKILL.md              # 必須：名前・説明・指示書
├── agents/
│   └── openai.yaml       # 任意：UI設定・起動ポリシー・ツール依存関係
├── scripts/              # 任意：実行可能スクリプト
├── references/           # 任意：参照ドキュメント
└── assets/               # 任意：出力ファイル置き場

最小構成のSKILL.md

---
name: commit-message
description: Use when generating git commit messages from staged changes. Triggers on "commit", "コミット", "commit message作って".
---

staged changesの内容を確認し、以下のルールでコミットメッセージを生成する:
1. 形式: `: `
2. type は feat/fix/refactor/docs/test/chore から選ぶ
3. description は動詞から始める命令形（英語）
4. 本文が必要な場合は空行を挟んで追記

出力はコードブロックで囲む。複数案を提示しない。

descriptionは「どんな言葉でトリガーされるか」を具体的に書くのがコツです。暗黙的呼び出しの精度に直結します。

agents/openai.yaml の設定

Codexアプリでの見え方やUIをカスタマイズしたい場合に追加します。

interface:
  display_name: "コミットメッセージ生成"
  icon_small: "./assets/icon.svg"
  brand_color: "#007a8a"

policy:
  allow_implicit_invocation: false   # 明示的呼び出しのみに限定

dependencies:
  tools:
    - type: "mcp"
      value: "github"

allow_implicit_invocation: falseを設定すると、Codexが勝手にSkillを適用することを防げます。機密性の高いワークフローや、特定の条件でしか使ってはいけない処理に有効です。

config.tomlでの有効/無効管理

# ~/.codex/config.toml

[[skills.config]]
path = "/Users/username/.agents/skills/commit-message"
enabled = true

[[skills.config]]
path = "/Users/username/.agents/skills/old-workflow"
enabled = false   # 削除せずに無効化

削除するのではなくenabled = falseで無効化するのが運用のベストプラクティスです。後で有効に戻せますし、チームメンバーへの変更説明もconfig.tomlの差分で伝えられます。

Codex Skillsを活用したエージェント設計の全体像については、Codex AGENTS.md完全ガイド｜プロジェクト指示書の書き方7パターンも合わせてご覧ください。

自作Skill 7パターン：コピペ可能SKILL.mdテンプレ

以下は実際に業務で使える7種類のSkillテンプレートです。それぞれのdescriptionには、暗黙的呼び出しで正確にトリガーされるよう、トリガーワードを具体的に記載してあります。

パターン1：コードレビューSkill

---
name: code-review
description: Use for code review of pull requests or specific files. Triggers on "review", "レビュー", "PR確認", "コードチェック", "code review". Do NOT use for writing new code.
---

# コードレビュー指示

対象コードを以下の観点で評価し、Markdownでレポートを出力する:

## 評価項目
1. **バグ・エラー**: ロジックの誤り、例外未処理、境界値
2. **セキュリティ**: インジェクション、認証漏れ、機密情報ハードコード
3. **パフォーマンス**: 不要なループ、N+1、メモリリーク懸念
4. **可読性**: 変数名、関数分割、コメント不足
5. **テスト**: テストの欠如、カバレッジ不足

## 出力形式
- 🔴 CRITICAL: 本番リリース前に必ず修正
- 🟡 MAJOR: リリース前に対応推奨
- 🟢 MINOR: 改善提案（任意）

各指摘に修正案のコードスニペットを添付する。

パターン2：テスト生成Skill

---
name: test-generator
description: Use when generating unit tests or integration tests for existing code. Triggers on "テスト生成", "test作って", "ユニットテスト", "unit test", "spec書いて".
---

# テスト生成指示

対象コードを解析し、以下の方針でテストを生成する:

1. **境界値テスト必須**: 空文字・null・最大値・最小値
2. **ハッピーパスとエラーパスを両方カバー**
3. **テストの命名**: `test_関数名_条件_期待結果` 形式
4. **モック戦略**: 外部依存（DB・API・ファイルI/O）は必ずモック化

プロジェクトのテストフレームワーク（package.json / pyproject.toml等で確認）に合わせる。
テストは単体で動作し、環境依存を排除すること。

パターン3：リサーチ・情報収集Skill

---
name: research
description: Use for researching topics, summarizing documents, or gathering information. Triggers on "調査", "リサーチ", "まとめて", "要約", "research", "調べて". Scope: information gathering only, NOT for implementing code.
---

# リサーチ指示

1. **ソース明記必須**: 各情報源のURL・日付を記録
2. **情報の鮮度確認**: 1年以上前の情報は「要確認」フラグを付ける
3. **要約構造**:
   - TL;DR（3文以内）
   - キーポイント（箇条書き5点以内）
   - 詳細（見出し付き）
   - 未解決の疑問点
4. **不明な点は「確認できていません」と明示** — 推測を事実として書かない

パターン4：ドキュメント生成Skill

---
name: doc-generator
description: Use for generating documentation from code, including README, API docs, and inline comments. Triggers on "ドキュメント", "README", "ドキュメント化", "API仕様書", "doc generate".
---

# ドキュメント生成指示

対象コードに応じて適切な形式でドキュメントを生成:

## README.md（リポジトリルートのコード指定時）
- Overview: プロジェクト概要（1段落）
- Quick Start: 最低限の起動手順（コード付き）
- Configuration: 環境変数・設定ファイル一覧
- API Reference: パブリックな関数・エンドポイントの全リスト

## 関数コメント（個別関数指定時）
- JSDoc / Docstring形式（言語に応じて選択）
- @param / @returns / @throws を網羅
- 使用例を1つ含める

既存コメントと矛盾しないように注意。日本語・英語はコードベースの既存スタイルに合わせる。

パターン5：セキュリティレビューSkill

---
name: security-review
description: Use for security analysis of code, configuration files, or architecture. Triggers on "セキュリティ", "脆弱性", "security", "vulnerability", "セキュリティチェック". Do NOT use for general code review.
---

# セキュリティレビュー指示

OWASP Top 10 + プロジェクト固有リスクで評価:

## 必須チェック項目
1. **認証・認可**: 未認証アクセス、権限昇格の可能性
2. **入力検証**: SQLインジェクション、XSS、パス トラバーサル
3. **機密情報**: APIキー・パスワードのハードコード、ログへの出力
4. **依存関係**: 既知脆弱性のあるライブラリ（CVE確認）
5. **暗号化**: 弱いアルゴリズム、鍵管理の問題

## 出力
- CRITICAL（即修正）/ HIGH（24h以内）/ MEDIUM（1週間以内）/ LOW（任意）の4段階
- 各リスクに: 脆弱性の種類・影響範囲・具体的な修正手順

パターン6：翻訳・多言語対応Skill

---
name: translate
description: Use for translating code comments, documentation, or UI strings. Triggers on "翻訳", "translate", "英訳", "日本語化", "i18n", "localization". Scope: text translation in software context only.
---

# 翻訳指示

## ソフトウェア文脈の翻訳方針
1. **技術用語は原語を保持**: API・SDK・README等の業界標準用語はそのまま
2. **UIテキスト**: 自然な言い回しを優先（逐語訳NG）
3. **コメント・ドキュメント**: 意味の正確さを最優先

## 日→英の注意点
- 主語を明示する（日本語の省略主語を英語で補う）
- 受動態より能動態を優先

## 英→日の注意点
- カタカナ乱用を避ける（「インプリメント」より「実装」）
- 敬体・常体はファイル内の既存スタイルに合わせる

翻訳後に「変更した箇所の数」と「要注意の文脈依存ワード」をサマリーで報告する。

パターン7：プロジェクト固有Skill（設計テンプレ）

---
name: project-deploy
description: Use when deploying [プロジェクト名] to staging or production. Triggers on "デプロイ", "deploy", "リリース", "本番反映". ONLY for [プロジェクト名] repository.
---

# デプロイ指示（[プロジェクト名]専用）

## デプロイ前チェックリスト
1. [ ] テストが全件パスしているか確認: `npm test`
2. [ ] 環境変数が本番用に設定されているか確認
3. [ ] CHANGELOG.mdに今回の変更が記載されているか

## デプロイ手順
1. mainブランチへのマージを確認
2. `./deploy.sh --env [staging|production]` を実行
3. デプロイ後にヘルスチェックURL（[URL]）を確認

## ロールバック手順
`./deploy.sh --rollback` でひとつ前のバージョンに戻す

チームへの完了通知: Slackの#deployチャンネルに結果を報告する。

Uravation現場メモ: 上記7パターンを実際に複数社で導入してみて気づいたのは、パターン7（プロジェクト固有Skill）の効果が最も高いということです。チーム全員が「このリポジトリにはどんなデプロイ手順があるか」をCodexに聞けるようになり、口頭伝承やWikiの陳腐化が一気に解消されました。

5ステップ：Codex Skillを今日から作る完全フロー

1. $skill-creatorで雛形を生成する

   CodexのCLIまたはアプリで $skill-creator を呼び出すと、名前・説明を対話式に入力でき、標準ディレクトリ構造とSKILL.mdのフロントマターが自動生成されます。ゼロから手書きする必要はありません。

   # CLI での実行例
   codex
   > $skill-creator
   
   ? Skill name: code-review
   ? Description: Use for code review of pull requests...
   → ~/.agents/skills/code-review/SKILL.md が生成される

2. SKILL.mdの指示部分を業務フローに合わせて書く

   自動生成されたSKILL.mdのフロントマター（name・description）はそのまま使い、本文部分に具体的な手順を書きます。「命令型・箇条書き・明確なアウトプット形式指定」の3点を守ると再現性が高まります。

3. agents/openai.yamlで起動ポリシーを設定する

   チーム共有Skillの場合、allow_implicit_invocation: falseを設定して意図しない暗黙起動を防ぎます。MCPツールへの依存がある場合はdependenciesセクションに明記します。

4. ~/.codex/config.tomlに登録してテストする

   Skillを置いたパスをconfig.tomlの[[skills.config]]に追加します。Codexを再起動後、明示的呼び出しで動作を確認します。

   [[skills.config]]
   path = "/Users/username/.agents/skills/code-review"
   enabled = true

5. チームリポジトリにコミットして共有する

   チーム全員に使わせたいSkillは .agents/skills/ ディレクトリをリポジトリルートに作り、SKILL.mdとagents/openai.yamlをコミットします。新しいメンバーがリポジトリをcloneすると自動的にSkillが使えるようになります。

Curated Skillsのインストールとアップデート運用

OpenAIはCodex公式のSkillsカタログをgithub.com/openai/skillsで公開しています（スター21,000以上、2026年6月時点）。3種類に分類されています。

インストールコマンドの使い方

# Curated Skillをインストール（例：GitHubコメント対応Skill）
$skill-installer gh-address-comments

# Experimental Skillをインストール（GitHubのURLを指定）
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

# インストール後はCodexを再起動（新規Skill認識のため）

アップデート対応5ステップ

Codex本体のアップデートに合わせてSkillも更新が必要になります。以下の手順で定期的に確認します。

1. Codex Changelogを購読する

   developers.openai.com/codex/changelogでリリースノートを確認します。Skills関連の変更は「Agent Skills」セクションに集中しています。

2. github.com/openai/skillsのリリースタグを確認する

   Skillsカタログ側のアップデートはCodexのバージョンと独立して管理されています。Watchまたはgh repo watch openai/skillsで変更通知を受け取る設定がおすすめです。

3. 既存Curated Skillを再インストールする

   Curated Skillを最新版に更新するには、$skill-installerで再インストールします。上書きされるのはCuratedのSkill定義ファイルのみで、自作のCustom Skillは影響を受けません。

4. 自作SkillのAGENTS.md連携を確認する

   Codexのバージョンアップでフロントマターの仕様が拡張されることがあります。公式Skillsドキュメントで最新のopenai.yaml設定項目を確認し、deprecatedな設定が残っていないかチェックします。

5. チームにCI/CDで変更を通知する

   リポジトリ内の.agents/skills/に変更があった際にSlackへ通知するGitHub Actionsを設定すると、チームメンバー全員が変更を見逃しません。

Uravation現場メモ: 顧問先のエンジニアチームで.agents/skills/をリポジトリに入れ始めてから、「この作業どうやるんでしたっけ？」という口頭確認が目に見えて減りました。Skillのdescriptionが一種のFAQになっているんですね。新しいメンバーのオンボーディング時間が短くなるという副次効果もありました。

Codex Skillsのアップデート：2026年6月時点の最新仕様

2026年5月〜6月にかけて、Codex本体に大きなアップデートが入り、Skillsに関連する変更も含まれています。（出典: Codex Changelog、参照日: 2026-06-03）

主要アップデートとSkillsへの影響

特に注目はGoal mode（ゴールモード）の標準化です。以前は実験的機能でしたが、2026年5月21日から全環境で標準搭載されました。Goal modeとSkillを組み合わせると、「このプロジェクトの最終目標をSkillが把握した上で実行する」という使い方ができ、単純なマクロを超えた挙動が可能になっています。

また、非エンジニアによるCodexの採用が加速しており、週次ユーザー500万人のうち約20%が非エンジニアです。SkillsはもともとエンジニアのCI/CDワークフロー向けが中心でしたが、データアナリスト・マーケター・オペレーション担当者向けのCurated Skillsも増えています。（出典: VentureBeat、参照日: 2026-06-03）

【要注意】Codex Skillsの失敗パターン4選

実際の現場でよく見る失敗と、その回避策を整理します。

失敗1：トリガーが競合して意図しないSkillが起動する

❌ よくある間違い: 2つのSkillのdescriptionに同じキーワードが入っている。例えば「code-review」と「security-review」の両方に「レビュー」と書いてある。

⭕ 正しいアプローチ: 各Skillに否定例を入れる。

description: Use for security analysis. Triggers on "セキュリティ", "脆弱性", "security", "CVE".
Do NOT use for general code review（そちらは $code-review スキルが対応）.

Codexは複数のSkillが一致した場合、最も具体的なdescriptionを優先しますが、明示的な「〜はしない」という記述があると判定精度が上がります。

Uravation現場メモ: ある開発チームで「レビュー」というキーワードが3つのSkillに入っていて、どれが起動されるか毎回違うという問題が起きました。否定例を追加して解消しましたが、Skillが増えてくるとこの問題が必ず出てきます。Skill設計の段階でトリガー語を被らせない規則を決めておくことを強くおすすめします。

失敗2：配置パスを間違えて「Skillが見つからない」になる

❌ よくある間違い: ~/.codex/skills/（codex配下）に置いている。正しい配置パスは~/.agents/skills/（agents配下）です。

⭕ 正しいアプローチ: パス確認コマンドで現在認識されているSkillを一覧する。

# CLI で認識されているSkill一覧を確認
codex
> /skills

# または明示呼び出しで確認
> $skill-name
→ 「skill not found」が出たら配置パスを確認

Codexが認識するパスは$CWD/.agents/skills/・$REPO_ROOT/.agents/skills/・$HOME/.agents/skills/・/etc/codex/skills/の4つのみです。これ以外に置いても認識されません。

失敗3：古いバージョンのSkillを放置してCodex本体と乖離する

❌ よくある間違い: Curated Skillsを最初にインストールした後、Codex本体のみアップデートして放置する。openai.yamlの仕様変更が入った際に動作がおかしくなる。

⭕ 正しいアプローチ: CodexのマイナーアップデートのたびにChangelogを確認し、Skills関連の変更があれば$skill-installerで再インストールする。月1回の定期メンテナンスとして習慣化するのが現実的です。

失敗4：SKILL.mdとAGENTS.mdが競合して想定外の動作になる

❌ よくある間違い: リポジトリのAGENTS.mdに「コードレビューは必ず〜の手順で行う」と書かれていて、且つcode-review Skillにも別の手順が書かれている。両者が矛盾していると、どちらが優先されるかが不安定になる。

⭕ 正しいアプローチ: AGENTS.mdは「プロジェクト全体の一般方針」、SKILL.mdは「特定タスクの詳細手順」として役割を分ける。AGENTS.mdには「詳細な手順は$code-review Skillを参照」と書いて委譲し、重複を避ける。

Claude Code Skills との対比表

Codex Skillsと、AnthropicのClaude Code Agentのスキル仕組みを使っている場合、違いを正確に理解しておく必要があります。

両方のツールを使う場合、最も重要な違いは配置パスです。Codex Skillsは.agents/配下、Claude Codeは.claude/配下と明確に分かれているので、混在してもファイルが衝突することはありません。

ただし、AGENTS.mdとCLAUDE.mdの両方があるリポジトリでは、それぞれのエージェントがどちらのファイルを読むかを明確にしておく必要があります。CodexはAGENTS.mdを、Claude CodeはCLAUDE.mdを優先して読みます。

チーム導入ロードマップ：3週間で全員が使いこなす手順

「Skillsを導入しよう」と決めてから、チーム全員が使いこなせる状態になるまでの現実的なロードマップです。

3週目で最も重要なのがdescriptionのレビューです。トリガーが曖昧だったり競合しやすかったりするSkillが必ず出てきます。全員が作ったSkillを持ち寄って「このdescriptionだと何が起動する？」を確認するセッションが、品質の底上げに効きます。

Codex全体の機能最新動向については、OpenAI Codex 大型アップデート完全解説も参考にしてください。

まとめ：今日から始める3つのアクション

1. 今日やること: $skill-creatorを使って自分が毎日やる作業（コミットメッセージ or コードレビュー）のSkillを1本作り、~/.agents/skills/に配置して動作確認する
2. 今週中: チームで最も繰り返している作業フロー（デプロイ手順・PRレビュー基準）をSkillにまとめ、.agents/skills/としてリポジトリにコミットしてチームに共有する
3. 今月中: github.com/openai/skillsのCurated Skillsカタログを全員で確認し、すでに公式で用意されているSkillは$skill-installerでインストールして車輪の再発明をしない体制を整える

あわせて読みたい:

• Codex CLI vs Claude Code 料金比較ガイド｜プラン早見表+業務別使い分け7パターン
• OpenAI Codex 大型アップデート完全解説｜6プラグイン・Sites・Bedrock対応で何が変わる
• Codex AGENTS.md完全ガイド｜プロジェクト指示書の書き方7パターン+階層設計

参考・出典

• Agent Skills – Codex | OpenAI Developers — OpenAI（参照日: 2026-06-03）
• Changelog – Codex | OpenAI Developers — OpenAI（参照日: 2026-06-03）
• openai/skills: Skills Catalog for Codex – GitHub — OpenAI（参照日: 2026-06-03）
• Configuration Reference – Codex | OpenAI Developers — OpenAI（参照日: 2026-06-03）
• OpenAI’s Codex update lets agents build interactive enterprise workspaces via Sites and role-specific plugins — VentureBeat（参照日: 2026-06-03）

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。
100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。
SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。

ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。