【2026年最新】Codex Skillsガイド｜使い方・作り方・おすすめ7選

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

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

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

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

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

📊 Codex完全リファレンス: 機能網羅マトリクス・利用形態の判断フローはCodex完全リファレンス（ピラー版）へ。

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は「リポジトリ（CWDからREPO_ROOTまで各階層の.agents/skills）」「ユーザー（$HOME/.agents/skills）」「管理者（/etc/codex/skills）」「System Skills」を参照して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〜REPO_ROOTの各階層にある.agents/skills）」「$HOME/.agents/skills/」「/etc/codex/skills/」「System Skills」です。

失敗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 大型アップデート完全解説も参考にしてください。

Codex Skills 一覧 完全版：公式+コミュニティ全網羅

「どんなSkillsがあるか全体像をつかみたい」という声を開発チームのリーダーから何度も聞いてきました。公式ドキュメントはカテゴリ別に分散していて一覧しにくいので、ここで System・Curated・Experimentalの3層を一気に整理します。

System Skills（5種・自動インストール済み）

Codexの最新版に同梱されており、インストール不要で即使えるコアスキルです。（出典: Codex Knowledge Base – Official Skills Catalogue、参照日: 2026-06-11）

Curated Skills カテゴリ別一覧

OpenAIが審査した本番環境対応スキルです。$skill-installer スキル名でインストールできます。2026年7月5日時点で39種が公開されています。

コミュニティ発のおすすめSkillsリポジトリ

公式以外にも、実用度の高いコミュニティ製Skillsが複数のリポジトリにまとめられています。

Uravation現場メモ: ある企業の開発チームで「公式38本＋ComposioHQ製10本」を導入したとき、最初はインストールしすぎてSkillが乱立する問題が起きました。現場でわかったルールは「月1本ずつ試して定着したものだけ残す」。一気に全部入れるより、使用頻度で取捨選択していくほうが定着率が高いです。Skillの一覧を把握しておくことと、全部使うことは別の話です。

Codex Skills おすすめベスト10：実測比較

Uravationの顧問・研修先での実導入フィードバックと、Sunny Kumar（The Guidex）による独立検証を組み合わせて、2026年現時点で特に効果の高いSkillsを10本選定しました。（参考: 10 Best Codex Skills (OpenAI) in 2026 — Tested by Sunny Kumar、参照日: 2026-06-11）

シーン別おすすめ組み合わせ

単体使いより「Skillの組み合わせ」で効果が倍増します。実際の開発フローで効果が高かった組み合わせを紹介します。

Uravation現場メモ: 複数の企業でCodex Skillsの研修を実施してきて、最も費用対効果が高いと感じるのは「gh-address-comments＋gh-fix-ciの2本セット」です。PRレビューのやりとりは開発チームが最も時間を取られる作業のひとつ。この2本を導入した企業では、シニアエンジニアがレビューに使う時間が半分以下になり、その分をアーキテクチャ設計に使えるようになったという声を複数聞いています。

インストールコマンド一覧（コピペ用）

# 公式 Curated（名前指定でインストール）
$skill-installer gh-address-comments
$skill-installer gh-fix-ci
$skill-installer playwright
$skill-installer figma-implement-design
$skill-installer security-threat-model
$skill-installer notion-meeting-intelligence
$skill-installer transcribe

# Experimental（カタログパス指定）
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

# コミュニティ（GitHubパス指定）
$skill-installer ComposioHQ/awesome-codex-skills/mcp-builder
$skill-installer ComposioHQ/awesome-codex-skills/codebase-migrate

# インストール後はCodexを再起動（新規Skill認識のため）
# 既存Skillの変更は再起動不要で自動反映される

Codex Skills 自作ガイド：ステップバイステップ

既存のCurated Skillsには「自社独自のワークフロー」は含まれていません。ここでは、実際に動くCustom Skillをゼロから作る手順を、現場でよくつまずくポイントを中心に解説します。

ステップ1：自作すべきワークフローの選び方

Skillを作る前に「これはSkillにすべきか？」を判断する基準が重要です。以下の条件を満たすワークフローだけをSkillにするのが原則です。

Uravation現場メモ: 研修先で「Skillを作りまくってしまった」という相談を何度か受けました。月に1回しか使わない作業をSkillにして、description管理が煩雑になったというケースが典型です。「毎週やっていることだけをSkillにする」というルールを最初に決めると、Skill数が適切な範囲に収まります。

ステップ2：$skill-creatorでスキャフォールドを生成する

ゼロからSKILL.mdを手書きするのは非効率です。Codexに組み込まれた$skill-creatorを使うと、フロントマターと基本構造が自動生成されます。

# Codex CLIを起動して $skill-creator を呼び出す
codex
> $skill-creator

# 対話式の質問に答えていく
? Skill name（英小文字ハイフン区切り）: weekly-pr-report
? Description（暗黙的呼び出しのトリガー文を含める）:
  Use for generating weekly PR activity reports. Triggers on "週次PRレポート",
  "PR report", "PR活動まとめ". Do NOT use for individual PR review.
? Where to place: ~/.agents/skills/ （個人用）or .agents/skills/ （チーム用）
→ ~/.agents/skills/weekly-pr-report/SKILL.md が生成される

ステップ3：SKILL.mdの「指示部分」を書く5つのコツ

descriptionとフロントマターは自動生成されます。品質を決めるのはその下の指示本文です。現場で試して効果が高かった5つのコツをまとめます。

コツ1：命令形の箇条書きで書く（「する」ではなく「せよ」）

❌ 悪い例：
コードレビューを行い、問題点を見つけてください。
バグがあれば指摘してもよい。

⭕ 良い例：
対象コードの以下の観点で評価せよ：
1. バグ・エラー（境界値・例外未処理）
2. セキュリティ（インジェクション・認証漏れ）
各指摘に修正案のコードスニペットを添付すること。

コツ2：アウトプット形式を明示する

出力形式（必ず守ること）：
- セクション1: TL;DR（3文以内）
- セクション2: Critical（🔴）/ Major（🟡）/ Minor（🟢）の3段階で分類
- セクション3: 修正後のコードスニペット（コピペ可能な形式）

コツ3：「しないこと」を明記する

このSkillがやらないこと（重要）：
- 新しいコードを書かない（レビューのみ）
- リファクタリング案を実装しない（提案のみ）
- テストを自動で追加しない

コツ4：エラー時の動作を定義する

エラーハンドリング：
- 対象ファイルが見つからない場合：「ファイルパスを確認してください」と出力して停止
- 対象コードが空の場合：「レビュー対象が空です」と出力して停止
- 500行を超えるファイルの場合：「ファイルが大きすぎます。関数単位で指定してください」と警告

コツ5：参照ドキュメントはreferences/に分離する

# SKILL.md 内の参照指定
詳細なコーディング規約は references/coding-standards.md を参照すること。
出力テンプレートは references/review-template.md を使用すること。

ステップ4：agents/openai.yamlで起動ポリシーを設定する

本番ワークフローに組み込む場合は、暗黙的呼び出しをオフにして意図しない起動を防ぎます。

# .agents/skills/weekly-pr-report/agents/openai.yaml
interface:
  display_name: "週次PRアクティビティレポート"
  brand_color: "#007a8a"

policy:
  allow_implicit_invocation: false  # 明示的呼び出し（$weekly-pr-report）のみ

dependencies:
  tools:
    - type: "mcp"
      value: "github"  # GitHub MCP連携が必要な場合

ステップ5：動作テストと本番投入

Skillを配置したら、本番投入前に以下の手順で動作を確認します。

# 1. Skillが認識されているか確認
codex
> /skills
→ weekly-pr-report が一覧に表示されることを確認

# 2. 明示的呼び出しでテスト
> $weekly-pr-report
→ 期待するフォーマットで出力されることを確認

# 3. 暗黙的呼び出しのテスト（allow_implicit_invocation: trueの場合のみ）
> 今週のPR活動をまとめてほしい
→ weekly-pr-report が自動選択されることを確認

# 4. config.tomlに登録して有効化
# ~/.codex/config.toml に追加:
[[skills.config]]
path = "/Users/username/.agents/skills/weekly-pr-report"
enabled = true

失敗ゼロでチームに展開する3つのルール

Custom Skillをチームリポジトリに追加して全員に使わせる段階で、よく起きるトラブルと防止策を整理します。

Codex Skillsを活用した法人向けAI内製化の進め方については、Claude Fable 5の企業導入プログラムでも詳しく解説しています。企業全体でAIエージェントを定着させるための組織設計から、Skill設計の支援まで対応しています。

Codex Skillsのトラブルシューティング：認識されない・動かない時の診断フロー

「SKILL.mdを置いたのにCodexが呼び出してくれない」——Codex Skillsを使い始めた開発者から最もよく受ける相談がこれです。原因は大抵、配置パスのミスかフロントマターの書き方、あるいは再起動の忘れのどれかです。体系的に潰す手順を整理しました。

（出典: OpenAI Developers – Agent Skills、参照日: 2026-06-14）

ステップ1：配置パスを確認する

Codexが参照するのは、リポジトリ内各階層（CWD〜REPO_ROOT）の.agents/skills、$HOME/.agents/skills、/etc/codex/skills、System Skillsです。

よくあるミスは「~/.codex/skills/」や「.codex/skills/」など、微妙に違うパスに置いてしまうケースです。必ず.agents/skills/（ドットagents）であることを確認してください。.codex/はconfig.tomlなどの設定ファイルを置くディレクトリで、Skillの格納場所ではありません。

ステップ2：SKILL.mdのフロントマターを検証する

フロントマターに不備があると、Codexはそのスキルを無効扱いにします。最小構成の正しい書き方は以下の通りです。

---
name: skill-name            # 半角英小文字・ハイフン区切り必須
description: When this skill should be used. Include trigger words.
---

# ここからSkillの本文

よくある記法ミス:

• ---（三連ハイフン）の前後に空行を入れる ← これはエラー。---はファイル冒頭1行目から始める
• nameに日本語や大文字を使う ← 半角英小文字・ハイフンのみ使用可
• descriptionを空にする、またはフォールドスタイル（>）で長文にする ← 1行の平文で書く
• YAML内でダブルクォートを使わずコロンを入れる ← : を含む場合はdescription: "Use when: ..."とクォート必須

ステップ3：再起動の要否を確認する

Codexの再起動が必要なタイミングと不要なタイミングを正確に把握しておくと、無駄な混乱を避けられます。

ステップ4：config.tomlで明示的に有効化する

スキルが配置パスに存在するにもかかわらず認識されない場合、~/.codex/config.tomlでenabled = falseが残っている可能性があります。以下で現在の設定を確認してください。

# ~/.codex/config.toml の確認

# スキルが無効化されている場合
[[skills.config]]
path = "/Users/username/.agents/skills/my-skill"
enabled = false   # ← これが原因。trueに変更して再起動

# 明示的に有効化する場合
[[skills.config]]
path = "/Users/username/.agents/skills/my-skill"
enabled = true

config.tomlに記述がない場合のデフォルト動作: 配置パスに存在するSkillはすべて有効として扱われます。config.tomlへの記述は「無効化したい時のみ」必要と覚えておくと混乱しません。

ステップ5：暗黙的呼び出しが効かない場合の対処

descriptionに書いたトリガーワードを使っても呼び出されない場合、descriptionの書き方を見直します。

効果が低いdescriptionの例（NG）:

description: This skill is useful for many tasks.

効果が高いdescriptionの例（OK）:

description: Use when generating git commit messages. Triggers on "commit message", "コミットメッセージ", "commit作って", "git commit". Do NOT use for code review or branch creation.

ポイントは3つです。

1. 肯定トリガー: 「どんな言葉の時に使うか」を具体的に列挙する（日本語・英語の両方を書くと認識精度が上がる）
2. 否定スコープ: Do NOT use for ...の記述でスキルが誤った場面で呼ばれるのを防ぐ
3. 用途の一意性: 複数のスキルのdescriptionが「コードレビューに使う」と重複すると、Codexがどちらを選ぶか不定になる。スコープを分けるか、一方を削除する

現場の経験から: Codex Skillsの導入支援を行う中で「Skillが呼ばれない」問題の約8割は、パスのミス・フロントマター不備・再起動忘れのどれかでした。上記5ステップを順番に確認するだけで、ほとんどのケースは解決します。

Codex SkillsのチームGit管理：共有・バージョン管理・引き継ぎの実践手順

個人ワークフローを超えてチームにCodex Skillsを展開する時、最も重要になるのが「どこに置いてどうGit管理するか」の設計です。誤った設計をすると「Aさんのマシンでは動くがBさんのマシンでは動かない」問題が頻発します。（出典: github.com/openai/skills、参照日: 2026-06-14）

チームSkillの推奨配置設計

チーム共有Skillはリポジトリに含める設計が最もトラブルが少なく、Git管理と相性が良い方式です。

リポジトリにSkillをコミットする際の推奨構成

my-project/
├── .agents/
│   └── skills/
│       ├── code-review/
│       │   ├── SKILL.md              # レビュー基準・指示書
│       │   └── references/
│       │       └── coding-standards.md  # レビュー時に参照する規約
│       ├── commit-message/
│       │   └── SKILL.md
│       └── deploy-checklist/
│           ├── SKILL.md
│           └── scripts/
│               └── pre-deploy.sh     # デプロイ前チェックスクリプト
├── src/
└── README.md

.agents/ディレクトリをプロジェクトルートに置いてGitにコミットすることで、git cloneした全員が即座に同じSkillセットを使えます。チームオンボーディングのコストを大きく下げられる構成です。

Skillのバージョン管理：更新時の注意点

Skillを更新する時は、本番業務への影響を最小化するための3つのルールを守ります。

1. nameは変更しない: SKILL.mdのフロントマターにあるnameを変更すると、他のSkillやConfig.tomlから参照している場合に参照切れが起きます。nameを変えたい場合は新規Skillとして作り直し、旧Skillをenabled = falseで無効化します。

2. 破壊的変更はブランチでテスト: Skillの指示本文を大きく変更する場合、開発ブランチで変更をテストしてからmainにマージします。特にチームで共有しているSkillは、一人が変更するとその瞬間から全員の動作が変わります。

3. CHANGELOG.mdをSkillディレクトリ内に置く: 公式ドキュメントでは言及されていませんが、実際の現場で効果が高い慣習です。各Skillディレクトリに変更履歴を残しておくことで、「なぜこのdescriptionになったのか」をチーム全員が把握できます。

シンボリックリンクで複数リポジトリに同一Skillを共有する

Codexはシンボリックリンクをサポートしています。同一Skillを複数のリポジトリで共有する場合、Skillの実体を一箇所に置いてシンボリックリンクを張る方式が使えます。

# 1. 実体を個人のSkillsディレクトリに置く
mkdir -p ~/.agents/skills/code-review

# 2. プロジェクトAとプロジェクトBからシンボリックリンクを張る
cd ~/projects/project-a
mkdir -p .agents/skills
ln -s ~/.agents/skills/code-review .agents/skills/code-review

cd ~/projects/project-b
mkdir -p .agents/skills
ln -s ~/.agents/skills/code-review .agents/skills/code-review

# 一箇所のSKILL.mdを更新するだけで全プロジェクトに反映される

ただし、シンボリックリンクをGitリポジトリにコミットする場合、リンク先（~/.agents/skills/code-review）が他のチームメンバーのマシンに存在しないと動作しません。チーム全員のマシンで同じパスにSkillが存在する場合のみ使える方式です。チームで使うSkillは実体をリポジトリに含める設計の方が、環境依存を排除できます。

公式Curatedスキルをチームに展開する手順

github.com/openai/skillsのキュレーション済みスキルをインストールして試す場合、インストールコマンドは以下の通りです。

# CodexのCLIまたはアプリで実行

# キュレーション済みスキルをインストール
$skill-installer gh-address-comments

# 実験的スキルをインストール（スキル名を明示指定）
$skill-installer install the create-plan skill from the .experimental folder

# GitHub URLから直接インストール
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

インストール後は必ずCodexを再起動して認識させます。チームへの展開時は、上記コマンドをオンボーディングドキュメントに記載しておくのが最も確実な方法です。

Codex Skillsのチーム活用事例やエージェント全体の設計については、Codex完全リファレンス（ピラー版）に詳細をまとめています。

Codex Skills 実務レシピ3選：ビフォーアフターで見る使い方

テンプレートだけ見ても「自分の業務でどう効くのか」がイメージしにくい、という声を研修先で何度も受けてきました。ここでは、実際の開発フローにSkillを組み込んだ前後の変化を、具体的な手順とともに3パターン紹介します。いずれも公式の$skill-installer・$skill-creatorと.agents/skills/配置だけで再現できる構成です。（出典: OpenAI Developers – Agent Skills、参照日: 2026-06-29）

レシピ1：PRレビュー往復を1サイクルに圧縮する

レビューコメントへの対応は、コメントを読む→該当箇所を直す→返信する、の往復で時間が溶けがちな作業です。公式Curatedのgh-address-commentsを入れて、レビュー対応をひとつのフローにまとめます。

# 1. 公式Curatedをインストール
$skill-installer gh-address-comments

# 2. Codexを再起動（新規Skillの認識に必要）

# 3. 明示的に呼び出してレビュー対応を実行
> $gh-address-comments
→ 未対応のレビューコメントを読み、該当コードの修正案を生成

ポイントは、gh-address-commentsを明示的呼び出し（$メンション）で使うことです。レビュー対応は「やるタイミングを人が決めたい」作業なので、暗黙起動より明示起動が向いています。

レシピ2：自社のデプロイ手順を「聞けば出る」状態にする

デプロイ手順は属人化しやすく、Wikiは更新が止まりがちです。プロジェクト固有Skillを$REPO_ROOT/.agents/skills/にコミットして、リポジトリをcloneした全員が同じ手順を引ける状態を作ります。

# 1. リポジトリルートに配置ディレクトリを作る
mkdir -p .agents/skills/deploy-checklist

# 2. $skill-creator で雛形を生成、本文にデプロイ手順を書く
codex
> $skill-creator
? Skill name: deploy-checklist
? Description: Use when deploying this repo. Triggers on "デプロイ", "deploy", "本番反映".

# 3. .agents/skills/ ごとGitにコミット → clone した全員が利用可能

このときSKILL.mdの本文には、テストの実行コマンド・環境変数チェック・ロールバック手順を箇条書きで書いておきます。手順が変わったらSkillを編集してコミットするだけで、チーム全員の「最新手順」が自動で揃います。SKILL.mdの編集は再起動不要で自動検出されるため、運用負荷も小さく済みます。

レシピ3：設計MTGの記録を自動で構造化する

Skillは開発作業だけのものではありません。公式Curatedのtranscribeとnotion-meeting-intelligenceを組み合わせると、設計MTGの音声を文字起こしし、ToDoと要約に変換する流れを作れます。非エンジニアのメンバーでも使いやすい組み合わせです。

# 文字起こしSkillと議事録要約Skillをインストール
$skill-installer transcribe
$skill-installer notion-meeting-intelligence

OpenAIの公開情報によれば、Codexの週次ユーザーのうち約2割が非エンジニアであり、こうしたメディア・ドキュメント系Curated Skillsの活用が広がっています。（出典: VentureBeat、参照日: 2026-06-29）

Uravation現場メモ: レシピを紹介すると「全部入れたい」となりがちですが、現場で定着率が高いのは「まず1レシピだけ2週間回す」やり方です。PRレビュー往復の圧縮（レシピ1）は効果が体感しやすく、最初の1本として推奨度が高いです。1本が定着してから次を足すと、Skillの乱立を防ぎながら効果を積み上げられます。

Codex Skills よくある質問（FAQ）

Codex Skillsの導入支援でよく受ける質問を、公式ドキュメントで裏が取れる範囲に絞って整理します。仕様が明記されていない項目は「公式に記載なし」と明示しています。（出典: OpenAI Developers – Agent Skills、参照日: 2026-06-29）

Q. Skillを一時的に無効化したい。削除しないとダメ？

削除は不要です。~/.codex/config.tomlに[[skills.config]]ブロックを追加し、enabled = falseを指定すれば、ファイルを残したまま無効化できます。再度有効にしたいときはtrueに戻すだけです。config.tomlの変更後はCodexの再起動が必要です。

# ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false   # ファイルを消さずに無効化

Q. Skillに引数（パラメータ）を渡せる？

公式ドキュメントには、Skillに引数を渡す専用の仕組みは記載されていません。現実的には、呼び出し時のプロンプトに対象や条件を自然文で添える運用になります（例: $code-review この関数だけレビューして）。SKILL.md本文側で「対象が指定されない場合は確認する」といった分岐を書いておくと、入力の揺れに強くなります。

Q. 暗黙的呼び出しを完全にオフにしたい

agents/openai.yamlでpolicy.allow_implicit_invocation: falseを設定します。デフォルトはtrue（暗黙起動あり）なので、明示呼び出しのみに限定したいSkillには必ずこの設定を入れます。機密性の高いワークフローや、意図せず起動すると困る処理に有効です。

Q. MCPツールに依存するSkillは、どう宣言する？

agents/openai.yamlのdependencies.toolsに記載します。type・valueに加え、必要に応じてtransportやurlも指定できます。依存を明記しておくと、別メンバーの環境で「ツールが無くて動かない」事故を防げます。

dependencies:
  tools:
    - type: "mcp"
      value: "github"
      transport: "streamable_http"
      url: "https://..."

Q. シンボリックリンクで置いたSkillは認識される？

認識されます。公式ドキュメントは、スキャン対象パスにあるシンボリックリンクのフォルダをたどってリンク先を読む、と明記しています。ただしGitにコミットして共有する場合、リンク先が他メンバーのマシンに同じパスで存在しないと動かないため、チーム共有Skillは実体をリポジトリに含める設計の方が安全です。

Q. ~/.codex/skills/に置いたら認識されなかった

配置パスの誤りです。Skillの格納先は.agents/skills/（ドットagents）であり、.codex/はconfig.tomlなどの設定ファイルを置くディレクトリです。Codexがスキャンするのは$CWD/.agents/skills・$REPO_ROOT/.agents/skills・$HOME/.agents/skills・/etc/codex/skillsなどの.agents/skills系パスのみです。

Q. Claude CodeのSKILL.mdをそのまま流用できる？

フロントマターの必須項目（name・description）とファイル名が共通なので、本文は概ね流用できます。ただし配置パスが異なります（Codexは.agents/skills/、Claude Codeは~/.claude/skills/）。設定ファイルもCodexはconfig.toml＋agents/openai.yaml、Claude Codeはsettings.jsonと別系統です。両者の違いは本記事の「Claude Code Skills との対比表」セクションで詳しくまとめています。

あわせて読みたい（Codex関連）

• Codex Record & Replay｜作業を1回録画してSkillを自動生成する
• Codex App 完全ガイド｜macOS・iOS・Windows対応＋セキュリティ設定
• Cursor vs Claude Code 完全比較｜料金・機能・チーム導入
• Codex CLIとは？使い方・コマンド一覧 完全リファレンス — config.tomlおすすめ設定つき

まとめ：今日から始める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ピックス）。

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