--- title: "Codex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】" url: "https://www.issoh.co.jp/tech/details/10181/" published: 2025-12-08 updated: 2026-09-27 categories: ["AIエージェント・MCP"] publisher: "株式会社一創" --- # Codex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】 Codex Skillsは、繰り返し使う作業手順や社内のやり方を「スキル」として`SKILL.md`にまとめ、OpenAI Codexのエージェントに必要なときだけ読み込ませる機能です。起動時はスキルの名前と説明だけを索引し、実際に使うと判断した時点で本文を読み込む（Progressive Disclosure）ため、コンテキストを無駄に膨らませずに手順を再利用できます。配置場所は当初の`~/.codex/skills`から`.agents/skills`へ移り、Anthropic発のAgent Skills標準に沿った仕様になりました。本記事はできること・作り方・配置場所・有効化・Claude Code/MCPとの違いを最新仕様で整理します。 ## まとめ：Codex Skillsの要点 - **正体**：手順・参照資料・任意スクリプトを1フォルダに束ね、`SKILL.md`でエージェントに手順を教える仕組み。Agent Skillsオープン標準に準拠。 - **できること**：CI失敗の修正、PRレビューコメント対応、コードベース解析、議事録からのアクション抽出、changelog生成など、定型ワークフローの委譲。 - **配置場所（現行）**：プロジェクトは`.agents/skills`、個人は`$HOME/.agents/skills`。旧来の`~/.codex/skills`はレガシー。 - **作り方**：フォルダを作り`SKILL.md`を置くだけ。フロントマターは`name`と`description`の2つのみ。 - **有効化**：初期は実験フラグが必要だったが、現行版は既定有効の場合がある（要バージョン確認）。設定は`~/.codex/config.toml`。 - **Claude/MCPとの関係**：Claude CodeのスキルとはAgent Skills標準に準拠した同形式。MCPは別物で、ライブなツール接続を担う。 以下、それぞれを仕様の出典つきで詳しく見ていきます。 ## Codex Skillsとは：仕組みと設計思想 ### SKILL.mdにワークフローを束ねる仕組み 1つのスキルは`SKILL.md`を必須とするフォルダで、その中に手順書（Markdown本文）に加えて`scripts/`（実行スクリプト）・`references/`（参照ドキュメント）・`assets/`（テンプレート）を任意で置けます。「デプロイ手順」「インシデント対応」のような、毎回同じプロンプトを書き直していた作業をライブラリ化し、エージェントに一貫した進め方を取らせるのが狙いです。 ### Progressive Disclosure：名前と説明だけを先読みする Codexは起動時、各スキルの`name`・`description`・パスだけを索引に読み込み、`SKILL.md`本文はエージェントがそのスキルを使うと判断した後にオンデマンドで読み込みます。この索引は公式仕様で「モデルのコンテキストウィンドウの最大2%、コンテキスト長が不明な場合は最大8,000文字」に制限されます。だからこそ、多数のスキルを登録しても常時のコンテキスト消費を抑えられます。 ### Anthropic発の「Agent Skills」標準に準拠 Codex Skillsは、Anthropicが2025年12月18日に公開したAgent Skillsオープン標準（agentskills.ioで管理）の上に成り立っています。同じ`SKILL.md`形式を採用するため、後述のようにClaude Code向けに書いたスキルをCodexへ持ち込むことも可能です。[Claude Codeのスキル機能](/tech/details/12534/)を使ったことがあれば、考え方はほぼそのまま通用します。 ## Codex Skillsでできること：任せられるタスク スキルは「手順の再利用」に向いた作業ほど効果が出ます。公式カタログ（openai/skills）やコミュニティ集（ComposioHQ/awesome-codex-skills）で実際に配布されている代表的なタスクは次のとおりです。 - **CI失敗の修正**：失敗したGitHub Actionsのチェックを調べ、原因を要約して修正案を出す（gh-fix-ci）。 - **PRレビュー対応**：現在のブランチのPRに付いたレビュー・Issueコメントを`gh`経由で処理する（gh-address-comments）。 - **コードベース解析**：Git履歴からホットスポットやバグの温床、属人化リスクを洗い出してから読み始める（codebase-recon）。 - **議事録の整理**：会議の書き起こしを要約し、決定事項と担当者つきアクションに落とす（meeting-notes-and-actions）。 - **changelog生成**：コミットやPRから変更履歴を生成する（changelog-generator）。 いずれも「毎回同じ判断基準・同じ手順で進めたい」定型作業です。逆に、その場限りの一回きりの調査や、都度異なる自由な設計判断が要る作業はスキル化の効果が薄く、通常のプロンプトで足ります。 ## Codex Skillsの配置場所とスコープ スキルの置き場所は複数のスコープに分かれ、Codexはカレントディレクトリからリポジトリのルートまでをさかのぼって`.agents/skills`を探索します。現行の公式仕様は次のとおりです。 | スコープ | パス | 用途 | | ------ | ---------------------- | -------------- | | REPO | `.agents/skills` | そのプロジェクト専用の手順 | | USER | `$HOME/.agents/skills` | 個人のプロジェクト横断スキル | | ADMIN | `/etc/codex/skills` | システム全体の既定スキル | | SYSTEM | Codex同梱 | 組み込みの標準スキル | 注意したいのが配置場所の変更です。2025年12月のリリース当初は個人用が`~/.codex/skills`、プロジェクト用が`.codex/skills`で、リポジトリ単位のスキルもその後のアップデートで加わりました。その後、エージェント非依存の`.agents/skills`へ収束し、現在の公式ドキュメントは`~/.codex/skills`を記載していません。`~/.codex/skills`を「現在の置き場所」と説明している解説は古い版に基づくものなので、新規に作るなら`.agents/skills`系に置くのが安全です。 ## Codex Skillsの有効化と設定 Skillsは登場当初、実験的機能として`~/.codex/config.toml`に次の設定を書いて有効化する必要がありました。 ``` [features] skills = true ``` ただしこのフラグはバージョン依存で、現行の公式ドキュメントは有効化フラグを前提にしておらず、近年の版では既定で有効な場合があります。使っているCodex CLIの版に合わせて確認してください。特定のスキルを無効化・設定したい場合は、同じ`config.toml`に次のように書きます。 ``` [[skills.config]] path = "/path/to/skill/SKILL.md" enabled = false ``` `config.toml`やスキルを追加・変更した後は、Codexの再起動が必要です。 ## SKILL.mdの書き方とスキルの作り方 ### フロントマターはnameとdescriptionのみ YAMLフロントマターに書けるのは`name`と`description`の2つだけで、公式のskill-creatorは「フロントマターに他のフィールドを含めない」と明記しています。`version`や`license`、`allowed-tools`は書きません。`name`は英小文字・数字・ハイフンで64文字未満とし、スキルの親フォルダ名に一致させます。`description`には公式に明確な字数上限はありません（実装上は概ね1,024文字が目安）が、ここに「どんなときにこのスキルを使うか」という起動条件を書きます。マッチ判定に使われるのはこのdescriptionだけなので、ここが曖昧だとスキルが呼ばれません。 ### Markdown本文に手順を書く 本文は起動後に読み込まれる手順書です。抽象的な説明より、実行する手順・判断基準・してはいけないことを具体的に書きます。最小構成は次の形です。 ``` --- name: release-notes description: リリースノートを作成するときに使う。直近のマージ済みPRから変更点を分類し、ユーザー向けの文章に整える。 --- # Release Notes 1. gh pr list --state merged で対象PRを取得する 2. 変更を「新機能 / 修正 / 破壊的変更」に分類する 3. 各項目を1行の日本語で要約する ``` ### scripts・references・assetsで分割する 手順が長くなるときは、詳細を`references/`のファイルに逃がし、`SKILL.md`本文からは要点だけ参照させます。実行を伴う処理は`scripts/`に置きます。Progressive Disclosureを活かし、SKILL.md自体を薄く保つのがコンテキスト節約のコツです。 ## Codex Skillsの使い方：作成から呼び出しまで 実際にスキルを作って動かす最短の流れは次のとおりです。プロジェクト用なら`.agents/skills`、個人用なら`~/.agents/skills`にフォルダを作ります。 ``` mkdir -p .agents/skills/release-notes # SKILL.md を作成して保存 codex --list-skills # 認識されたスキル一覧を確認 ``` 登録したスキルの呼び出しには3つの経路があります。 - **一覧から選ぶ**：CLIやIDEの`/skills`セレクタで登録済みスキルを一覧・選択する。 - **明示的に指定**：`$`に続けてスキル名を書く（例：`$release-notes 直近のPRからリリースノートを作って`）。 - **暗黙的に起動**：プロンプトがdescriptionにマッチすれば、名前を書かなくても自動で選ばれる。 導入初期は挙動を把握するため、`$スキル名`で明示的に呼ぶ運用から始めると安全です。ゼロから雛形を作るなら、組み込みの`$skill-creator`が対話的に作成を案内してくれます。 ## おすすめのCodex Skillsと入手先 自作する前に、公開されているスキルを試すのが近道です。入手先は主に2つあります。 - **openai/skills**：公式カタログ。スキル作成を案内する`skill-creator`、GitHubから導入する`skill-installer`、Claude Code資産を移行する`migrate-to-codex`などを含みます。 - **ComposioHQ/awesome-codex-skills**：実用スキルのキュレーション集。gh-fix-ci、gh-address-comments、codebase-recon、meeting-notes-and-actions、changelog-generatorなどが揃っています。 awesome-codex-skillsからは、次のコマンドで個別スキルを取り込めます（スキル名は取得したいものに置き換えます）。 ``` python skill-installer/scripts/install-skill-from-github.py --repo ComposioHQ/awesome-codex-skills --path [skill-name] ``` ## Codex Skills・Claude Code Skills・MCPの違い 混同しやすい3つを整理します。SkillsとMCPは競合ではなく役割が異なります。 | 項目 | Codex Skills | Claude Code Skills | MCP | | ------ | ---------------------- | ------------------ | ---------- | | 正体 | 手順の束（Markdown＋任意スクリプト） | 手順の束（同一標準） | ツール接続プロトコル | | 配置 | `.agents/skills` | `.claude/skills` | サーバ設定 | | ファイル形式 | `SKILL.md` | `SKILL.md`（互換） | コード実装 | | 読み込み | 段階開示 | 段階開示 | 実行時に呼び出し | Skillsは「やり方（手順・知識）」をエージェントに教える仕組みで、MCPは「外部の道具（ライブAPIやサーバ）」をエージェントに使わせる仕組みです。定型の作業手順を再利用したいならSkills、SlackやデータベースなどのライブなツールへつなぎたいならMCPを選びます。CodexとClaudeは同じ`SKILL.md`形式のため、Claude向けスキルは`migrate-to-codex`で持ち込めますが、Claudeが許す`allowed-tools`のような追加フィールドはCodexでは使わない点に注意します。 ## 導入前に押さえる制約と注意点 効果を出すうえで、次の落とし穴を先に潰しておくべきです。 - **索引を圧迫しない**：スキルの索引は最大2%または8,000文字。descriptionを長く書きすぎたり、使わないスキルを大量登録すると索引が溢れ、必要なスキルが起動しなくなります。 - **フロントマターは厳格**：`name`・`description`以外を書くと想定外の挙動になります。 - **再起動を忘れない**：スキル追加や`config.toml`編集は再起動後に反映されます。 - **スクリプトはサンドボックス下**：`scripts/`の実行はCodex通常の承認・サンドボックスモデルに従います。無条件に任意コマンドが走るわけではありません。 - **版差に注意**：配置場所（`~/.codex/skills`→`.agents/skills`）や有効化フラグの要否は版で変わってきました。手順は使用中のCLI版を基準に確認します。 ## よくある質問 ### Codex Skillsの配置場所はどこですか？ 現行仕様では、プロジェクト用が`.agents/skills`、個人用が`$HOME/.agents/skills`、管理者用が`/etc/codex/skills`です。Codexはカレントディレクトリからリポジトリルートまで`.agents/skills`を探索します。 ### 有効化に実験フラグは必要ですか？ 登場初期は`~/.codex/config.toml`に`[features] skills = true`を書く必要がありました。ただしバージョン依存で、近年の版は既定で有効な場合があります。使用中のCLI版で確認してください。 ### \~/.codex/skills はもう使えませんか？ `~/.codex/skills`はリリース当初の置き場所で、現在は`.agents/skills`系に移っています。互換のため一部の版では読まれる可能性はありますが、新規に作るなら`.agents/skills`に置くのが確実です。 ### Claude CodeのスキルとSKILL.mdは互換ですか？ どちらも同じAgent Skills標準の`SKILL.md`形式です。公式の`migrate-to-codex`スキルで移行できます。ただしCodexのフロントマターは`name`・`description`のみで、Claudeにある追加フィールドは使いません。 ### SKILL.mdのdescriptionには何を書けばよいですか？ 「どんなときにこのスキルを使うか」という起動条件を簡潔に書きます。公式に明確な字数上限はありません（実装では概ね1,024文字が目安）が、スキルのマッチ判定にはこのdescriptionだけが使われるため、対象タスクを具体的に書くほど正しく起動します。 ## 関連記事 - [Claude Codeのスキルで業務と動画編集を自動化する活用法・作成手順【2026年最新】](/tech/details/12534/) - [Codexサブエージェントの仕組みと従来の単一エージェント実行との根本的な違い](/tech/details/11463/) - [OpenAI最新AIモデル「GPT-5.3-Codex」とは何か？概要と主な特徴・最新進化を徹底解説](/tech/details/10905/) - [Codexの音声入力とは？App・CLIの2系統と設定方法・Windows対応を解説【2026年版】](/tech/details/12799/) --- 出典: [Codex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】]()（株式会社一創）