Codex Skillsとは？作り方・置き場所・使い方を非エンジニア向けに解説

「Codexに頼むたびに、同じ手順や注意点を打ち込んでいる」「毎回少しずつ言い方が変わって、仕上がりがそろわない」と感じている方は多いのではないでしょうか。うまくいった頼み方があっても、次の日には思い出せないことがあります。

Codexのスキル（Skills）を使うと、よく使う手順や出力の形を1つのフォルダにまとめておき、必要なときだけCodexに読み込ませることができます。$を付けて名前を呼び出すことも、依頼の内容に合わせてCodexに自動で選ばせることもできます。

この記事では、スキルの仕組み、AGENTS.mdやプラグインとの違い、最初のスキルの作り方、置き場所と呼び出し方、設定、うまく動かないときの対処までを順に解説します。内容は2026年10月時点のOpenAI公式ドキュメントにもとづいています。

Codexのスキルとは

手順をまとめた「取扱説明書」

公式ドキュメントでは、スキルを「指示・資料・必要に応じたスクリプトをひとまとめにした、作業の手順書」と説明しています。Codexはこれを読むことで、毎回同じ流れで作業を進められます。「月次報告のメモを決まった形式に整える」「リリース前の確認項目を順に実行する」といった、くり返しの仕事に向いています。

スキルの実体は、SKILL.mdというファイルが入ったフォルダです。名前と説明、そして手順を書けば、最小限のスキルになります。

必要なときだけ読み込まれる

スキルは、最初から全文がCodexに渡されるわけではありません。公式の説明では、次の順に読み込まれます。

1. 名前と説明だけを読むCodexは、入っているスキルの名前と説明の一覧（Codexではファイルの場所も含む）を最初に把握します。
2. 使うスキルを決める依頼の内容がスキルの説明に合っていれば、そのスキルを選びます。自分で名前を指定することもできます。
3. SKILL.mdの全文を読む選ばれたスキルだけ、手順の本文を読み込みます。
4. 必要なら資料やスクリプトを使うreferences/やscripts/の中身は、手順の中で必要になったときに使われます。

この仕組みのおかげで、スキルをたくさん入れても、毎回の会話が長い指示で埋まることはありません。ただし、最初に読む一覧にも上限があり、多すぎると説明が短く切られたり、一部のスキルが一覧から外れたりします。詳しくは「うまく動かないとき」で説明します。

使える場所

公式のBuild skillsのページでは、単体のスキルを使える場所としてChatGPTのデスクトップアプリ、Codex CLI、IDE拡張機能が挙げられています。デスクトップアプリでは、サイドバーの「Skills」から、各プロジェクトで作られたスキルを一覧できます。

スキルは、ChatGPTのChat・Workでも使える共通の仕組みとして説明されています。ChatGPT側では@、Codex側では$でスキルを指定します。この記事ではCodexでの使い方を中心に扱います。

AGENTS.md・プラグインとの違い

Codexには、動きを調整する仕組みがいくつかあります。公式のCustomizationのページでは、これらを「競合するものではなく、組み合わせて使うもの」と説明しています。役割の違いを表にまとめます。

AGENTS.mdとの使い分け

公式のCustomizationのページによると、AGENTS.mdは「毎回守ってほしいルール」を書く場所です。ビルドやテストのコマンド、レビューで見るべき点、リポジトリ固有の決まりなどが例に挙がっています。

スキルは「その作業をするときだけ読んでほしい手順」を書く場所です。AGENTS.mdにリリース手順の全部を書くと、関係のない作業でも毎回読み込まれてしまいます。常に守ることはAGENTS.md、特定の作業の流れはスキルと分けると整理しやすくなります。

カスタムプロンプトは非推奨になった

以前は、Markdownファイルを~/.codex/prompts/に置いて、/prompts:名前で呼び出す「カスタムプロンプト」がありました。公式ドキュメントでは、これは非推奨とされ、再利用したい指示にはスキルを使うよう案内されています。

カスタムプロンプトは、自分で呼び出したときだけ動き、リポジトリでは共有されませんでした。スキルは、リポジトリに置いてチームで共有でき、Codexが自動で選ぶこともできます。すでにカスタムプロンプトを使っている場合は、スキルに書き直すのが公式の方針です。

スキルの作り方

公式ドキュメントでは、スキルの作り方として次の3つが紹介されています。

$skill-creatorで作る

Codexには、スキルを作るためのスキル「skill-creator」が最初から入っています。使い方は簡単で、Codexの入力欄に次のように書きます。

$skill-creator

公式の説明では、skill-creatorは「何をするスキルか」「いつ使うか」「スクリプトを含めるか」を質問してきます。初期状態では、スクリプトを含まない、指示だけのスキルになります。まずは指示だけで作り、必要が出てからスクリプトを足す方が安全です。

1. 作る仕事を1つに絞る「月次報告のメモ整形」のように、1つのスキルには1つの仕事だけを決めます。
2. $skill-creatorを呼び出す入力欄に$skill-creatorと書き、続けて、やりたいことを書いて送ります。
3. 質問に答える何をするスキルか、どんなときに使うかを答えます。良い出力の例や、使うテンプレートがあれば添えます。
4. できあがったSKILL.mdを読む手順が自分の考えと合っているかを確認し、足りない点は会話で直してもらいます。
5. 実際の依頼で試す本番に近い依頼で動かして、手順の抜けや出力の形のずれを確認します。

SKILL.mdを手で書く

手で作る場合は、フォルダを作って、その中にSKILL.mdを置きます。公式に載っている最小の形は次のとおりです。

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Skill instructions for ChatGPT or Codex to follow.

先頭の---で囲まれた部分が、名前と説明です。その下に、Codexに従わせたい手順を書きます。公式のCustomizationのページには、次のような例が載っています。

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

説明（description）は「何をするか」に加えて「どんなときに使うか」を書きます。Codexは、この説明を見て、自動で使うかどうかを判断するためです。

手順を見せて作る（Record & Replay）

「言葉にするより、やって見せる方が早い」という作業には、Record & Replayがあります。公式ドキュメントによると、Macで、Computer Useが使える状態のときに利用できる機能です。デスクトップアプリの「Plugins」から「+」メニューを開いて「Record a skill」を選び、画面で作業を見せると、Codexが手順書を下書きします。

公式のヒントとして、短く完結した操作を見せること、秘密情報や機微なデータを使わないこと、録画のあとに命名規則などの「見えない好み」を書き足すことが挙げられています。公式の説明はMac向けのもので、Windowsで使えるかどうかは記載がありません。

置き場所と呼び出し方

スキルを置ける場所

Codexは、次の4種類の場所からスキルを読み込みます。リポジトリの場合、いま作業しているフォルダから、リポジトリの一番上のフォルダまでの各階層にある.agents/skillsが対象です。

公式の説明では、スキルのフォルダへのシンボリックリンクもたどって読み込まれます。また、同じ名前（name）のスキルが複数ある場合、Codexはそれらを統合せず、どちらも選択画面に表示されます。

Windowsでの個人用フォルダの具体的な場所は、公式のこのページには書かれていません。公式の表記は$HOME/.agents/skillsです。

呼び出し方

スキルの使い方は2通りあります。

CLIで/skillsを実行すると、使えるスキルが一覧で表示され、選ぶと次の依頼がそのスキルの手順に従って進みます。公式の説明では、IDE拡張機能でも/skillsか$で指定できます。

スキルを追加する

自分で作る以外に、すでにあるスキルを入れる方法もあります。

• $skill-installerで入れる：公式が用意したスキル集（openai/skills）から入れられます。たとえばLinearのスキルなら$skill-installer linearと書きます。ほかのリポジトリのスキルを入れるよう頼むこともできます。
• プラグインで入れる：プラグインを入れると、中に含まれるスキルも使えるようになります。Codex CLIでは/pluginsでプラグインの一覧を開きます。
• Claude Codeなどから取り込む：デスクトップアプリの設定、またはCLIの/importから、Claude CodeやCursorで使っているスキルを取り込めます。

新しく入れたスキルはCodexが自動で検出します。表示されない場合はCodexを再起動してください。取り込んだ内容は、使う前に確認します。取り込んだスキルに付いているツールの制限や権限は、公式でも見直すよう案内されています。

業務で使えるスキルの例

スキルは、プログラムを書く人だけのものではありません。Codexは、フォルダの中の文書やデータを読み書きできます。くり返す事務作業も、スキルにすれば毎回同じ形で進められます。以下は、スキルにしやすい仕事の例です。

例：議事メモを報告書の形に整えるスキル

総務の担当者が、会議のメモを社内の報告書の形に整えるスキルを作る場合の例です。以下の内容は、この記事のために作った例で、公式のものではありません。フォルダ名や項目は、自社に合わせて書き換えてください。

---
name: meeting-report
description: 会議のメモを社内の報告書の形に整える。ユーザーが「議事録にして」「会議のメモを報告書にして」と頼んだときに使う。メールの下書きや要約だけの依頼には使わない。
---

1. 指定されたメモのファイルを読む。ファイルが指定されていなければ、どれを使うか質問する。
2. 次の見出しで、です・ます調の報告書にする。
   - 開催日時・場所・参加者
   - 決定事項
   - 次にやること（担当者と期限を表にする）
   - 持ち越しの課題
3. メモに書かれていない情報（日付、担当者名など）は補わず、「記載なし」と書く。
4. 最後に、元のメモと食い違う可能性がある箇所を一覧にして知らせる。

この例では、descriptionに「使う場面」と「使わない場面」の両方を書いています。公式でも、説明には範囲と境界をはっきり書くよう勧められています。手順の3つ目のように、やってはいけないこと（情報を補わない）を書いておくと、仕上がりのずれが減ります。

書き方のコツ

公式のBest practicesから、書き方の要点を整理します。

設定・共有・社内での使い方

agents/openai.yamlで設定する

スキルのフォルダにagents/openai.yamlを置くと、表示や動作を設定できます。公式に載っている形は次のとおりです。

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"
policy:
  allow_implicit_invocation: false
dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

社外へ出すメールの作成のように、勝手に動かれると困るスキルは、allow_implicit_invocationをfalseにしておくと安心です。

スキルを無効にする

スキルを消さずに使わない状態にするには、~/.codex/config.tomlに次のように書きます。書き換えたあとは、Codexを再起動します。

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

公式のBuild skillsのページでは、pathにSKILL.mdのファイルを指定しています。一方、設定リファレンスでは、pathを「SKILL.mdを含むスキルのフォルダへのパス」と説明しています。うまく反映されないときは、どちらの書き方か確認してください。

チームで共有する

スキルを他の人に使ってもらう方法は、規模によって変わります。

公式では、フォルダに置く方法は「自分で作って試す」「リポジトリの中で使う」のに向いていて、他の人に配る場合はプラグインを使うよう案内されています。なお、プラグインはIDE拡張機能では使えず、デスクトップアプリかCodex CLIで入れる必要があります。

会社で使うときに決めておくこと

管理者向けの「Skill controls」のページでは、ChatGPTのワークスペースのスキル、パソコン上のフォルダに置くスキル、プラグインに入ったスキルは、それぞれ別の管理の仕組みを持つと説明されています。あるスキルを別の経路に移しても、所有者や共有の設定、コネクタの許可は引き継がれません。

• 誰がスキルを作り、誰が内容を確認するか
• どの場所（リポジトリ・個人・管理者）に置いてよいか
• 外部のスキルやプラグインを入れる前の確認手順
• スクリプトを含むスキルを、どの範囲で許可するか

スキルに会社の機密や個人情報を書き込まないことも大切です。SKILL.mdはただのテキストファイルで、リポジトリで共有すれば、そのリポジトリを見られる人全員に見えます。

うまく動かないとき

スキルが一覧に出ない、思ったとおりに使われない、といったときの確認点を、公式の説明にもとづいてまとめます。

上限の仕組み

公式の説明では、最初に読むスキルの一覧は、既定ではモデルの文脈の大きさの2％まで（文脈の大きさが不明な場合は8,000文字まで）です。多すぎるときは、まず説明を短くし、それでも収まらないとスキルの一部を一覧から外して警告を出します。

この上限は、最初の一覧だけに適用されます。Codexがスキルを選んだあとは、そのスキルのSKILL.mdを全文読みます。上限を変えたい場合はskills.max_context_tokensを設定でき、設定できる上限は10,000トークンです。

よくある質問

まとめ

スキルは、「いつもの手順をCodexに覚えさせておく」ための仕組みです。まずは、毎週やっている小さな作業を1つ選び、指示だけのスキルにしてみるのがおすすめです。使いながら説明と手順を直していくと、少しずつ仕事に合ったスキルになっていきます。

社内でスキルを共有する場合は、置き場所、確認の手順、扱ってよい情報の範囲など、決めることが増えます。INTERCREATE JAPANでは、Claude CodeやCodexの導入から、社内で使い続けられるルールと仕組みづくりまでをお手伝いしています。